[yusiwen]

What changed

• agent/truncate.go: the preview is now bounded by a token budget (TruncMaxTokens, 4000) beside
  the line and byte caps, keeps the tail (TruncTailLines, 20), and reports what it dropped:
  ... 18,431 of 20,000 lines omitted (4 mention an error, 9 a warning) .... The counts come from a
  regexp scan of the dropped lines. A single line larger than every bound is still clipped into a
  readable preview rather than producing an empty one.
• config: truncation.max_tokens and truncation.tail_lines, in DefaultConfig and in
  config.example.json; SetTruncationConfig takes the two new values and keeps its rule that zero or
  negative values never lower a bound.
• agent/truncate_test.go: rewritten around the new behaviour — the budget, the tail, the summary
  counts, the untouched small output, the enormous first line, and two pins (the estimator's inverse, and
  package defaults == config defaults).
• Docs: CODEBASE.md's truncation section, the example config's note, roadmap B6 → Delivered — [agent] Truncate tool output to a token budget, keeping head, tail and a summary #304
  (16 delivered, 22 not started, 40 total).

Why

The old preview measured bytes the model does not pay for and kept the head. On a failing command that is
exactly backwards: the evidence is at the end, and the head can be 50k tokens of build log. The token
budget is the bound that matters; the tail is where the failure is; the counts are what let a reader
decide whether to open the saved file at all.

The summary is deliberately not a model call: the output was already too large to keep, and paying a
second call to describe it would move the cost rather than remove it.

Verification

• go test ./... -count=1 → 16 packages ok; go vet and gofmt -l clean.
• Mutation check: the head budget replaced with the fixed byte cap → TestTruncateRespectsTheTokenBudget
  fails; restored, it passes.
• New tests: 9 in agent/truncate_test.go, including the control (an output inside every bound is
  returned byte for byte, no file written) and TestBytesPerTokenMatchesTheEstimator.
• git log --format='%h %G? %s' → G.

Honest scope

• The summary counts lines, not causes: it says "4 mention an error", not "the build failed at step 3".
  That is the deliberate limit of a deterministic scan.
• The budget covers head and tail; the message and the file pointer add a small amount on top, which the
  test allows for explicitly.
• No per-tool budgets: one budget applies to every tool result.

Follow-ups

• B5 (context management strategies) and B4 (repository index) remain the open entries in section B;
  [memory] Align the Hindsight adapter with a real deployment #302 owns the Hindsight adapter's contract.

Refs #304, #168