feat(interface): enforce aggregate candidate token limits

[drewstone]

Summary

• Add optional maxTotalTokens to AgentCandidateExecutionLimits with strict nonnegative safe-integer validation.
• Enforce accounted input plus output usage in both throwing and Zod refinement helpers.
• Carry required accountedInputTokens per router settlement call and usageWithinLimits on terminal settlement material.
• Aggregate settlement usage from accounted input tokens, while retaining raw input tokens for provenance.
• Update canonical fixtures, mutation tests, README, and a minor-release changeset.

Proof

• pnpm test — 9 workspace packages passed; Interface: 33 files / 415 tests.
• pnpm --filter @tangle-network/agent-interface check-types — passed.
• pnpm build — passed.
• pnpm run check:package-artifacts — checked 9 packages, 26 exports, 52 targets.
• pnpm exec changeset status --since=origin/main — Interface minor; dependent packages patch.
• git merge-tree --write-tree origin/main HEAD — clean.

No downstream repositories or provider/model calls were changed.

[tangletools]

✅ Auto-approved drewstone PR — 2479dd56

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-13T16:05:46Z}