From d1e75f855c977f7201adb3a200c8675b8fe42381 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Thu, 3 Sep 2026 16:55:25 -0500 Subject: [PATCH] docs(tools): document tools/ tree in TOOLS.md + fix stale suite counts (#43) Collaborator-authored via conductor-loop calibration: task dispatched to the live ms-test seat (glm-5.3-flash) over agent-send.sh; diff reviewed line by line and every documented flag/exit code independently verified against tool source by the conductor; suites green at integration (config 24 / task 74 / release 14 / conductor 17 + verify). - new 'Tools (host-side)' section: agent-send.sh, agent-watch.sh, unslop-check.js - intro reading guide now points at tools/ (worker-flagged addition, accepted) - Maintenance suite counts corrected: test-task.sh 58 -> 74 Authored-by: ms-test collaborator (glm-5.3-flash) Integrated-by: conductor (dragon-lin:darkwing) --- docs/TOOLS.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 49 insertions(+), 3 deletions(-) diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 3da498a4..7196f495 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -4,8 +4,10 @@ On-demand reference for agent sessions (conductors, bootstrapping agents, reviewers). `AGENTS.md` routes here; this file carries the depth: usage, inputs/outputs, exit codes, and safety notes for every entry point. -Reading guide: all entry points are `scripts/*.sh` (bash) or invoked via -`node scripts/mosaic-task.mjs` (node). Every script fails closed — missing +Reading guide: system entry points are `scripts/*.sh` (bash) or invoked via +`node scripts/mosaic-task.mjs` (node). Host-side helpers under `tools/` +(tmux messaging, watchers, prose checker) are covered under Tools +(host-side) below. Every script fails closed — missing or invalid configuration/policy refuses the operation with a nonzero exit and changes nothing. @@ -72,11 +74,55 @@ Push is never automatic. |---|---|---| | `scripts/reset.sh` | Delete the data root | Triple-safety-checked (path, symlink, ownership marker) | | `scripts/test-config.sh` | Config selftests (no Docker) | 24 cases | -| `scripts/test-task.sh` | Task selftests + live cases | 58 cases | +| `scripts/test-task.sh` | Task selftests + live cases | 74 cases | | `scripts/test-release.sh` | Release selftests | 14 cases | | `scripts/test-conductor.sh` | Auto-apply selftests (sandboxed) | 17 cases | | `scripts/gitea-api.sh [body]` | Gitea API helper | Token never on argv/stdout | +## Tools (host-side) + +Host-side helpers under `tools/`, outside the `scripts/` command surface. +Per-tool READMEs: `tools/tmux/README.md` and `tools/unslop-hook/README.md`. + +| Command | Purpose | Notes | +|---|---|---| +| `tools/tmux/agent-send.sh` | Inter-agent tmux message with addressing preamble | Reliable submit (bracketed paste, Enter flush, draft detection); ships `send-message.sh` over ssh for remote panes (remote needs only bash + tmux + base64) | +| `tools/agent-watch/agent-watch.sh` | Condition watcher per agent seat | One transient systemd `--user` timer + service per watch; fires `agent-send.sh` when the condition command exits 0 | +| `node tools/unslop-hook/unslop-check.js ` | Mechanical AI-tell prose check | Dependency-free node CLI + module driven by `lists.json`; `extension.ts` is the pi extension wrapper | + +`agent-send.sh` prepends the preamble +`[: -> :]`; `-C`/`--class` adds +a ` class=` token (`terminal-log`, `actionable`, `human`, `reaction`, +`digest`; consumers treat an absent class as `actionable`). Flags: `-s` dst +session (required) · `-H` ssh target for a remote pane · `-L` named tmux +socket · `-n` dst hostname for the preamble · `-m`/`-f`/stdin message body · +`-S` source-label override · `-r N` Enter-flush attempts (default 2) · `-v` +verbose · `-h` help. Exit codes: `0` delivered/queued · `1` target not found · +`2` still draft · `3` usage error · `4` ambiguous socket (the session exists +on more than one tmux server; disambiguate with `-L` or `MOSAIC_TMUX_SOCKET`). + +`agent-watch.sh` subcommands: `start --name --session --when +'' --message ` with `--class`, +`--interval` (default 30), `--timeout` (default 3600), `--repeat`, +`--quiet-timeout`, `--socket` · `list` · `status [--json]` · `stop ` · +`log ` · `meta-install [--interval 300] [--unit-name ]` · +`meta-remove [--unit-name ]`. Interval floor is 10s (a watcher is a +fallback cadence, never a tight poll); hidden `_tick`/`_scan` subcommands run +inside the systemd services. `status` exit codes: `0` clean · `3` any stale +watch or dead meta-watch · `6` systemd user bus unreachable. Delivery goes +through `agent-send.sh`; rc `2` means the text reached the pane as an +unsubmitted draft, which counts as delivered and is not retried (other +failures retry twice, then the watch gives up). Watches are one-shot by +default; `--repeat` re-arms. Notices carry a `[watch:]` prefix. + +`unslop-check.js` checks a file (or stdin) against the word, phrase, +punctuation-density, and pattern lists in `lists.json`, stripping fenced and +inline code first so a quoted mention never flags. Invocation: +`node tools/unslop-hook/unslop-check.js `; `UNSLOP_LISTS=` +overrides the lists location. Exit codes: `0` clean · `1` violations (findings +printed as JSON on stdout) · `2` gate broken (invalid lists or unreadable +input; error on stderr, never a clean verdict). + ## Exit-code convention `0` success · `1` operation failed · `2` invalid data/configuration ·