scout-ai 2.0.0 → 2.1.0

data/research/provenance-continuation-accounting.md

@@ -0,0 +1,255 @@
+# Provenance token accounting for continued conversations (design, not implemented)
+
+Step 3, Part 2 of the provenance-gap plan. Part 1 (provenance follows `job=`
+receipt edges) is done and validated; this document designs token accounting
+for continuation chains (Cortex `continue` jobs and any `chat_task` that
+follows a previously projected chat). No library code was changed for this
+design; probes live in `tmp/prov-cont/measure*.rb` and
+`tmp/cortex-continuation-accounting-probes.md`.
+
+All numbers below are measured on the real example chain unless marked
+otherwise. Jobs live under `/home/mvazque2/.scout/var/jobs/Cortex/continue/`.
+
+## Evidence
+
+### The example chain
+
+Three sequential continuations of one conversation, `fin_fixes_recon`
+(workspace copy not found in this environment, see Open questions):
+
+| job | result chat (`Default_<k>.chat`) | inference metas | pt sum |
+|-----|----------------------------------|-----------------|--------|
+| `c0b45189` | 445 messages, 1 `job=` marker, 147 metas | 147 | 6,297,210 |
+| `68b5b7fa` | 711 messages, 1 `job=` marker, 237 metas | 237 | 10,707,400 |
+| `80070846` | 60 messages, 1 `job=` marker, 20 metas  | 20  | 1,124,684 |
+
+Each result chat starts with its own `job=` meta marker followed by exactly
+that job's own new inferences (this is `Chat.project(self.short_path, result)`
+with `result = agent.current_chat - agent.start_chat`,
+lib/scout/llm/agent/workflow.rb:127-139, projection at
+lib/scout/llm/chat/process/meta.rb:410).
+
+### What the agent log actually contains (replay measured)
+
+`Default_80070846...chat.files/agent.chat` (the third, latest job):
+
+- 404 inference metas, 404 *distinct* `inference_id`s, 0 duplicated ids
+  (`tmp/prov-cont/measure41.rb`).
+- Organized in projected segments delimited by `job=` meta markers:
+  - segment `job=...c0b45189...chat`: 147 metas, pt 6,297,210,
+    timestamps 2026-09-02T20:32:48Z .. 21:53:59Z;
+  - segment `job=...68b5b7fa...chat`: 257 metas, pt 11,832,084,
+    timestamps 21:54:59Z .. 22:48:55Z
+    (`measure43.rb`, `measure47.rb`).
+- The last segment is MIXED: 257 = 237 inferences authored by job
+  `68b5b7fa` + 20 authored by `80070846` itself. There is no marker between
+  the second job's projected result and the third job's own new turns; the
+  third job appended its turns after `start_chat.follow chat`
+  (lib/scout/llm/agent/workflow.rb:85-87) of the projected second result.
+- `Default_68b5b7fa...files/agent.chat`: 384 metas, all inside the
+  `job=c0b45189` segment (147 replayed + 237 own new, unmarked).
+- `Default_c0b45189...files/agent.chat`: 147 unmarked metas, nothing replayed.
+
+So: a continuation log carries the entire grown conversation; every replayed
+inference retains its original per-call token fields (`pt`, `ct`, `tt`,
+`cct`, `cwt`, `rt`, plus cumulative `*_c` and session `*_s` keys, all 404
+rows), original `inference_id`, `provider_response_id` and `timestamp`.
+
+### Inference identity is stable across copies
+
+Shared `inference_id`s between the second and third logs: 384; token-field
+(`pt/ct/tt/cct`) mismatches among them: 0 (`measure39.rb`). The third log's
+inherited rows sum to pt 17,004,610 / cct 16,288,896, byte-identical totals
+to the second job's own log content. Identity, not position, is the reliable
+key.
+
+### Traversal already reaches the whole chain
+
+`Chat.provenance_chat_files(third result chat)` returns 6 files: the three
+result chats plus the three `.files/agent.chat` logs (`measure44.rb`), via
+the `job=` marker edges (Part 1). Per-call meta keys observed in the third
+log, all 404 rows: `inference_id`, `timestamp`, `provider_response_id`,
+`pt/ct/tt/cct/cwt/rt`, `pt_c...rt_c`, `pt_s...rt_s`, plus `reas` on 12 rows.
+
+## Current behavior (measured)
+
+`Chat.provenance_token_totals(root)` (lib/scout/llm/chat/provenance.rb:729)
+collects per-inference events (`provenance_token_events`, line 499),
+deduplicates them by identity (`[:inference_id, id]`, else
+`provider_response_id`, else lineage, else receipt address; lines 577-608),
+then sums the canonical event's tokens (lines 706-708).
+
+Measured per-root totals (`measure44.rb`):
+
+| root | pt | interpretation |
+|------|----|----------------|
+| `c0b45189` | 6,297,210 | own only |
+| `68b5b7fa` | 17,004,610 | cumulative: own 10,707,400 + first's 6,297,210 |
+| `80070846` | 18,129,294 | cumulative: own 1,124,684 + 17,004,610 |
+
+Verdicts:
+
+1. Global deduplicated total does NOT double count. 18,129,294 =
+   6,297,210 + 10,707,400 + 1,124,684 exactly. Replayed copies of the same
+   inference in later logs collapse onto one event; the code's `next if
+   meta[:job]` filters (lines 534, 557) plus identity grouping do their job.
+2. Per-job root totals ARE cumulative. A continuation job's root total
+   includes every ancestor inference, so summing per-root totals across a
+   chain double counts (6,297,210 would be counted three times), and a
+   naive per-job cost read overstates job `68b5b7fa` by 6.3M pt. Today
+   there is no per-job "owned" breakdown: scope symbols
+   (`:deduplicated_total`, `:chat_evidence`, `:receipt_evidence`,
+   `:receipt_only`, lines 737-750) partition evidence coverage, not authorship.
+3. Re-send cost is present but unseparated. The third job's own 20 calls
+   cost pt 1,124,684 with cct 1,028,352 (91.5% of prompt tokens served from
+   cache; uncached prompt = pt - cct = 96,332). Per-call `pt` already
+   includes re-sent history for every call, which is the honest provider
+   view, but nothing at job level separates "what this job authored" from
+   "history this job re-paid for".
+4. Degraded case (missing child `81e265cf`): root
+   `Planned/work/Default_de207a52...chat` totals pt 37,969,140 with 2
+   warnings, both `unresolved_job_reference` for
+   `Cortex/continue/Default_81e265cf...chat` (file absent on disk). The
+   parent's log carries that job's projected segment with 0 inference metas
+   (its result was an exception receipt), so nothing is silently counted or
+   lost; the missing job's own cost is simply unknown, reported only as a
+   warning.
+
+## Attribution rules
+
+Core rule: **an inference belongs to exactly one job - the job that issued
+the model call - and its tokens are attributed to that job only; any other
+copy of the same `inference_id` is evidence, never a second charge.**
+
+1. Ownership set of a job J = the `inference_id`s of the inference metas in
+   J's persisted result chat (for `chat` result-type jobs, `job_result_chat_file`,
+   provenance.rb:83). Measured: this reproduces the exact deltas above
+   (147 / 237 / 20).
+2. Fallback ownership (result chat absent, e.g. non-chat jobs or pruned
+   results): inference metas in J's own logs (`direct_job_chat_files`,
+   provenance.rb:44) whose `timestamp` >= J's start time. Measured: job
+   `68b5b7fa` issued 2026-09-02T21:54:53Z; the 237 rows with
+   `timestamp >= issued` equal its result-chat set exactly (set difference 0).
+3. Rows in J's logs belonging to other jobs are labeled inherited, with
+   provenance `{owning job id -> count}` derived from the `job=` segment
+   markers around them; they never enter J's owned sums.
+4. Global total = sum over distinct `inference_id`s (unchanged; already
+   correct today). Per-job owned totals must sum to the global total when
+   the chain is complete; the residual (global - sum of known owners) is
+   attributed to `unknown`, driven by missing jobs.
+5. A missing job referenced by a receipt keeps its `unresolved_job_reference`
+   warning; its contribution is reported as `missing`, never as zero-owned
+   and never dropped from the residual.
+
+## Continuation-point detection
+
+Three independent signals, used in this priority:
+
+1. **Inference identity** (primary). `inference_id` is unique per call and
+   stable across copies (0 token-field mismatches over 384 shared ids).
+   Ownership from the result chat (Attribution rule 1) needs no markers at
+   all and survives arbitrary re-projection.
+2. **Timestamps** (secondary/corroborating). Every inference meta carries
+   `timestamp`; job issue time bounds the owned set. Use to cross-check rule
+   1 and to recover ownership when a result chat is missing. Measured
+   boundary in the chain: first's rows end 21:53:59Z, second starts 21:54:59Z,
+   second job issued 21:54:53Z.
+3. **`job=` segment markers** (structural, not authoritative). Markers delimit
+   projected segments and are what the traversal follows, but the FINAL
+   segment of a continuation log mixes the parent's projected result with the
+   current job's own turns (measured: 257 = 237 + 20). Therefore markers
+   alone can only give an upper bound on inherited content; they must not be
+   the sole attribution mechanism. Markers are also where duplicate/cycle
+   safety and re-projection idempotence already live
+   (`Chat.project` `seen_inference` guard, meta.rb:410-431).
+
+## Cost vs content (honest cost model)
+
+Two quantities must both stay visible and stay distinct:
+
+- **Authored (content) cost**: tokens of inferences the job itself issued.
+  Report per job: owned `{pt, ct, tt, cct, cwt, rt}` over its owned set.
+- **Re-send (transmission) cost**: history re-paid on each of the job's own
+  calls. It is already inside per-call `pt`; surface it as a derived view per
+  job: `uncached_prompt = sum(pt) - sum(cct)` over owned calls, plus
+  `cache_read = sum(cct)`, `cache_write = sum(cwt)`. Example, job `80070846`:
+  pt 1,124,684, cache_read 1,028,352, uncached 96,332 - the continuation was
+  cheap precisely because history was cached, and that is now legible.
+- Do NOT hide re-send by subtracting history tokens from per-call `pt`: each
+  call really did pay its prompt; the cache fields carry the discount.
+- Do NOT add inherited rows into the job's cost "because they were sent":
+  they were paid inside the job's own calls' `pt` already; adding them again
+  is exactly the double count being removed.
+- Cumulative keys (`pt_c` etc.) stay out of all sums; they are linear-chat
+  checkpoints (`Chat.meta`, meta.rb:140-160), not per-call evidence.
+
+## Safety (dupes / cycles / degraded)
+
+- **Duplicate inference copies**: already handled by identity grouping in
+  `provenance_token_events`; the attribution layer only adds an owner label
+  per event, so a row replayed into N logs is still one event with N
+  evidence records.
+- **Conflicting token fields across copies**: existing conflict machinery
+  (immutable core `pt/ct/tt` + distinct `provider_response_id`, lines
+  632-662) stays authoritative; ownership never overrides a conflict, and
+  `strict:` keeps raising.
+- **Cycles / self-edges**: traversal visited-set (`provenance_key`, lines
+  227-231) and the sidecar root-copy exclusion (`direct_chat_sidecar_files`,
+  provenance.rb:68-76) already prevent infinite recursion and self-duplication.
+- **Mixed final segment**: attribution by identity/timestamp (not markers)
+  is immune; if both identity and timestamps were missing, fall back to
+  markers and flag the final segment as `ambiguous_tail` rather than
+  guessing.
+- **Missing jobs**: unresolved receipt references produce warnings (measured
+  2 for `81e265cf`); attribution reports the job as `missing` with its
+  reference, and the residual accounting keeps global honesty (unknown, not
+  zero).
+- **Log inspectability**: unchanged. Nothing is trimmed from logs; only the
+  accounting view filters.
+
+## Future implementation surface (not implemented)
+
+- `lib/scout/llm/chat/provenance.rb`
+  - new `Chat.provenance_token_attribution(root, warnings: nil, **opts)`:
+    reuse `provenance_token_events` (no new traversal), then resolve owners:
+    per job node from the same traversal, owned set = inference ids in
+    `job_result_chat_file` (fallback: log metas with `timestamp >= job
+    start`, from `Step#started`/info), inherited counts from `job=` markers.
+  - optional `scope: :owned` (or `attribution:` keyword) on
+    `provenance_token_totals` that filters events by owner == root job.
+- Data shape: hash keyed by job path:
+  `{owned: {pt:, ct:, tt:, cct:, cwt:, rt:, uncached_prompt:, cache_read:},
+    inferences: n, inherited: {job_id => count}, missing: [refs],
+    ambiguous_tail: bool, warnings: [...]}`.
+- CLI: `scout llm prov --tokens=owned` (and an `--attribution` table view),
+  reusing the existing totals plumbing.
+- Flag/feature name suggestion: `token_attribution` (no env/config knob
+  needed; it is a view, not a change of evidence collection).
+- Tests would mirror `test/scout/llm/chat/test_agent_meta_tokens.rb` with
+  fixture chats containing projected segments, a mixed final segment, a
+  missing referenced job, and a re-projected chat.
+
+## Open questions
+
+- **Unverified** - `pt` semantics vs `cct`: whether `pt` includes cached
+  tokens (provider convention) or excludes them. The uncached_prompt
+  derivation assumes inclusion; confirm against the API adapter code before
+  implementing.
+- **Unverified** - `fin_fixes_recon` workspace copy: not found under
+  `/bulk` or `/home` (only `.scout/tmp` chat copies exist); the design rests
+  on job artifacts only. If the Cortex store reappears, confirm its
+  conversation file carries the same projected segments.
+- **Unverified** - parentage claimed in the task brief (continuations as
+  children of `Planned/work 4bf865b6`): not measured; the measured structure
+  is a linear chain `c0b45189 -> 68b5b7fa -> 80070846` plus the separate
+  `de207a52 -> (missing) 81e265cf` case.
+- **Open** - job start time source for the timestamp fallback: `Step` info
+  fields vs file mtime vs first owned inference timestamp; pick the most
+  robust and document it.
+- **Open** - whether ownership should also attach to non-`chat` jobs whose
+  logs contain inference metas (e.g. `:json`/`:text` tasks that ran an
+  agent); the fallback rule covers them, but naming the owner for log-only
+  jobs needs a decision.
+- **Open** - should `receipt_only` and owned views be combined in one CLI
+  table, or kept separate reports to avoid the documented non-additivity of
+  the coverage scopes?

data/scout-ai.gemspec

@@ -2,11 +2,11 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: scout-ai 2.0.0 ruby lib
+# stub: scout-ai 2.1.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "scout-ai".freeze
-  s.version = "2.0.0".freeze
+  s.version = "2.1.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -52,6 +52,7 @@ Gem::Specification.new do |s|
     "doc/user/WritingChats.md",
     "lib/scout-ai.rb",
     "lib/scout/llm/agent.rb",
+    "lib/scout/llm/agent/attach.rb",
     "lib/scout/llm/agent/chat.rb",
     "lib/scout/llm/agent/delegate.rb",
     "lib/scout/llm/agent/iterate.rb",
@@ -152,6 +153,7 @@ Gem::Specification.new do |s|
     "research/prompt-strategies-analysis.md",
     "research/prov-verbosity-fix-notes.md",
     "research/provenance-analysis.md",
+    "research/provenance-continuation-accounting.md",
     "research/provenance-navigation-design.md",
     "research/synthesis-report.md",
     "research/tools-system-analysis.md",

data/scout_commands/llm/prov

@@ -17,12 +17,22 @@ Examine the provenance of a chat or workflow job
 $ #{cmd} [<options>] <filename>
 
 -h--help Print this help
--c--component Show per-component direct costs instead of aggregate totals
+-c--component Show per-component direct costs (direct=) instead of subtree evidence closures (evidence=)
 -f--flow Print a compact provenance flow
 -l--long Show full filesystem paths instead of abbreviated names
 -e--evidence List the deduplicated direct inference events and their evidence
 --dot* Write the flow as Graphviz DOT
 -p--plot* Render the flow as svg, png, or pdf
+
+Default-tree numbers are evidence= subtree-deduplicated closures: they overlap
+between nodes and are never per-part cost.  Job nodes add delta= (direct tokens
+of the persisted chat-typed result, the accounting delta).  The root footer
+always prints the authoritative deduplicated_total, in both modes; --component
+relabels the node numbers direct=.  cache= carries the cache-hit share of
+prompt (cct/pt); the root footer adds fresh= (prompt not served from cache,
+including cache_write) and cache_write= (Anthropic cache-write tokens).
+Per-job delta= values sum to the root total on continuation chains but not on
+general DAGs.
 EOF
 if options[:help]
   defined?(scout_usage) ? scout_usage : puts(SOPT.doc)
@@ -38,6 +48,12 @@ evidence = options.delete(:evidence)
 filename = ARGV.first
 raise MissingParameterException, :filename if filename.nil?
 
+# One parse-once cache for the whole CLI run (see
+# Chat.provenance_chat_load): the initial traversal, the token-event
+# collector and this script's own node computations then share a single
+# Chat object per resolved path.
+Chat.open_provenance_run_cache
+
 # A persisted Step always has an info sidecar. A .files directory alone is NOT
 # evidence: saved agent chats carry one too. Explicitly loading the Step after
 # this evidence check avoids treating every readable chat as a job.
@@ -103,18 +119,36 @@ chat_cache = {}
 direct_tokens = lambda do |key|
   node = nodes[key]
   if node[:kind] == :chat
-    chat = chat_cache[node[:path]] ||= Chat.load(node[:path])
+    chat = chat_cache[node[:path]] ||= Chat.provenance_chat_load(node[:path])
     Chat.token_totals([chat])
   else
     logs = edges.select { |e| e[:from] == key && e[:relation] == :log }
                 .collect { |e| nodes[e[:to]][:path] }.uniq
-    chats = logs.collect { |path| chat_cache[path] ||= Chat.load(path) }
+    chats = logs.collect { |path| chat_cache[path] ||= Chat.provenance_chat_load(path) }
     Chat.token_totals(chats)
   end
 rescue => error
   warnings << { error: error, kind: node[:kind], object: node[:object], relation: :tokens }
   Chat::TOKEN_KEYS.each_with_object({}) { |name, totals| totals[name.to_sym] = 0 }
 end
+# Per-job accounting delta: the direct tokens of the job's persisted
+# chat-typed result (Chat.job_result_chat_file).  This is the
+# receipt-defined accounting object - the new chat the job returned - so on a
+# continuation chain the per-job deltas sum to the root deduplicated_total
+# while every ancestor's evidence= closure stays cumulative.  Jobs whose
+# result is not chat-typed omit the field (nil, never zero).
+delta_cache = {}
+delta_tokens = lambda do |key|
+  return delta_cache[key] if delta_cache.key?(key)
+  node = nodes[key]
+  delta_cache[key] = if node[:kind] == :job
+    file = Chat.job_result_chat_file(node[:object])
+    file ? Chat.token_totals([chat_cache[Chat.provenance_path(:chat, file)] ||= Chat.provenance_chat_load(file)]) : nil
+  end
+rescue => error
+  warnings << { error: error, kind: node[:kind], object: node[:object], relation: :delta }
+  delta_cache[key] = nil
+end
 
 # ------------------------------------------------------------------
 # Receipt (agent_meta) evidence: delegated inference events embedded in
@@ -204,21 +238,52 @@ end
 # ------------------------------------------------------------------
 # Formatting helpers
 # ------------------------------------------------------------------
-def token_str(tokens)
+# `qualifier` names the total field after what it measures so a number can
+# never be read as a different quantity: `evidence` (default tree; subtree
+# deduplicated closure), `direct` (-c; per-component direct tokens),
+# `deduplicated_total` (root footer; the authoritative cost).  `events`
+# appends the deduplicated event count where it is already computed (the
+# footer), and `delta` inserts the job's result-chat delta right after it.
+#
+# Canonical field order, identical for node lines and the footer: qualifier
+# total, [delta=], then the prompt axis `prompt= cache=<abs>@<rate> [fresh=]
+# [cache_write=]`, then generation `cont= reason=`.  `footer: true` adds the
+# run-level economics (`fresh=`, `cache_write=`) that do not belong to a node
+# label.  The rate is always computed from RAW integer totals
+# (`100.0 * cct / pt`): humanized values round at K/M boundaries and would
+# corrupt boundary rates.  `cache=` prints whenever pt is positive, including
+# `cache=0@0.0%`; when pt is nil/0 the whole prompt axis is omitted (nothing
+# to partition).  A conflicting summed set can yield cct > pt; the raw ratio
+# is then printed unclamped and the footer caveat line is the guard that
+# labels such a figure best-effort.
+def token_str(tokens, qualifier: nil, events: nil, delta: nil, footer: false)
   parts = []
-  parts << "total=#{Misc.human_number(tokens[:tt])}" if tokens[:tt] && tokens[:tt].to_i > 0
-  parts << "prompt=#{Misc.human_number(tokens[:pt])}" if tokens[:pt] && tokens[:pt].to_i > 0
+  if tokens[:tt] && tokens[:tt].to_i > 0
+    value = Misc.human_number(tokens[:tt])
+    value += " (#{events} events)" if events
+    parts << "#{qualifier || 'total'}=#{value}"
+    parts << "delta=#{Misc.human_number(delta[:tt])}" if delta && delta[:tt].to_i > 0
+  end
+  pt = tokens[:pt].to_i
+  if pt > 0
+    cct = tokens[:cct].to_i
+    parts << "prompt=#{Misc.human_number(pt)}"
+    parts << "cache=#{Misc.human_number(cct)}@#{format('%.1f', 100.0 * cct / pt)}%"
+    if footer
+      parts << "fresh=#{Misc.human_number(pt - cct)}"
+      parts << "cache_write=#{Misc.human_number(tokens[:cwt].to_i)}" if tokens[:cwt] && tokens[:cwt].to_i > 0
+    end
+  end
   parts << "cont=#{Misc.human_number(tokens[:ct])}" if tokens[:ct] && tokens[:ct].to_i > 0
-  parts << "cache=#{Misc.human_number(tokens[:cct])}" if tokens[:cct] && tokens[:cct].to_i > 0
   parts << "reason=#{Misc.human_number(tokens[:rt])}" if tokens[:rt] && tokens[:rt].to_i > 0
   parts * ' '
 end
 
-def report_line(kind, label, tokens, offset: 0)
+def report_line(kind, label, tokens, offset: 0, qualifier: nil, delta: nil, events: nil)
   color = kind == :job ? :yellow : :green
   parts = [' ' * (offset * 2)]
   parts << Log.color(color, kind.to_s)
-  tok = token_str(tokens)
+  tok = token_str(tokens, qualifier: qualifier, events: events, delta: delta)
   parts << tok unless tok.empty?
   parts << Log.color(:blue, label.to_s) unless label.to_s.empty?
   parts * ' '
@@ -279,14 +344,34 @@ unless flow || dot_file || plot_file
     node = nodes[key]
     parent_node = parent_key ? nodes[parent_key] : nil
 
-    # Skip hidden nodes entirely — don't print, don't traverse children
-    return if hidden_node?(node, relation)
+    # Hidden nodes (result chats duplicating a job, top-level agent.chat
+    # logs) are not printed, but PROJECTION ONLY: the walk still descends
+    # through them so their children are attributed to the current display
+    # parent.  This is what makes delegated children of tree-hidden carrier
+    # chats visible without adding, removing or rewriting any traversal
+    # edge: the :agent_job/:job edges keep pointing at the carrier chat.
+    #   - no "printed" slot is consumed, so offsets stay as if the carrier
+    #     were not there
+    #   - children keep their own incoming relation (delegated-job label)
+    #   - the global `printed` set still dedups nodes discovered from
+    #     several carriers (first visit wins)
+    if hidden_node?(node, relation)
+      (adjacency[key] || []).each do |edge|
+        print_tree.call(edge[:to], offset, edge[:relation], parent_key)
+      end
+      return
+    end
 
     printed << key
     label = node_label(node, parent_node, root_key, key, long)
     # A job reached through an agent_meta receipt is a delegated producer.
     label = "delegated-job #{label}" if node[:kind] == :job && relation == :agent_job
-    puts report_line(node[:kind], label, node_tokens.call(key), offset: offset)
+    # Both modes: job nodes carry their accounting delta (in -c the
+    # direct=/delta= contrast on one line is the question the mode answers).
+    delta = node[:kind] == :job ? delta_tokens.call(key) : nil
+    puts report_line(node[:kind], label, node_tokens.call(key), offset: offset,
+                     qualifier: component ? 'direct' : 'evidence',
+                     delta: delta)
 
     # One compact annotation line for the delegated usage embedded in this
     # chat's own outputs; never one line per receipt.
@@ -309,6 +394,25 @@ unless flow || dot_file || plot_file
   end
   print_tree.call(root_key, 0, nil, nil)
 
+  # Root footer (BOTH modes): the one authoritative cost figure, always
+  # printed, so -c no longer lacks a global bound.  It carries the run-level
+  # economics (deduplicated event count, fresh=, cache_write=) that do not
+  # belong to a node label.  It reuses the root aggregate computed for the
+  # root node line, which IS the root :deduplicated_total (every deduplicated
+  # event once).  Identity conflicts demote it to best-effort; this footer
+  # caveat is the single home of the non-authoritative warning in both modes
+  # (the -c scope block no longer repeats it).
+  conflicts = {}
+  root_totals = Chat.provenance_token_totals(root, warnings: receipt_warnings, conflicts: conflicts)
+  puts Log.color(:cyan, 'root ') +
+    token_str(root_totals, qualifier: 'deduplicated_total',
+                       events: token_events_for.call.length, footer: true) + ' ' +
+    Log.color(:cyan, '(authoritative cost; per-node evidence=/direct= values overlap)')
+  unless conflicts[:authoritative]
+    puts Log.color(:red, 'unresolved identity conflicts: ') +
+      "#{conflicts[:events]} conflicting event(s); totals above are best-effort (canonical evidence only), not exact"
+  end
+
   # Component mode: make the evidence coverage behind the numbers explicit
   # once receipts are present; chats without receipts keep the previous output
   # exactly.  These are COVERAGE figures, not additive cost categories:
@@ -316,8 +420,7 @@ unless flow || dot_file || plot_file
   # both a saved child log and a receipt.  Only deduplicated_total is the
   # cost, and receipt_only is the disjoint delegated contribution.
   if component && has_receipt_evidence
-    coverage = [[:deduplicated_total, 'total'],
-                [:chat_evidence, 'events with saved chat/log evidence'],
+    coverage = [[:chat_evidence, 'events with saved chat/log evidence'],
                 [:receipt_evidence, 'events inside agent_meta receipts (overlaps chat_evidence)'],
                 [:receipt_only, 'receipt evidence with no saved chat/log']]
     coverage.each do |scope, note|
@@ -326,13 +429,6 @@ unless flow || dot_file || plot_file
       rendered = 'total=0' if rendered.empty?
       puts Log.color(:cyan, "evidence #{scope}:") + ' ' + rendered + ' ' + Log.color(:cyan, "(#{note})")
     end
-
-    conflict_info = {}
-    Chat.provenance_token_totals(root, warnings: [], conflicts: conflict_info)
-    unless conflict_info[:authoritative]
-      puts Log.color(:red, 'unresolved identity conflicts: ') +
-        "#{conflict_info[:events]} conflicting event(s); totals above are best-effort (canonical evidence only), not exact"
-    end
   end
 end
 
@@ -600,3 +696,7 @@ receipt_warnings.each do |warning|
     Log.warn "agent_meta receipt: #{warning[:reason]} in #{warning[:source]} at #{location.inspect} call=#{warning[:call_id]}#{warning[:message] ? ' - ' + warning[:message] : ''}"
   end
 end
+
+# End of the CLI run: drop the parse-once cache so a following run in the
+# same process (tests, embedded use) re-parses freshly.
+Chat.close_provenance_run_cache

data/test/scout/llm/chat/agent_meta_fixtures.rb

@@ -32,8 +32,14 @@ module AgentMetaFixtures
   end
 
   # JSON payload of a function_call_output envelope carrying agent_meta.
-  def receipt_output(call_id, agent_meta, name: 'ask', content: 'child answer')
-    {name: name, content: content, id: call_id, agent_meta: agent_meta}.to_json
+  # `envelope:` selects which serialized key carries the receipts:
+  # :agent_meta is the legacy envelope, :meta the current one written since
+  # the dual-envelope reader landed (lib/scout/llm/tools/call.rb).
+  # `name` only decorates the envelope; the receipt lifting ignores it.
+  def receipt_output(call_id, agent_meta, name: 'ask', content: 'child answer', envelope: :agent_meta)
+    payload = {name: name, content: content, id: call_id}
+    payload[envelope] = agent_meta
+    payload.to_json
   end
 
   # Persisted chat text with one paired ask call per receipt entry.  Hash keys
@@ -43,11 +49,13 @@ module AgentMetaFixtures
   # Message indexes produced by Chat.parse (single user turn, no leading
   # empty user message since 49c0d20):
   #   0 user, then per receipt: function_call, function_call_output.
-  def receipt_chat_text(receipts, extra: nil)
+  # `tool` sets the function_call name; receipts are lifted from the output
+  # envelope regardless of it, so tests can pin that no tool name is special.
+  def receipt_chat_text(receipts, extra: nil, envelope: :agent_meta, tool: 'ask')
     lines = ['user: Run the worker']
     receipts.each do |call_id, agent_meta|
-      lines << 'function_call: ' + %({"name":"ask","arguments":{},"id":"#{call_id}"})
-      lines << 'function_call_output: ' + receipt_output(call_id, agent_meta)
+      lines << 'function_call: ' + %({"name":"#{tool}","arguments":{},"id":"#{call_id}"})
+      lines << 'function_call_output: ' + receipt_output(call_id, agent_meta, envelope: envelope)
     end
     lines.concat(Array(extra)) if extra
     lines << 'assistant: done'
@@ -128,4 +136,82 @@ module AgentMetaFixtures
       "function_call_output: #{payload}\n" +
       "assistant: done\n"
   end
+
+  # Continuation-chain fixture (theme-2 A/B/C shape, in-repo).  Three
+  # chat-typed jobs A -> B -> C whose agent logs are cumulative histories
+  # (each carries the projected parent metas before its own), so per-root
+  # closures are cumulative while each job's own delta is disjoint.  Every
+  # meta line is a plain direct chat meta (not a receipt).
+  #
+  # Token plan (all figures arithmetically checkable):
+  #   A own: 3 metas pt=40 tt=50 cct=30 cwt=5  -> delta tt=150, pt=120, cct=90
+  #   B own: 2 metas pt=100 tt=120 (no cache)  -> delta tt=240, pt=200
+  #   C own: 1 meta  pt=0   tt=600 (pt missing)-> delta tt=600, pt=0
+  #   chain closure at C: 6 events, tt=990, pt=320, cct=90, cwt=15, ct=6
+  #   sum of deltas 150+240+600 = 990 == root deduplicated_total
+  #
+  # Also builds a TSV-typed job reached from `parent.chat` through a
+  # receipt, to pin delta= omission for non-chat results in both modes.
+  # Returns [a_job, b_job, c_job, tsv_job, parent_chat].
+  def continuation_chain(dir)
+    meta = lambda do |id, pt, tt, cct: 0, cwt: 0|
+      parts = ["pt=#{pt}", 'ct=1', "tt=#{tt}"]
+      parts << "cct=#{cct}" if cct > 0
+      parts << "cwt=#{cwt}" if cwt > 0
+      parts << "inference_id=#{id}" << 'timestamp=2026-09-04T00:00:00Z'
+      "meta: " + parts * ' '
+    end
+
+    a_metas = (1..3).collect { |i| meta.call("a#{i}", 40, 50, cct: 30, cwt: 5) }
+    b_metas = (1..2).collect { |i| meta.call("b#{i}", 100, 120) }
+    c_meta  = meta.call('c1', 0, 600)
+
+    a = make_job(dir, 'Cortex/continue/Default_a1', logs: {'agent.chat' => ''})
+    File.write(a + '.info', {dependencies: [], type: :chat}.to_json)
+    File.write(a, (['user: start'] + a_metas + ["meta: job=#{a}"]) * "
+" + "
+")
+    File.write(File.join(a + '.files', 'log', 'agent.chat'), a_metas * "
+" + "
+")
+
+    b = make_job(dir, 'Cortex/continue/Default_b2', logs: {'agent.chat' => ''})
+    File.write(b + '.info', {dependencies: [], type: :chat}.to_json)
+    File.write(b, (['user: continue B'] + b_metas + ["meta: job=#{b}"]) * "
+" + "
+")
+    File.write(File.join(b + '.files', 'log', 'agent.chat'),
+               (["meta: job=#{a}"] + a_metas + b_metas) * "
+" + "
+")
+
+    c = make_job(dir, 'Cortex/continue/Default_c3', logs: {'agent.chat' => ''})
+    File.write(c + '.info', {dependencies: [], type: :chat}.to_json)
+    File.write(c, (['user: continue C'] + [c_meta, "meta: job=#{c}"]) * "
+" + "
+")
+    File.write(File.join(c + '.files', 'log', 'agent.chat'),
+               (["meta: job=#{b}"] + a_metas + b_metas + [c_meta]) * "
+" + "
+")
+
+    # TSV-typed job (no chat result): must omit delta= while still showing
+    # its own log evidence.
+    tsv = make_job(dir, 'Other/step/Default_d4',
+                   result: "a	b
+1	2
+",
+                   logs: {'agent.chat' => meta.call('d1', 7, 8) + "
+"})
+    info = JSON.parse(File.read(tsv + '.info'))
+    File.write(tsv + '.info', {dependencies: info['dependencies'], type: :tsv}.to_json)
+
+    parent = write_chat(dir, 'parent.chat',
+                        receipt_chat_text(
+                          {'a1' => [meta_receipt("job=#{tsv}")]},
+                          extra: ['meta: pt=10 ct=1 tt=11 inference_id=p1']
+                        ))
+
+    [a, b, c, tsv, parent]
+  end
 end