v5.7.x: four reliability fixes from a multi-agent audit (frontend leak + 3 boundary hints)

[RobLe3]

Summary

Four independent reliability/UX fixes surfaced during a multi-agent audit running v5.7.1 against local OpenAI-compatible model backends. Each is small, single-concern, has direct pin tests, and does not introduce new abstractions or change semantics. Bundled in one PR because every fix is small and orthogonal — same shape as the accepted #29 bundle.

The fixes

1. web/modules/chat.js — bound chat live-card memory on long sessions

Three accumulation sites grew monotonically: record.items per task (unbounded push, dedupe-against-last only), the matching DOM nodes under record.timelineEl, and finished-task records in liveCardRecords (intentionally retained for chat history).

The dedupe-against-last fails on interleaved retry storms (e.g. alternating provider_incomplete_response + llm_usage events during a stuck-round LLM loop) — a single wedged round can push hundreds of timeline rows. Added MAX_LIVE_TIMELINE_ITEMS=200 and MAX_LIVE_CARD_RECORDS=100 caps with trimRecordItems(record) (shifts array + DOM + expandedLineKeys in lockstep) and evictOldestFinishedRecordIfFull() (only evicts finished records, removes the DOM node). Cards beyond the cap are reconstructed from progress.jsonl on page reload.

2. ouroboros/tools/registry.py — TOOL_ARG_ERROR signature hint

When the agent emits a tool call with an unexpected kwarg, missing required arg, or wrong arity, the dispatcher catches the TypeError and surfaces it as TOOL_ARG_ERROR. The bare exception message says no but doesn't say how — observed: data_write(force=True) looped without a recovery cue.

Added _format_handler_signature_hint(name, handler, err_msg) that enriches the catch site with a one-line "Valid args for : ()" reminder built from inspect.signature(handler). Triggers only on known kwarg/arity error shapes; any other TypeError raised inside a handler body gets the original message unchanged. Filters out ctx, *args, and **kwargs from the surfaced hint.

3. ouroboros/tools/git.py — _repo_write_commit dirty-tree resilience (port of #36)

PR #36 fixed the checkout-on-dirty-tree class in _repo_commit_push: when checkout fails, check if we're already on branch_dev; if yes, the failure is incidental (no-op-but-git-complained on a dirty tree where the dirty files ARE what's being committed) and we proceed to staging. The parallel checkout site at _repo_write_commit:1171 (the legacy "write one file + commit" path) still aborts on any checkout failure — same trigger, same shape, not covered by #36.

Ports the already_on_target check from _repo_commit_push to _repo_write_commit. Mechanically identical pattern; only the follow-up step changes (write+stage instead of stage cycle).

4. ouroboros/tools/shell.py — run_shell argv[0] tool-name hint (extends #37)

Smaller coder models emit malformed calls of the shape cmd=["run_shell", "cd /x && y"] — putting the literal tool name as argv[0]. subprocess returns ENOENT on the literal "run_shell" with the opaque message [Errno 2] No such file or directory: 'run_shell'. Observed: 3 identical malformed calls in one task before the agent gave up.

Same shape of fix as the merged SHELL_REGEX_HINT (#37) — boundary-level structured hint before subprocess returns its opaque error. Detects cmd[0] in {"run_shell", "shell"} and surfaces a SHELL_ARG_ERROR with a concrete suggestion: if cmd[1:] looks like a bash-string with shell metachars, suggest ["bash", "-c", "..."]; otherwise suggest dropping the tool name from argv.

Tests

• tests/test_chat_js_contracts.py (extended) — 4 new contract tests pin the constants, the trimRecordItems shape (array+DOM+expandedLineKeys lockstep), the eviction logic (only finished records, DOM removed), and the call-site wiring.
• tests/test_tool_arg_signature_hint.py (new) — 6 tests cover unexpected-kwarg, missing-required, multiple-values, suppression on unrelated TypeErrors, ctx-only handler, and **opts filtering.
• tests/test_repo_write_commit_dirty_tree.py (new) — 2 tests pin the resilience path and the legitimate-failure preservation.
• tests/test_shell_run_shell_argv0.py (new) — 5 tests cover the exact production shape, plain-argv shape, the "shell" alias, the existing builtin-rejection path (regression guard), and the lone-tool-name edge case.
• All 17 new tests + adjacent existing tests pass on this branch.

No behavior change

No new public APIs. No new env vars. No new dependencies. No semantic changes — every fix is recovery enrichment or boundary hardening at an existing site:

• (1) caps an unbounded structure; cards beyond the cap reconstruct from progress.jsonl (existing path)
• (2) error-message enrichment only; success path unchanged
• (3) extends merged fix(git): _repo_commit_push doesn't abort on dirty-tree with named paths #36 to its sibling site; happy path (clean checkout) unchanged
• (4) extends merged fix(tools): run_shell grep regex-escape hint for argv-mode failures #37 in shape; happy path (real binary in argv[0]) unchanged

Test plan

• CI green on this PR
• pytest tests/test_chat_js_contracts.py tests/test_tool_arg_signature_hint.py tests/test_shell_run_shell_argv0.py tests/test_repo_write_commit_dirty_tree.py -v → all green
• Existing test suite remains green
• Manual: noisy chat session does not balloon timeline DOM (verify via DevTools Memory tab)
• Manual: a run_shell(cmd=["run_shell", "..."]) call surfaces SHELL_ARG_ERROR with the bash-c suggestion
• Manual: a tool called with an unexpected kwarg surfaces the "Valid args for " hint
• Manual: a repo_write_commit on a dirty tree where the agent is already on branch_dev proceeds to write+stage (does not abort at checkout)

🤖 Generated with Claude Code