rubino-agent 0.5.0 → 0.5.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a3a48a6f7deb104446c624354a271ff1a1671c9b3ea846cee1144b3f55538db
-  data.tar.gz: cbc407cd78db827d75f150f61045b2cce759b266816e32fdba874c30eb3647c4
+  metadata.gz: 45e009503b875320e560be8ce46459d7c2a70b0c5744043b70f2121c5e747ab2
+  data.tar.gz: c26d1f586ae8578ed3d7298d1f7f8765d16ed5328b6d063d77e0df41d32a710a
 SHA512:
-  metadata.gz: 3342a4c8b1856691788ac9625b81eb4058870a0eb5a75946e99e6570ce40a05a7b44475a798863ac0fc92c9fcb505cf6caf27fcedc10a8e1bd9653ba18edf440
-  data.tar.gz: e54077b30f385942dd3591fb7e6c4e7afc0f301e5fea9d3111732c91ce56e63a4c7d192704ebd74ea97ee4a04437784d73a8d398bf02ce6143cdd69b2227a841
+  metadata.gz: dc1cfd93fb51e6236daf8e839a8df248fdcd299aef3028c258fefc93c585bf15e322b5d41ebf4d1b504795a9d24d6e8668f5dece2089b9454f6432dabcace482
+  data.tar.gz: 5495d4862d7b082826205ca4ecb30701df4a103ce801233df6a3dc91c59ce423ea4cb6cab4e41b9b0327f72e911ad310bf9433aaf6d218d8803bb0ffd56bec65

data/.rubocop.yml

@@ -27,6 +27,12 @@ AllCops:
     # Test fixtures are sample input documents (e.g. a .rb code sample for the
     # plain-text converter), not project source -- they must not be linted.
     - "spec/fixtures/**/*"
+    # Eval-harness fixtures are deliberately tiny/imperfect sample projects the
+    # agent edits at eval time (INPUT, not source); results/ is generated output.
+    # The eval/.rubocop.yml excludes these for an in-eval run; mirror it here so
+    # the whole-repo lint from the root is clean too.
+    - "eval/fixtures/**/*"
+    - "eval/results/**/*"
 
 # --- House style: strings ----------------------------------------------------
 

data/.rubocop_todo.yml

@@ -538,6 +538,7 @@ RSpec/DescribeClass:
     - 'spec/rubino/skills/skills_spec.rb'
     - 'spec/rubino/tools/edit_read_gate_spec.rb'
     - 'spec/rubino/tools/shell_background_spec.rb'
+    - 'spec/rubino/tools/shell_background_completion_spec.rb'
     - 'spec/rubino/tools/shell_input_spec.rb'
     - 'spec/rubino/tools/tool_fixes_spec.rb'
     - 'spec/rubino/ui/bottom_composer_approval_handoff_pty_spec.rb'

data/CHANGELOG.md

@@ -1,5 +1,393 @@
 # Changelog
 
+## [0.5.2.1] - 2026-06-26
+
+### Fixed
+
+- **Symlinked workspace roots broke three path checks.** Several modules compared
+  a symlink-resolved path against a NON-resolved root, so a workspace reached
+  through a symlink (macOS `/etc` → `/private/etc`, `/var` → `/private/var`, or
+  any symlinked checkout) defeated the match:
+  - **SecretPath** — `secret?("/etc/sudoers")` returned `false` and the
+    `~/.ssh`/`~/.aws`/… credential read-gate classified nothing, silently
+    no-op'ing the write-approval gate and read-block for those paths.
+  - **IgnoreRules** — `git rev-parse --show-toplevel` returns the realpath, so
+    the allowed-set rebase dropped *every* file and the whole tree read as
+    git-ignored; `grep`/`glob` then returned nothing under a symlinked checkout.
+  - **Skills::Registry** — an untrusted repo's project-local `.rubino/skills` was
+    not recognised as project-local, so the trust gate failed to drop it (hostile
+    project skills could load in an untrusted directory).
+
+  All three now resolve both sides of the comparison through `realpath` /
+  `canonical_path`. Defense-in-depth — not security boundaries.
+- **`grep` Ruby fallback now matches dotfiles.** Without ripgrep on PATH, the
+  fallback globbed `**/<include>` without `FNM_DOTMATCH`, so an include like
+  `*.env` never matched `.env`/`.envrc` — exactly the secret-bearing files. The
+  include glob now matches dotfiles, mirroring `rg --glob`.
+
+## [0.5.2] - 2026-06-26
+
+### Added
+
+- **Live formatted-markdown streaming.** The in-flight model stream now renders
+  as formatted markdown while it arrives (Stage 1), painted as atomic frames via
+  DEC-2026 synchronized output so a fast stream never tears mid-update (Stage 2),
+  with committed code blocks syntax-highlighted through Rouge (Stage 3). (#592,
+  #593, #594)
+- **Leaked tool-call recovery.** Models that emit a tool call as plain text or
+  garbled XML/JSON markup instead of a structured call (MiniMax-M3 and other
+  tool-loop models) now have those calls re-parsed into real `tool_calls` at the
+  transport layer so they actually execute, including a garbled `<invoke">`
+  variant.
+- **`write` content preview.** The `write` tool box now shows a preview of the
+  content being written.
+
+### Changed
+
+- Raise the default `max_tool_iterations` from 25 to 90 (Hermes-aligned), so long
+  tool-driven turns no longer hit the ceiling mid-task.
+- Teach the agent (via the build prompt) to read the compressed tool-output
+  markers introduced in 0.5.1.
+
+### Fixed
+
+- Render any unterminated code fence as a code box, matching CommonMark's
+  end-of-file fence auto-close, instead of leaking the raw backticks. (#595)
+- Merge consecutive same-role messages on the Anthropic-family wire so the
+  request shape stays valid. (#597)
+- Give MiniMax its full output ceiling so a long thinking block no longer starves
+  the visible output (a root cause of heavy-turn "invalid params" death).
+- Keep a 5xx-wrapped "invalid params" response on the retryable path.
+- Multi-line `ask()` prompts no longer erase terminal scrollback.
+- Exclude synthetic `[harness control]` injections from the rewind picker.
+- Fix an installed-gem launch crash (`uninitialized constant Rubino::TAGLINE`).
+
+### Removed
+
+- Drop the dead `server.*` config section, the orphaned `ask_parent` takeover and
+  ask/reply substrate, and dead code surfaced by the post-removal audit.
+
+### Docs
+
+- Mark native OAuth as not wired end-to-end (WIP).
+
+## [0.5.1] - 2026-06-25
+
+### Added
+
+- **Tool-output compression (deterministic, off by default).** A no-LLM content
+  router at the single `Agent::ToolExecutor` seam compresses high-volume tool
+  output before it reaches the model: test/build/lint logs are reduced to their
+  failures + summary (≈97% fewer tokens on a failing suite, every failure kept),
+  and a whole-file source read can be returned as a skeleton (signatures kept,
+  large bodies elided behind a `read offset:/limit:` pointer). Diffs, grep/search
+  results, JSON, and short output pass through **byte-identical**. Reversibility
+  reuses the existing spill: the full original is written to
+  `tool-results/<call_id>.txt` and the compressed output points the model there —
+  no separate store/tool. When enabled, `read` and `shell` expose a `compress`
+  parameter (default true) so the model can opt a single call out and get the
+  verbatim output. Master switch `tool_output_compression.enabled` (default
+  `false`); `rubino setup` offers to turn it on. See
+  [configuration.md](docs/configuration.md#tool_output_compression).
+- **Multi-language code compression.** The whole-file source-skeleton compressor
+  now covers more than Ruby. `tool_output_compression.code.languages` (default
+  `["ruby"]`) selects which languages get skeletonised: Ruby (built-in Prism
+  parser), Python (stdlib `ast` via your `python3` — a no-op if `python3` isn't
+  on PATH), and JavaScript / TypeScript / TSX (via the optional
+  `tree_sitter_language_pack` gem — a no-op until it's installed). A read in an
+  unlisted language passes through verbatim. `rubino setup` adds a language
+  picker and, if you choose JS/TS, offers to install the parser gem.
+- **Agent-attach view.** At the idle prompt, `↓` opens the subagent picker and
+  `Enter` now **attaches** to the highlighted background subagent: the screen
+  switches to that agent's OWN full timeline (its tool calls and what it said,
+  replayed from its session) and the input prompt becomes scoped — `sa_xxxx ❯`.
+  While attached, typed text steers the running child (or answers it when it's
+  blocked on you); `←` on the empty prompt (or the picker's `◂ main` row) returns
+  to the main timeline, and the picker doubles as a switcher between agents. This
+  replaces the bounded registry snapshot the picker's Enter used to show with the
+  agent's real conversation, and makes the global `/agents <id> steer/probe` and
+  `/reply <id>` forms redundant while attached. The attached view **live-tails**
+  the child's stream (tool rows and streaming prose) exactly like the main agent
+  instead of freezing on a snapshot, and `/back` / `/detach` return to the main
+  agent regardless of composer-draft state (#82, #85, #87).
+- **`api.allow_public_bind` gate.** Because the API server can execute shell
+  tools, binding it to a non-loopback address (`--host 0.0.0.0`,
+  `RUBINO_API_HOST`) now **refuses to boot** unless `api.allow_public_bind: true`
+  is set in `config.yml`; when opted in, the server prints a one-time exposure
+  warning. Loopback binds are unaffected (#577).
+- **MCP tool transparency + parallel startup.** An MCP tool's display label now
+  carries its source — the live tool card and the approval card both show
+  `<bare> (mcp:<server>)`, so you can tell at a glance that an out-of-process
+  server is running (the model-facing tool name is unchanged) (#582). MCP
+  servers also now connect **in parallel** at boot, so one hanging server no
+  longer serializes startup (#576).
+- **Read-only meta-commands run immediately while a turn is active.** A small
+  set of non-mutating slash commands (`/agents`, `/tasks`, `/stop`, `/status`,
+  `/jobs`, `/help`, `/commands`, `/dirs`) now execute **immediately** mid-turn
+  instead of queuing — so you can drill into a sub-agent, stop the run, or check
+  status without interrupting. State-mutating commands (`/model`, `/clear`,
+  `/new`, `/config`, `/mode`, …) show a transient `⚠ <cmd> is not available
+  during an active turn — press Esc to interrupt first` notice; plain text still
+  queues, and `Esc` interrupts.
+- **Interactive CLI session picker.** A bare `rubino sessions` on a TTY opens an
+  interactive picker (id, title, message count, dir, age; arrow-key highlight,
+  type-to-filter, `Esc` cancels) and `Enter` resumes the chosen session. On a
+  pipe / non-TTY it prints a script-safe list; `sessions list` stays list-only.
+  The picker is cwd-scoped by default; `--all` unscopes it.
+- **`/sessions rename <id|title> <new title>`.** Rename a session from the REPL
+  (#45).
+- **Aux-LLM session titles.** When `auxiliary.title` names a concrete backend,
+  new sessions get an LLM-generated, length-capped summary title; the
+  deterministic derivation stays the default and the fallback (#45).
+- **Streaming GFM table rendering (#89).** A markdown table now renders as a
+  live, correctly-fitted table as it streams — a sliding window of recent rows
+  grows in place — instead of leaking raw `| col | col |` pipes that only snap
+  into a table once the message completes.
+
+### Changed
+
+- **Provider auto-routing.** With `model.provider: "auto"` (the default), the
+  concrete provider is derived from the model id (`openai/*` → OpenAI); the
+  setup wizard / auto-detect write an explicit provider when a non-OpenAI
+  backend is chosen.
+- **Credential check uses provider-specific env vars.** The credential check
+  and key resolution now read the env var for the configured provider
+  (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `BEDROCK_API_KEY`,
+  `MINIMAX_API_KEY`, and `<PROVIDER>_API_KEY` for anything else, e.g.
+  `DEEPSEEK_API_KEY`). A non-OpenAI provider no longer silently falls back to
+  `OPENAI_API_KEY` (only providers explicitly marked `openai_compatible` /
+  `anthropic_compatible` fall back to `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`).
+- **`security.confirm_policy` default is `dangerous_only`.** Safe shell commands
+  run unprompted; only commands matching a dangerous pattern prompt. Set
+  `confirm_policy: confirm_all` to restore prompt-on-everything. The
+  non-bypassable hardline floor and `permissions: deny` always run first
+  regardless of policy.
+- **Removed the built-in `run_tests` and `github` tools.** Running tests and
+  GitHub/git operations now go through the generic `shell` tool (with its
+  hardened git arg parsing), matching the field norm and shrinking the tool
+  surface.
+- **Blocked-tool results are now typed errors.** When a tool call is blocked
+  (denied by approval, sandbox, or policy), its result is returned to the model
+  as a typed error with explicit anti-confabulation wording, so the model is told
+  the action did NOT happen instead of being free to assume success (#583).
+- **Single status bar during a turn.** The animated facet activity row is folded
+  into the model/ctx footer (one bar, not two); the "esc to interrupt" hint shows
+  exactly once, and a mid-stream **waiting indicator** resurfaces beneath the
+  in-flight tail after a short window of model/transport silence and drops away
+  the instant tokens resume (#21, #56b — `/status` now also shows the workspace
+  cwd line).
+- **FIFO approval queue for concurrent subagents.** When multiple subagents need
+  approval at once, one modal shows at a time with an "(N more queued)"
+  indicator that dequeues on resolve, and async-completion notices no longer
+  print over an active modal. Subagent approvals also **escalate to the parent's
+  approval card at any nesting depth**, so a nested child no longer fail-closes
+  with a noninteractive block (#86).
+- **Slash commands dispatch while attached to a subagent** (`/stop <id>`,
+  `/agents`, `/status`, …) instead of being steered into the child as text;
+  `/skills list` / `/skills ls` show the skills list rather than trying to
+  activate a skill named `list`; `/think off` hides the reasoning aside for
+  always-thinking models unless an explicit `/reasoning` is set; `/config <key>`
+  resolves the short labels `/status` advertises (`reasoning`, `effort`,
+  `think`) (#62, #66, #87).
+- **`/new` returns instantly.** The end-of-session memory flush is enqueued as a
+  background job instead of running a synchronous aux-LLM extract, so starting a
+  new session no longer freezes the prompt for 2–3s.
+- **Headless one-shot drains only its own jobs.** `rubino -q` now emits and
+  flushes the JSON result envelope before draining, and scopes the post-turn job
+  drain to the run's own session, so a one-shot returns immediately even with a
+  background job backlog.
+- **Subagent cards are distinguishable + carry the task id.** Concurrent
+  subagent cards label by a dimension drawn from the task prompt (rather than the
+  bare agent type), background "done" markers carry the task id, and the live
+  elapsed counter shows seconds (`1m05s`) so it visibly advances (#44, #570).
+- **Pastes coalesce into a single placeholder**, input history is recalled and
+  persisted, `Enter` accepts the highlighted dropdown candidate, and
+  `task_result` running-polls no longer flood the transcript (#524, #525).
+- **System-prompt grounding for control + tools.** The cap / continuation /
+  summary control is framed as trusted `[harness control]` so MiniMax-M3 stops
+  treating it as prompt-injection (#75); the background-shell lifecycle is primed
+  so the model uses `shell_output` / `shell_kill` correctly; the verification
+  step is scoped to never modify the environment and to stop honestly.
+- **Memory-flush best-effort boundary** made airtight (#471), so a failure
+  flushing memory at shutdown can't take down the run.
+
+### Removed
+
+- **Child→parent `ask_parent` / `answer_child` tools.** Subagents are
+  non-blocking background workers and can no longer pause mid-task to ask their
+  parent (or the human) a question; instead they make sensible default calls and
+  surface open decisions in their result. The two model-facing tools that
+  implemented that channel — `ask_parent` (the child→parent escalation) and
+  `answer_child` (the parent's reply) — are gone. The parent→child `steer` /
+  `probe` tools and the human approval gate (`/reply` for a child parked on an
+  approval) are unchanged. `tasks.ask_parent_timeout` is now vestigial.
+- **`streaming.cursor` config key.** It was dead config (assigned, never read)
+  and is no longer accepted — remove it from any `config.yml`.
+- **`security.require_confirmation_for_shell` config key.** Replaced by
+  `security.confirm_policy` (`dangerous_only` | `confirm_all`); the old key is no
+  longer honored.
+
+### Security
+
+- **Hermes-style secret handling (#506).** Adopts the Hermes secret model across
+  the agent: the structured `read` tool blocks `.env` and credential files
+  outright, and secret **values** are redacted in the output of `read`, `grep`,
+  `shell` (including the live stream seam, not just the final buffer, #507),
+  `summarize`, and `read_attachment` (#511/#512). A `security.redact_secrets`
+  toggle (default **on**) controls redaction. The earlier per-read secret-file
+  approval gate was removed in favour of this block-list + redaction model
+  (#480). Over-broad redaction was then narrowed: the `ENV_ASSIGN` pattern is
+  anchored so `AUTHORS` / `SECRETARY` pass through while `API_KEY` / `AUTH_TOKEN`
+  still redact, the Telegram-token pattern is pinned to its canonical shape, and
+  fully-masked secrets carry an explicit marker rather than a bare `***`
+  (#67, #516).
+- **Secrets are no longer persisted to memory (#99).** A `Security::SecretDetector`
+  is wired into the memory write path (it refuses an explicit save and the
+  auto-extract persist path) and into the redactor, catching prefixed key
+  shapes, prefix-less AWS secret keys, and a high-entropy heuristic — previously
+  an `sk-proj-…` key could be saved verbatim and re-injected into every future
+  system prompt.
+- **Removed the dedicated `git` tool (RCE bypass).** Git now runs through the
+  hardened `shell` with strict arg parsing that rejects exec vectors
+  (`--ext-diff`, `-c`, textconv, …) plus a `GIT_HARDENED_ENV`, instead of a tool
+  that could be steered into arbitrary command execution (#536/#553).
+- **Dangerous write/exec flag-forms prompt under the default gate (#61).**
+  `git -c` / `--output`, `sed -i`, `sort -o`, `find -delete` / `-exec`,
+  `tar --to-command`, `tee`, interpreter `-c` / `-e` / `--eval`, etc. no longer
+  auto-run under `dangerous_only`, while bare interpreters and read-only forms
+  still auto-run. A shared `Security::CommandNormalizer` also closes
+  line-continuation evasion (e.g. `rm -r\<newline>f` no longer slips past the
+  danger/approval layer).
+- **Extended HOME credential read-block.** Reading credential stores under HOME
+  is blocked and a base64-decode-pipe-to-shell (`echo … | base64 -d | sh`) is
+  flagged dangerous (#519); the denylist now covers `.ssh`, `.aws`, `.netrc`,
+  `.git-credentials`, `.kube`, `.docker`, `.gnupg`, `.azure`, and `.config/gh`
+  (#537). A write through a **dangling in-workspace symlink** can no longer
+  escape the sandbox — the link target is resolved before the create-new-file
+  fallback (#62).
+- **Tighten the `ruby_llm` floor to `>= 1.16` (#508).** The adapter wires native
+  providers through ruby_llm's generic `<provider>_api_base=` setters
+  (deepseek/mistral/etc., #482), which only exist from ruby_llm 1.16.0. The
+  gemspec previously allowed `~> 1.0`, so a fresh `gem install` could resolve
+  ruby_llm 1.15 and crash at runtime with `NoMethodError`. The dependency is now
+  `>= 1.16, < 2.0`.
+- **Secret masking on `config set`.** `rubino config set` now masks the echoed
+  value when the key looks secret (`api_key`, `token`, `password`, `secret`,
+  `authorization`, …) and when the value itself contains inline credentials
+  (`key=value`, `Bearer …`, URL userinfo, `curl -u`, `mysql -p…`), so keys are
+  not printed in the clear to the terminal/scrollback.
+- **Sanitized untrusted text rendered to the terminal (CWE-150).** Text that
+  originates from the model, tools, or filenames (subagent cards, `/`-palette and
+  `@`-picker menu labels, and the remaining CLI aside sinks — probe, reasoning,
+  open-fence, branch title) is now defanged of ANSI/OSC escape sequences before
+  it is written, closing an escape-injection class (#563/#564/#565–#568).
+- **Vision egress hardening.** The `vision` tool now honours
+  `attachments.policy.aux_vision_egress` (default `true`): set it to `false` and
+  the tool refuses to send an image to an external auxiliary model, returning a
+  clean error instead of egressing the bytes (#578). Before any egress it also
+  **content-sniffs** the file (magic bytes win over the extension, fail-closed),
+  so a mislabelled or non-image file can't be smuggled to the external host
+  (#579).
+- **OS sandbox covers more executors.** The OS write-jail (Landlock / Seatbelt)
+  now also confines background shells, `ruby`, and `run_tests`, with relaxation
+  gated on verified enforcement; a write-jail `EACCES` outside the workspace
+  produces an attributable "blocked by write-jail" hint (#74).
+
+### Fixed
+
+- **MiniMax-M3 pre-tool-call "freeze".** Thinking/reasoning now defaults ON for
+  every provider (it was deliberately off for MiniMax-family ids). On the
+  anthropic-compatible path rubino now sends `thinking: {type: enabled,
+  budget_tokens: …}` and streams the model's reasoning deltas — so the multi-
+  second window where M3 reasons toward a tool-call is filled with visible
+  streamed reasoning instead of dead air (the symptom that read as the agent
+  "freezing" when it spawned subagents). Matches the reference agent's default
+  `reasoning_effort: medium`. A backend that rejects the budget is caught and
+  retried once without it (#75), so default-on is safe; set
+  `providers.<name>.supports_thinking: false` to opt out.
+- **MCP `degraded` server state.** `/mcp` and `rubino doctor` now distinguish a
+  reachable server (`●`) from a **degraded** one (`⚠` — the process is alive but
+  a protocol call such as `tools/list` failed), instead of reporting it as plain
+  reachable (#575).
+- **Session-title length cap.** A renamed session title is now length-capped at
+  rename and truncated on render, so an over-long title can't disrupt status /
+  session-list layout (#581).
+- **Streaming fidelity.** A streaming turn no longer re-executes or re-surfaces
+  tool calls it already ran (no double "started" line or duplicate final tool)
+  (#53), and a split think/fence sentinel is held across the message-boundary
+  flush so reasoning no longer leaks into the body and prose isn't torn apart
+  (#43/#54). A committed markdown table glued to trailing prose no longer leaks
+  raw pipes, and a too-wide table fits the pane instead of tearing the border.
+- **Subagent / multiplexer UI.** A running `blocked_on_parent` sub stays visible
+  in the footer while listed; cap-rejected delegation renders a neutral
+  "at capacity" row instead of a phantom failed card; the close-row / replay use
+  the per-call subagent name instead of a shared stale one (#35); the agent
+  picker opens reliably on `↓` and `←`/`↑` backs out; picking `◂ main` returns to
+  main immediately mid-turn; a nested child's menu no longer crashes it; and the
+  parent autonomously resumes at idle when background subagents finish while
+  detached (#37, #44, #51, #561).
+- **Interrupt handling.** `Esc` at the tool-dispatch boundary raises a clean
+  interrupt instead of a malformed continuation that the backend rejects as
+  "invalid params"; a stray `Ctrl-C` exits cleanly (130) with no raw `net/http`
+  backtrace; and a background thread never dumps a backtrace on death.
+- **Input papercuts.** Backspace (`DEL 0x7f`) deletes instead of inserting a
+  space (#522); a single `Ctrl-D` at an idle empty composer no longer hangs, and
+  fast input bursts coalesce their redraws (#520). Several composer
+  render/input races and resize-while-typing reflows that duplicated the
+  in-progress input into the scrollback are fixed, including chained resizes and
+  the resize REPAINT path (#481/#485/#486/#499/#500/#501/#503).
+- **`edit` no longer crashes on non-UTF-8 / binary buffers.** Fuzzy-match
+  normalization passes invalid-encoding bytes through verbatim (#47), atomic
+  writes are binmode'd so binary buffers never transcode (the intermittent
+  in-session edit crash on accented files) (#65), and `clean_slice` reinterprets
+  binary as UTF-8 rather than calling `.encode` (#58). A failed edit / read /
+  write now shows `✗` instead of a green `✓`.
+- **Background jobs and shells.** The job queue drains reliably — stale `running`
+  rows are reclaimed after the lease expires (#76) and `ExtractMemoryJob` is
+  prioritized over `SummarizeSessionJob` so save→recall doesn't lag (#79);
+  finished background shells are retired with their buffer and exit status
+  retained, so `shell_output` / `shell_tail` / `shell_kill` stay reachable next
+  turn (#78); shell cancel no longer orphans the child process group, and a
+  finished background shell auto-wakes the model.
+- **Turn-ledger honesty.** Blocked / errored tools no longer count toward the
+  "N tools ran / M edits" ledger, so a turn whose only tool was refused stops
+  telling you to review nonexistent changes; the force-summary and closing-summary
+  nudges are grounded in the truthful turn ledger so the model can't confabulate
+  having done nothing (#36/#84). MiniMax HTTP 429 / quota errors are categorized
+  as retryable rate-limit (honouring `Retry-After`) instead of "Invalid request",
+  and the anti-confabulation note no longer over-fires on accurate local caveats.
+- **Sessions / resume / doctor.** A per-session `flock` guard stops a concurrent
+  `--continue` from forking a moving transcript (#543), replay renders only the
+  new tail of a restated final message (#542), `--resume <id>` is validated
+  before the boot banner (#521), and `doctor` warns instead of false-green when
+  no usable credential exists and no longer implies an unverified key is
+  validated (#541/#546).
+- **Non-native provider wiring (#482).** Fixed the preflight that falsely
+  reported non-native providers (deepseek/mistral/…) as ready; they are now
+  wired through the generic `<provider>_api_base=` setters and the run stops
+  on an unreachable endpoint instead of failing later. Transient name-resolution
+  failures (`EAI_AGAIN`) are retried rather than fatal, and a stream that ends
+  without a finish signal is recovered instead of failing the turn.
+- **Parent-death reaps child shells (#478).** When the agent process dies, the
+  long-running child shells it spawned are reaped instead of being orphaned,
+  using a trap-safe SIGTERM/SIGHUP handler (no `Mutex` inside the signal trap).
+- **Compaction no-op loop (#484).** Stopped a busy-loop on an over-budget
+  session that has too few messages to compact. The `doom_loop.threshold`
+  default is also no longer rejected by its own validator (#60).
+- **Memory polish indicator no longer flashes every turn (#59).** The polish
+  worker starts only when a row was actually enqueued, the indicator composes
+  alongside the ctx bar instead of replacing it, and a verbatim repeat
+  short-circuits to the existing row at the write seam.
+- **`/exit` and exit codes.** `/exit` routes through the quit-guard, and an
+  interactive session exits non-zero on an auth/credential error (#154).
+- **CLI DX papercuts.** Fixed the bare-`rubino "prompt"` one-shot path, help-
+  session clutter, a bare-prompt did-you-mean edge case, and a `read_attachment`
+  hint that suggested markitdown for raster images instead of OCR.
+- **Input hardening.** Fixed a raw SQLite3 exception on session input with
+  hostile/NUL bytes (#498) and cleaned up `Errno` error messages on the failure
+  paths; tightened mcp args validation and assorted low-severity
+  config/sessions/resume/CLI papercuts.
+
 ## [0.5.0] - 2026-06-15
 
 ### Added

data/README.md

@@ -5,12 +5,62 @@ A coding & automation **agent** — small, self-contained, and built to run *whe
 ## Why rubino
 
 - **Runs where the work is** — a single gem on the machine (or VM) that holds the code, not a remote service you pipe files to.
-- **Persistent memory** — a tiny SQLite "Zep"-style fact store that learns about you and the project across sessions.
+- **Persistent memory** — a tiny SQLite fact store that learns about you and the project across sessions.
 - **Context compaction** — automatic compression with session lineage when the conversation outgrows the window.
 - **CLI *and* HTTP API** — an interactive terminal session for humans, a bearer-protected JSON + SSE API for programs.
-- **Real tools, gated** — read/write/edit, shell, ruby, git/github, grep/glob, a structured test runner, vision, and more, behind an approval model with a non-bypassable hardline floor.
+- **Real tools, gated** — read/write/edit, shell, ruby, grep/glob, apply_patch, vision, and more (git, GitHub, and tests run through the hardened shell), behind an approval model with a non-bypassable hardline floor.
 - **Built on ruby_llm** — provider-agnostic: MiniMax, OpenAI, Anthropic, Gemini, or an OpenAI-compatible gateway.
 
+## Cache-friendly compaction (measured)
+
+A long agent session only stays cheap if the cached prompt prefix survives
+compaction. rubino is built so that when the conversation is compressed into a
+summary, the summary lands *after* the cached head (system + tools + stable
+history) — so the provider's prompt cache keeps **hitting** the head instead of
+re-encoding it cold every time the session is compacted.
+
+Measured with the model held fixed (local oMLX `Qwen3.6-35B-A3B`,
+Anthropic-style `cache_control`) on a 25-turn coding session that triggers
+compaction **9 times**:
+
+| metric | rubino |
+|---|---|
+| cached prefix retained right after each compaction | **44–94%** (survives — never resets to 0) |
+| cumulative cache-read over the whole session | **88%** |
+| prefix byte-stability across turns | **0.95** |
+| task solved through all 9 compactions | **10/10** hidden tests, 0 wasted work |
+
+Holding the model fixed isolates the **engine** — any difference is the
+scaffolding (prompt assembly, where the compaction summary is placed, cache
+breakpoints), not the model. This is a single model and a single scenario:
+indicative of the design, not a leaderboard. The harness lives in a separate
+benchmark project.
+
+## Tool-output compression (measured)
+
+Test logs, diffs and large command dumps are mostly noise. rubino can route
+each tool output through a **deterministic (no-ML)** compressor that keeps the
+signal and drops the rest — opt-in (`tool_output_compression`), with a
+byte-identical passthrough for anything already small and a `retrieve_output`
+pointer back to the full text. Token-honest: counts are the **exact**
+`prompt_tokens` reported by the server (local oMLX `Qwen3.6-35B-A3B`), not
+chars/4 estimates.
+
+| tool output | reduction | fidelity (verified) |
+|---|---:|---|
+| rspec full suite (21 failures, ~8k lines) | **97%** | all 21 failures + the tally kept |
+| `git log --stat` / `ls -R` | **94%** | boundary/keyword lines kept |
+| large source diff (9 files) | **42%** | all 575 ± lines, 13 hunks, 9 headers |
+| `package-lock.json` diff (60 bumps) | **99%** | file header + summary (body elided) |
+| whole-file Ruby read → skeleton | **27%** | signatures + structure kept |
+| JSON (kubectl / docker / gh, uniform rows) | **40–88%** | error rows + outliers always kept |
+| rubocop (already signal-dense) | 11% | floor — every offense kept |
+
+End-to-end A/B on real edit tasks: **12/12 tasks passed with compression ON and
+OFF** — it never broke a task, and every forced-failure run still recovered the
+single failing line out of a long log. Routing is verified (each output goes to
+the right strategy) and small inputs pass through **byte-identical**.
+
 ## Install
 
 One line, Linux and macOS (x86_64 / arm64). Installs a compatible Ruby, then the gem — all in user space, no sudo:
@@ -111,7 +161,7 @@ agent:
 
 memory:
   enabled: true
-  backend: "sqlite"           # tiny-Zep FTS5 + graph-lite recall (default)
+  backend: "sqlite"           # SQLite FTS5 + graph-lite recall (default)
   auto_extract: true
 
 compression:
@@ -126,7 +176,7 @@ tools:
   git: true
   shell: true                 # ON by default; every command is still approval-gated
   ruby: true
-  web: false                  # gates BOTH webfetch and websearch
+  web: true                   # ON by default (keyless DuckDuckGo backend); gates BOTH webfetch and websearch
   memory: true
 ```
 
@@ -142,7 +192,7 @@ Full reference (every key, env vars, precedence): **[docs/configuration.md](docs
 - **[Configuration](docs/configuration.md)** — full config + env vars + precedence
 - **[Tools](docs/tools.md)** — the built-in tool set and approval behavior
 - **[Skills](docs/skills.md)** — reusable instruction packs, the 3-level disclosure, and `SKILL_LOADED` observability
-- **[Memory](docs/memory.md)** — the SQLite tiny-Zep backend
+- **[Memory](docs/memory.md)** — the SQLite memory backend
 - **[Security](docs/security.md)** — approval model, hardline floor, TLS
 - **[Troubleshooting](docs/troubleshooting.md)** — keyed on the exact error strings
 - **[HTTP API](docs/api/v1.md)** · **[Jobs & cron](docs/jobs.md)** · **[OAuth providers](docs/oauth-providers.md)** · **[Architecture](docs/architecture.md)**
@@ -150,7 +200,7 @@ Full reference (every key, env vars, precedence): **[docs/configuration.md](docs
 
 ## Built-in tools
 
-The agent ships **27 built-in tools** (the set `rubino tools` lists): `read`, `read_attachment`, `summarize_file`, `write`, `edit`, `multi_edit`, `apply_patch`, `grep`, `glob`, `git`, `github`, `shell`, `shell_output`, `shell_tail`, `shell_input`, `shell_kill`, `ruby`, `run_tests`, `web`, `question`, `todowrite`, `memory`, `session_search`, `attach_file`, `vision`, `skill`, `task`. A single `web` tool gates both fetching a URL and searching (config key `tools.web`, off by default). Each tool is gated by a `tools.<key>` config flag (opt-out) and the approval model. See **[docs/tools.md](docs/tools.md)**.
+The agent ships **27 built-in tools** (the set `rubino tools` lists): `read`, `read_attachment`, `summarize_file`, `write`, `edit`, `multi_edit`, `apply_patch`, `grep`, `glob`, `git`, `github`, `shell`, `shell_output`, `shell_tail`, `shell_input`, `shell_kill`, `ruby`, `run_tests`, `web`, `question`, `todowrite`, `memory`, `session_search`, `attach_file`, `vision`, `skill`, `task`. A single `web` tool gates both fetching a URL and searching (config key `tools.web`, on by default via the keyless DuckDuckGo backend; it degrades gracefully when no search backend is reachable). Each tool is gated by a `tools.<key>` config flag (opt-out) and the approval model. See **[docs/tools.md](docs/tools.md)**.
 
 ## Skills
 
@@ -191,7 +241,6 @@ These are designed-in but not fully wired yet — don't depend on them in produc
 
 - **MCP Support** — connect to Model Context Protocol servers via [ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp) ([docs/mcp.md](docs/mcp.md)).
 - **Multi-Agent** — Build / Plan / Explore agents with `@mention` routing ([docs/agents.md](docs/agents.md)).
-- **Plugin Hooks** — event hooks for extending behavior ([docs/plugins.md](docs/plugins.md)).
 
 ## Development
 

data/Rakefile

@@ -7,6 +7,23 @@ RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
 
+# API documentation. `rake rdoc` regenerates the HTML API docs into doc/rdoc
+# (gitignored); the .github/workflows/docs.yml workflow publishes the same
+# output to GitHub Pages. Guarded so the Rakefile still loads if the `rdoc`
+# default gem is somehow absent.
+begin
+  require "rdoc/task"
+
+  RDoc::Task.new(:rdoc) do |rdoc|
+    rdoc.rdoc_dir = "doc/rdoc"
+    rdoc.main     = "README.md"
+    rdoc.title    = "rubino-agent API documentation"
+    rdoc.rdoc_files.include("lib/**/*.rb", "exe/*", "README.md", "CHANGELOG.md", "docs/*.md")
+  end
+rescue LoadError
+  # `rdoc` unavailable -> the `rake rdoc` task is simply not defined.
+end
+
 # Parallel test execution across CPU cores via the `parallel_tests` gem.
 #
 #   rake parallel:spec            # auto: one worker per core