fix: harden tool execution under load

[w0wl0lxd]

Summary

• cap batch fan-out at four calls and update generated docs/tests
• coalesce bash live-output publications while preserving bounded final output
• isolate compaction unit tests from real user PreCompact/PostCompact hooks
• install the required n00n-git companion binary and strengthen RTK pass-through coverage

Validation

• cargo nextest run --workspace — 5,230 passed, 4 skipped
• just fmt-check
• just lint
• targeted compaction, bash plugin, buffering, and pass-through tests

Audit notes

• no recent n00n OOM, segfault, coredump, or journal crash evidence
• recurring libz_sys warning is a non-fatal kache cache-key miss through curl/isahc

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added deferred callbacks with cancellation and cleanup support.
  • Added discovery and selection of nested model specifications.
  • Improved live shell output responsiveness with periodic updates and final flushing.
  • Added buffered tool-output handling for efficient updates.
• Bug Fixes
  • Batch operations now reject requests exceeding four tools before execution.
  • Improved restoration of oversized historical batches and preserved unmodified command output.
  • Prevented stale model refreshes from replacing newer selections.
• Documentation
  • Updated installation instructions, batch limits, Lua API documentation, and changelog entries.

Walkthrough

Changes

Tool execution responsiveness

Layer / File(s)	Summary
Deferred callback jobs n00n-lua/src/api/fn.rs, n00n-lua/tests/plugin_host.rs, site/docs/content/lua-api/_index.md	Adds timer-only jobs and the n00n.fn.defer API. Tests cover callback delivery, cancellation, ownership, and deadline handling.
Task cleanup and timeout replies n00n-lua/src/api/util/ctx.rs, n00n-lua/src/runtime.rs, n00n-lua/tests/plugin_host.rs	Adds handler cleanup callbacks, bounded cleanup execution, batched task-event delivery, and validated timeout markers.
Buffered shell output plugins/bash/init.lua, plugins/lib/n00n/tool_view.lua, plugins/lib/tests/spec.lua, site/docs/content/lua-api/_index.md	Buffers shell output and flushes it after 32 lines, one second, cleanup, or command completion.

Optional compaction hooks

Layer / File(s)	Summary
Compaction hook control n00n-agent/src/agent/compaction.rs, n00n-agent/src/agent/run.rs	Adds hook control to compaction and disables hooks for selected test paths.

Four-tool batch contract

Layer / File(s)	Summary
Batch limit and restore handling plugins/batch/init.lua, n00n-lua/tests/batch_policy.rs, site/docs/content/tools/_index.md, changelog.d/388.changed.md	Limits live batches to four calls, rejects oversized requests before dispatch, supports tool_calls and tool_uses, and preserves historical restore rendering.

Nested model selection

Layer / File(s)	Summary
Catalog-based model resolution n00n-ui/src/event_loop.rs, n00n-ui/src/components/model_picker.rs, changelog.d/388.fixed.md	Resolves discovered nested specifications during session loading and model changes. Refreshes publish only the latest catalog, and equal-sized model replacements refresh the picker.

Installation packages

Layer / File(s)	Summary
Installation command updates README.md, site/docs/content/quick-start/_index.md	Installation commands now include n00n-git and n00n-smell.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: 🟠 High · up to 684e8

The PR hardens tool scheduling, output buffering, deferred callbacks, and model/session handling, but the current code can still panic on oversized delays, restore sessions with the wrong model, hide discovered models, stall low-volume output after clock changes, or fail during plugin initialization. These concrete runtime and correctness risks should be fixed or explicitly accepted before merge.

Sequence Diagram(s)

sequenceDiagram
  participant LuaTool
  participant JobStore
  participant Task
  LuaTool->>JobStore: schedule deferred callback
  JobStore->>Task: emit Exit(0) after deadline
  Task->>LuaTool: invoke callback and finish tool

Loading

sequenceDiagram
  participant BashPlugin
  participant ToolView
  BashPlugin->>ToolView: append stdout and stderr to buffer
  BashPlugin->>ToolView: flush after 32 lines or 1 second
  BashPlugin->>ToolView: flush remaining output on completion

Loading

Possibly related PRs

• w0wl0lxd/n00n#62: Both changes modify ToolView buffering behavior and its tests.
• w0wl0lxd/n00n#125: Both changes modify live output handling in plugins/bash/init.lua.
• w0wl0lxd/n00n#336: Both changes modify runtime cancellation and deadline handling that supports cleanup callbacks.

Poem

A rabbit buffers shell lines in a queue,
Four tools hop safely where twenty-five flew.
Timers call back when their deadlines appear,
Cleanup runs once before tasks disappear.
Nested models refresh with catalog care. 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 58.62% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary changes that harden tool execution under load.
Description check	✅ Passed	The description directly explains the batch, output, compaction, installation, testing, and validation changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/0.6.0-smoke-audit

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 90.72682% with 74 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
n00n-ui/src/event_loop.rs	66.10%	40 Missing ⚠️
n00n-lua/src/api/fn.rs	96.33%	15 Missing ⚠️
n00n-lua/src/runtime.rs	95.02%	10 Missing ⚠️
n00n-agent/src/agent/compaction.rs	81.48%	5 Missing ⚠️
n00n-lua/src/api/util/ctx.rs	81.81%	2 Missing ⚠️
n00n-agent/src/agent/run.rs	85.71%	1 Missing ⚠️
n00n-ui/src/components/model_picker.rs	95.83%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

Criterion

Details

Benchmark suite	Current: d3707e7	Previous: 5cfa8b0	Ratio
fib/jit_mlua_hook	7940129 ns/iter (± 118454)	6707726 ns/iter (± 83618)	1.18
fib/jit_watchdog	1879529 ns/iter (± 11442)	2221382 ns/iter (± 11947)	0.85
fib/jit_none	1878016 ns/iter (± 51567)	2222207 ns/iter (± 61733)	0.85
fib/interp_mlua_hook	8830761 ns/iter (± 16067)	8587714 ns/iter (± 84701)	1.03
fib/interp_watchdog	3636735 ns/iter (± 5858)	4334411 ns/iter (± 25751)	0.84
fib/interp_none	3633423 ns/iter (± 11565)	4291570 ns/iter (± 13989)	0.85
buffer_rw/jit_mlua_hook	809063 ns/iter (± 3483)	584004 ns/iter (± 10201)	1.39
buffer_rw/jit_watchdog	110982 ns/iter (± 347)	192089 ns/iter (± 342)	0.58
buffer_rw/jit_none	110934 ns/iter (± 234)	191871 ns/iter (± 2518)	0.58
buffer_rw/interp_mlua_hook	1164781 ns/iter (± 26255)	1038181 ns/iter (± 11196)	1.12
buffer_rw/interp_watchdog	535841 ns/iter (± 1694)	585591 ns/iter (± 3888)	0.92
buffer_rw/interp_none	534910 ns/iter (± 1253)	584619 ns/iter (± 2938)	0.91
splash_render_120x40	67226 ns/iter (± 635)	55026 ns/iter (± 3645)	1.22
splash_render_200x60	119746 ns/iter (± 11117)	197504 ns/iter (± 5916)	0.61

This comment was automatically generated by workflow using github-action-benchmark.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[w0wl0lxd]

Resolved review findings in ad42e54:

• replaced callback-only wall-clock flushing with a deferred one-second flush job, preserving coalescing while keeping paused/bursty command output visible;
• removed the collector timing policy, eliminating wall-clock and ambiguous parameter concerns;
• rejected oversized batches before normalizing or preparing any entry;
• moved compaction-hook suppression behind test-only state so production carries no hook toggle;
• added n00n-smell to source-install instructions;
• documented ToolView:append_buffered and regenerated Lua API docs.

The batch cap of four is intentional for load hardening. Validation: 82 compaction tests passed; 334 changed n00n-lua tests passed; just fmt-check, just gen-docs-check, and just lint passed.

Dismiss stale CodeRabbit changes-requested review: all review threads are resolved and the latest CodeRabbit check passed on current head.

Stale CodeRabbit review; all threads are resolved and latest checks passed.

[devin-ai-integration]

Devin Review found 2 new potential issues.

[linear-code]

N00N-401