charness 3.6.1 → 3.8.0

package/SETUP.md

@@ -143,7 +143,7 @@ WantedBy=default.target
 ```
 
 `nvm.sh` puts the nvm Node — and so `charness`, `claude` and `opencode` — on the service's `PATH`, which a service does not
-inherit from your shell. `KillMode=process` is the one [Restart behaviour](README.md#restart-behaviour) asks for: systemd's
+inherit from your shell. `KillMode=process` is the one [Restart behaviour](docs/backends.md#restart-behaviour) asks for: systemd's
 default would kill the agents' tmux and `opencode serve` with the bot, and while systemd marks `process` «not recommended»
 ([systemd.kill](https://www.freedesktop.org/software/systemd/man/latest/systemd.kill.html)), leaving them running is exactly
 what lets a bot restart keep its agents. Enable it and let the user manager start without a login:
@@ -229,7 +229,7 @@ stopped; this is not confirmed on current WSL. If the bot stops after you log in
 **Known risks.**
 
 - A Windows restart, a Windows Update reboot or `wsl --shutdown` ends the agents' processes, like a container restart:
-  each conversation resumes with its next message ([Restart behaviour](README.md#restart-behaviour)).
+  each conversation resumes with its next message ([Restart behaviour](docs/backends.md#restart-behaviour)).
 - **If a Windows program that the bot calls fails, run `wsl --update` in PowerShell first** and try again: the known
   failures below were fixed in newer WSL. The details, for whoever helps you: Windows `.exe` interop from a systemd service
   has failed in some WSL versions. WSL 2.0.5–2.0.13 could not run a Windows program stored in the Linux filesystem from a
@@ -273,7 +273,7 @@ your chosen providers need them.
 | `CLAUDE_BIN` | (auto) | The `claude` binary is not on PATH due to nvm/asdf/systemd PATH differences |
 | `ANTHROPIC_API_KEY` | — | A custom MCP/OpenCode plugin/auth resolver explicitly reads it; not needed for normal Claude CLI auth. The json-stream Claude backend strips it from the agent's env (subscription billing) |
 | `SCHEDULER_MCP_PORT` | an OS-chosen free loopback port | You need a stable, explicitly chosen port; it must differ from this instance's `OPENCODE_URL` port |
-| `CLAUDE_SCRAPE_DEBUG` | off | You are debugging Claude tmux scraping and need full RAW/FILTERED chunks |
+| `CLAUDE_SCRAPE_DEBUG` | off | You are debugging Claude tmux scraping (the deprecated tmux backend) and need full RAW/FILTERED chunks |
 | `AGENT_IDLE_MINUTES` | `55` | A json-stream Claude topic idle for this long is compacted (when `/compact_on_idle` allows) and its process stopped; the session sleeps and the next message resumes it — shorten it only for a test; a non-positive or non-numeric value keeps the default |
 | `REQUEST_BACKSTOP_MINUTES` | `90` | A request (a Jira hand-over, a message in an answers-only topic) with nothing seen working on it for this long is re-posted to its session — shorten it only for a test; a non-positive or non-numeric value keeps the default |
 | `TMUX_SOCKET_NAME` | — (the default tmux server) | The instance must run its agents on its OWN tmux server (`tmux -L <name>`; any plain name except `default`). Recommended for a second instance on one host: at boot an instance kills every agent session on its server that its own state does not know |
@@ -304,7 +304,7 @@ hostnames: their ports and tmux servers are their own.
 **The bot updates itself.** With `autoUpdate` on (the default) an instance checks for a new version every hour (the first
 check 10 minutes after it starts), installs it when nobody is using the bot, restarts **in place** — the same process id, so
 systemd, pm2, `nohup` or a terminal see nothing, and every agent keeps running (what survives:
-[Restart behaviour](README.md#restart-behaviour)) — and says in General what changed:
+[Restart behaviour](docs/backends.md#restart-behaviour)) — and says in General what changed:
 
 ```
 🔄 Charness updated: 3.4.0 → 3.5.0
@@ -364,7 +364,9 @@ safe to run blindly:
   changed;
 - a hot-mode instance (`charness hot`) rebuilds and restarts the worker
   by itself (after a dependency install the script touches `tsconfig.json`
-  so `tsc -w` recompiles with the new modules); a non-hot instance gets
+  so `tsc -w` recompiles with the new modules; should the watcher miss the pulled files anyway — its file-system events can
+  be dropped under the load of a big pull — the supervisor notices a source newer than its build and restarts the watcher by
+  itself); a non-hot instance gets
   `yarn build` — the script never kills processes (the bot's updater restarts it);
 - changes to the hot supervisor itself (`src/cli.ts`, `src/cli/hot.ts`,
   `nodemon.json`) are flagged with a warning: with the bot's updater the supervisor
@@ -380,6 +382,27 @@ entry:
 
 (create the log directory once: `mkdir -p ~/.local/state/charness`).
 
+### Runners for heavy commands (`remote-run`)
+
+A test suite, a build or an emulator run can take most of the machine the bot lives on. Attach another machine as a **runner** and
+agents can send such commands there with `charness remote-run`: output, exit code and declared result files come back as if the command
+had run locally. Without a runner nothing changes for anyone, and agents are not told of the command.
+
+**Pair it (the normal way).** Needs this machine's ordinary `sshd` (key login on) with an address the runner can reach — nothing else is
+opened or changed, no root, no VPN — and on the runner machine Node 22.12+, `ssh` and `tar`. In General send `/runners` → **＋ Pair a new
+runner**; the first time the bot asks which address runners dial (the `runnerHost` row of the [instance settings](#instance-settings-settingsjson)) and
+proposes the public address it finds. It posts one line (valid 10 minutes, single use): run it on the runner machine as the account that
+will run the jobs, then `charness-runner service install` there to keep it running. An instance without Telegram uses
+`charness runners pair --host host.example`. The steps, the services (a Mac that stays on while logged out), removing and the safety
+model: [docs/remote-run.md](docs/remote-run.md#pair-a-runner).
+
+**Or by hand over plain ssh** — for a machine that cannot dial this one: list it in `~/.config/charness/runners.json` (one file per OS
+user, shared by every instance of that user) after giving it an account of its own, `rsync` and Pueue; see
+[docs/remote-run.md](docs/remote-run.md#advanced-a-runner-over-plain-ssh) for that, `.remote-run`, every command and the exit codes.
+
+A **Jira** agent reaches `charness` through the bot's `PATH`; when that `PATH` lacks it, map it in `jira.json` `agentBinaries`
+([Jira setup](#jira-setup)).
+
 ## Telegram setup
 
 Four steps: create a bot, (optionally) set up a group, launch from your projects folder, bind a topic to an agent.
@@ -448,7 +471,7 @@ visible topic list, per-topic names/icons, quick agent switching — but it is
 4. **Remove the bot from the group and add it again.** Telegram caches the
    privacy-mode flag on join; without re-adding, the bot keeps private-mode and
    ignores free-form messages (see
-   [Troubleshooting → Bot doesn't see text](README.md#bot-doesnt-see-text-telegram)).
+   [Troubleshooting → Bot doesn't see text](docs/troubleshooting.md#bot-doesnt-see-text-telegram)).
 
 <p>
   <img src="docs/images/02-enable-topics.png" width="360" alt="Group settings → Topics toggle enabled (Forum mode)" />
@@ -576,7 +599,7 @@ next start and shows the progress in General (or in its log).
 
 - **Needs** `uv` (on `PATH` or in `~/.local/bin`), or `python3` ≥ 3.10 with the venv module (`apt install python3-venv`
   on Debian/Ubuntu). The install builds a private venv — your Python is left alone.
-- **Disk:** about 400 MB under `<DATA_DIR>/stt` (the model is 216 MB; the rest is the Python packages and their cache).
+- **Disk:** about 500 MB under `<DATA_DIR>/stt` (the model is 216 MB; the rest is the Python packages and their cache — about 100 MB of it is the ffmpeg libraries that read MP3, M4A and joined OGG files).
 - **RAM:** nothing while it is not running. The recogniser process starts with the first voice note that needs it (about
   +2–3 s once), uses about 0.5 GB for short voices and up to about 0.9 GB while a 5-minute voice is recognised with the
   default 4 workers, and exits by itself after 15 idle minutes (`gigaam.idleMinutes`, `0` = never). Idle time, workers,
@@ -585,6 +608,7 @@ next start and shows the progress in General (or in its log).
   recognised in parallel. A hot reload of the bot keeps a running recogniser; stopping or killing the bot takes it down.
 - **Russian only.** English words come out in Cyrillic or garbled; with a `language` other than `ru` set, the engine is
   skipped and the next one in the chain answers.
+- **Voice message formats:** a voice message is normally OGG/Opus, but Telegram also lets one be an MP3 or an M4A (AAC), and some apps join several OGG files into one — the local engine recognises each of these to its last second. Only *voice messages* are transcribed: an audio file sent as a file or as an audio message goes to the agent, not to speech recognition.
 - It listens on `127.0.0.1` only, on a port the OS picks, and answers only a per-start secret token.
 - **Docker is not supported yet** (the image has no `python3-venv`).
 
@@ -598,7 +622,7 @@ be written, the tap that needed it says so and names the path. The file is optio
 a hand edit applies to the next session start, no restart.
 
 ```json
-{ "defaultEffort": "medium", "autoUpdate": "on", "whatsNew": true }
+{ "defaultEffort": "medium", "autoUpdate": "on", "whatsNew": true, "botSkills": "on" }
 ```
 
 | Field | Meaning |
@@ -606,6 +630,10 @@ a hand edit applies to the next session start, no restart.
 | `defaultEffort` | The reasoning effort of every topic that has no `/effort` pick of its own: `low`, `medium`, `high`, `xhigh`, `max`, `auto` or `ultracode`. Set it from **`/effort` in the General topic** (a tap writes the file), or by hand. Leave it out and the built-in default, `medium`, applies |
 | `autoUpdate` | What the instance does about a new charness version: `on` installs it by itself when the bot is idle, `notify` says it is out and offers a button, `off` never looks. Set it from **`/update` in General**, or by hand. Leave it out and `on` applies ([Updating](#updating)) |
 | `whatsNew` | `true` (default): after an update General lists the CHANGELOG entries it brought; `false`: only the «Updated a → b» line. Set from `/update` in General, or by hand |
+| `botSkills` | Whether the skills Charness ships with its agents (`charness-manager`, the two delegate skills) and the hint to load the manager reach them ([Commands](docs/commands.md#skills-the-bot-gives-its-agents)): `"on"` or `"off"`. The default of an instance whose **General** never chose — a Jira-only instance, which has no General, sets it here; `/bot_skills` in General overrides it for the instance once used; leave it out and `on` applies. A running agent keeps its skills until its next start |
+| `taskAgents` | The cap on tracker task agents ([Jira setup](#jira-setup)): `{ "maxConcurrent": 5 }` — how many conversations of a connected tracker (Jira issues) may work on a hand-over at once, for the whole bot; an issue over it waits in a queue and starts by itself. `0` = no limit, 100 the most. The default of an instance whose **General** never chose — a Jira-only instance, which has no General, sets it here; **`/task_agents` in General** overrides it for the instance once used (a picker, or any number typed after the command). Leave it out and `5` applies |
+| `todo` | The shared todo lists ([Commands](docs/commands.md#shared-todo-lists)): `{ "isEnabled": true, "reminderMinutes": 60 }`. `isEnabled: false` turns the feature off (agents are not offered the tools); `reminderMinutes` is how long an agent may work without updating its list before it is reminded, `0` = never. Set both from **`/todo` in General → Settings**, or by hand — the way for an instance without a General topic (a Jira-only one). Leave it out and on / 60 apply |
+| `runnerHost` | The address paired runners dial to reach this machine's ssh server: `{ "host": "203.0.113.5", "port": 22 }`. **`/runners` in General** asks for it the first time you pair a machine (proposing this machine's public address when it answers with its own ssh key) and keeps it; it can be edited by hand. Leave it out and `/runners` asks again |
 
 What a new Claude session starts with, first that exists: the topic's own `/effort` pick, the platform's default
 (a Jira conversation: `effort` in `jira.json`, `high` when absent — Jira never reads `defaultEffort`), `defaultEffort`,
@@ -681,7 +709,7 @@ talk to the bot there.
 | Variable | Default | Description |
 |---|---|---|
 | `ALLOWED_GROUP_ID` | (auto-pair) | Numeric forum supergroup id (`-100…`). Leave empty to auto-pair with the first forum group a group **admin/creator** contacts the bot from (id is saved to `state.json`; re-point with `/pair`). A **name** is not accepted. A numeric value disables auto-pairing |
-| `CHAT_MODE` | `both` | Which surface(s) this instance serves: `group`, `dm`, or `both` — see [Two surfaces](README.md#two-surfaces-group-topics-bot-dm-or-both) |
+| `CHAT_MODE` | `both` | Which surface(s) this instance serves: `group`, `dm`, or `both` — see [Two surfaces](docs/backends.md#two-surfaces-group-topics-bot-dm-or-both) |
 | `OWNER_USER_ID` | — | **Optional.** Numeric Telegram user id of the owner — leave it unset to run group-only (the DM surface stays inert; a group works fully without it). Set it only to enable the owner-DM surface; **required** solely for `CHAT_MODE=dm` |
 
 **Localized in 12 languages** — the bot UI (commands, buttons, notices) speaks
@@ -771,11 +799,21 @@ connector behaves is described in [`src/connectors/jira/README.md`](src/connecto
    `runBudgetPer24h` defaults to 5; `model` and `effort` set the sessions' Claude model and reasoning effort
    (optional; absent → `opus` and `high`, either key overrides only its own default). `extraFields` (optional,
    none by default) names fields by id (`customfield_…`, or a system one like `duedate`) the agent should see next to the standard
-   ones, shown under their site name; an id the site does not list is logged at start and left out. `agentBinaries` (optional, host runtime) maps a tool name to the absolute path of an executable — for
+   ones, shown under their site name; an id the site does not list is logged at start and left out. `repos`
+   (optional) lists the repositories the project's issues work on, by folder name (`["example-repo"]`): the
+   [shared todo lists](docs/commands.md#shared-todo-lists) put the conversations of projects that share a name on one
+   board, together with the Telegram topics on a repository folder of that name; projects without `repos` share one
+   board for the whole instance. `agentBinaries` (optional, host runtime) maps a tool name to the absolute path of an executable — for
    example `{ "ffmpeg": "/opt/tools/ffmpeg" }` — which is checked at start and put on the agents' PATH. `adapter` is `claude-json-stream` (the default — the agent process is stopped when an issue
    idles) or `claude-per-turn` (stopped after every answer); either way the issue's conversation sleeps between
    requests and the next request resumes it.
 
+   **How many agents run at once.** The AI works on at most 5 issues at the same time, all projects together — set
+   `taskAgents.maxConcurrent` in [`settings.json`](#instance-settings-settingsjson) (`0` = no limit; read without a
+   restart). An issue handed over beyond that gets one comment saying it is queued, stays assigned to the AI and starts by
+   itself when an agent hands its issue back, the one that waited longest first — also across a restart. An @-mention
+   (answer only) is never held back, and a lower number never stops an agent that is already working.
+
 5. Start it with a clean environment, so nothing of the calling shell reaches it:
 
    ```bash

package/agent-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "charness",
+  "description": "Skills Charness gives the agents it starts: orchestrating detached workers with the bot's own tools",
+  "author": { "name": "Sergei Solo" },
+  "homepage": "https://github.com/olosegres/charness",
+  "license": "MIT"
+}

package/agent-plugin/README.md

@@ -0,0 +1,35 @@
+# agent-plugin — the skills Charness gives its agents
+
+A Claude Code plugin (`charness`) whose skills every bot-started agent session gets: Telegram topics and Jira
+conversations, Claude Code and OpenCode. The operator's own sessions outside the bot do not get them.
+
+| Skill | What it is for |
+|-------|----------------|
+| `charness-manager` | Orchestrating detached workers in a bot session: the delivery loop, the one-worker queue, the watch check that fires when a worker exits OR stalls (`schedule_create` + `checkCommand`), accounts through `claude_profiles`, talking to the user through the bot's tools |
+| `charness-delegate-claude` | Launching, watching and resuming a detached `claude -p` worker (`summarize-events.py` reads its event log) |
+| `charness-delegate-opencode` | The same for `opencode run` |
+
+## How a session gets them
+
+- **Claude Code:** every bot launch of an agent session (json-stream and tmux, start and resume) carries
+  `--plugin-dir <package>/agent-plugin`. Claude Code namespaces plugin skills by the plugin name and the skill's
+  FOLDER: `charness:charness-manager`. `--setting-sources project,local` (a Jira session) does not drop them.
+- **OpenCode:** the `opencode serve` the bot starts gets `OPENCODE_CONFIG_DIR=<DATA_DIR>/opencode-config`, a
+  bot-owned folder whose `skills` is a symlink to this folder's `skills/`. OpenCode adds those skills to the
+  project's and the user's own; it writes files (`.gitignore`) into that folder, which is why it is not this
+  folder. An operator who set `OPENCODE_CONFIG_DIR` keeps it, and OpenCode topics then go without these skills.
+- **Switched off:** the «Bot skills» switch (`/bot_skills`, `botSkills` in `settings.json`; `src/utils/botSkills.ts`) drops
+  the `--plugin-dir` of a Claude conversation at its next start or resume, and the hint to load `charness-manager` from the
+  bot MCP's instructions; the OpenCode server follows the instance value only (replaced at the bot's next start).
+
+## Rules for a skill here
+
+- Folder name = frontmatter `name` = `charness-<role>`. OpenCode has no namespaces: a skill named like a
+  project's or user's own one (`manager`) would replace it there.
+- The watch recipe in `charness-manager` is the `workerWatchCheckCommand` constant of
+  `src/scheduler/workerWatch.ts` verbatim (a unit test holds them equal), and every bot tool a skill names must
+  exist on the bot's MCP surface.
+- Written for this public repository: no real ids, paths or names. The shared rules repository keeps its own
+  `manager`; a change wanted in both is ported by hand.
+- Shipped in the npm package (`files`); a commit that touches only this folder still counts as a release change.
+  A Claude session reads a new version at its next start, OpenCode when it next creates the folder's instance.

package/agent-plugin/skills/charness-delegate-claude/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: charness-delegate-claude
+description: "In a Charness-run session, use to launch, watch, finish and resume a builder, reviewer, investigator or planner as a detached `claude -p` process instead of an in-process sub-agent: the account from claude_profiles, the role's model and effort, a full-privilege worker with deny rules, its event log, the bot watch check, resuming the same session. Load charness-manager first."
+---
+
+# Detached Claude Code worker (Charness session)
+
+A worker is `claude -p`: one turn per process, the conversation kept between runs by its session id. Load
+`charness-manager` first — it holds the delivery loop and the watch check this skill arms.
+
+## Account, model, effort
+
+- New worker: call `claude_profiles` with the worker's model and no `currentProfile`. Start the worker with
+  `CLAUDE_CONFIG_DIR=<configDir>` of the `recommended` profile (nothing when its `configDir` is null); without it
+  the worker drains YOUR account. The bot picks the account whose weekly limit resets soonest.
+- `recommended: null`: no account is usable now. Do not launch; `schedule_create` with `onceAt` = `nextAvailable.at`
+  and a prompt that stands on its own (plan path, scope, what to launch), then end the turn. If `nextAvailable` is
+  null too, no account names a time it frees up: ask the user a native question (nothing can run, no time known) and
+  `schedule_create` a one-off retry about 30 minutes ahead, with such a prompt.
+- Confirm the login under that directory: `env -u ANTHROPIC_API_KEY claude auth status --text`.
+- Role defaults, unless the user names others:
+  - builder (code, tests, debugging, live runs): `--model sonnet --effort xhigh`;
+  - investigator (a cause still unclear after a builder failed on it twice): `--model opus --effort high`;
+  - reviewer: `--model opus --effort high`; a small or mechanical diff (docs, tests only): `--effort medium`;
+  - planner and the research feeding a plan: `--model opus --effort high`, `xhigh` for a large feature.
+- Never Sonnet for work on data persistence (storage, DB schema and migrations, sync, merge and conflict
+  resolution, backups — anything that can lose or corrupt user data): every role runs on Opus, a builder at
+  `--model opus --effort xhigh` (`max` for a deep investigation). This beats the role defaults above.
+- Never Fable for a worker: it drains the shared session and weekly limits fastest.
+- The first `system`/`init` event must name the requested model; on a mismatch stop the worker and tell the user.
+
+## Launch
+
+1. Make a private run directory, generate a UUID for the session, write the brief into `<run-dir>/brief.md`:
+   the task and its context (the worker does not see this conversation), the skills it must load by name, every
+   resource another live process holds, and "report every changed file and how you verified".
+2. Run it in the target checkout:
+
+```bash
+setsid nohup env -u ANTHROPIC_API_KEY CLAUDE_CONFIG_DIR="<configDir>" \
+  CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 BASH_MAX_TIMEOUT_MS=7200000 \
+  claude -p --session-id "<uuid>" --model "<model>" --effort "<effort>" \
+  --dangerously-skip-permissions \
+  --disallowedTools Agent "Bash(git push *)" "Bash(git reset --hard *)" "Bash(git clean *)" "Bash(git branch -D *)" \
+  --output-format stream-json --verbose --include-partial-messages \
+  < "<run-dir>/brief.md" > "<run-dir>/events.jsonl" 2> "<run-dir>/stderr.log" &
+echo $! > "<run-dir>/pid"
+```
+
+- Leave out `CLAUDE_CONFIG_DIR=…` for the default profile.
+- `setsid nohup` detaches the worker from your process, so the bot stopping your idle process never ends it.
+- `--disallowedTools` takes several values, so an option must follow it, never the prompt.
+- `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` stops the worker from backgrounding a run that would die when its turn
+  ends; `BASH_MAX_TIMEOUT_MS` lets one foreground command run up to 2 hours. Longer work → split it.
+- Full privileges with deny rules, never a restricted allowlist: a refused ordinary command ends the worker's
+  turn early.
+- A checkout below the folder that holds `.claude/skills` does not see those skills: add
+  `--add-dir "<that folder>"` and check that the `init` event's `skills` lists every skill the brief names.
+3. Check the PID: `ps -o args= -p "$(cat "<run-dir>/pid")"` must show `claude -p … <uuid>`. If it does not (the CLI
+   handed over to a new process), take it from `pgrep -f "^claude -p .*<uuid>"` and write that into the pid file.
+4. Record the UUID, the profile name you launched on, the checkout and the run directory in the plan, then arm the
+   watch check from `charness-manager` with this PID and run directory.
+
+## Watch and finish
+
+- Progress: `python3 <this skill's base directory>/summarize-events.py <run-dir>/events.jsonl` — the tools it ran
+  last, its last words, the final result, the account's usage windows.
+- A quiet log alone does not prove a hang: look at the last tool call and API retries before stopping a worker.
+- Done means ALL of: a final event `"type": "result"` with `"is_error": false`, the task's actual output in it,
+  and the process gone. `"subtype": "success"` alone is not enough — it also appeared on an auth failure.
+
+## Resume
+
+- Confirm the old PID is gone, then repeat the launch with `--resume "<uuid>"` instead of `--session-id`, a new
+  brief and new log files (`events-2.jsonl`, …), and arm a new check. Never `--continue` or `--fork-session`.
+- Keep the model, effort and flags of the first run.
+- The account: call `claude_profiles` with `currentProfile` = the profile name recorded at launch; the worker stays on
+  it unless it can no longer run. Launch under the `recommended` profile's `configDir`, record that name.
+- A run rejected on a usage limit ("You've hit your session limit"): call `claude_profiles` with `currentProfile` and
+  `isStoppedByLimit: true`, and resume the SAME session at once under the `recommended` profile — never wait while an
+  account is usable. `recommended: null` → `schedule_create` with `onceAt` = `nextAvailable.at` and a prompt that
+  stands on its own (resume this session, call `claude_profiles` again); `nextAvailable` null too → ask the user a
+  native question and `schedule_create` the same one-off retry about 30 minutes ahead.
+- To stop a worker: confirm the PID is that worker (`ps -o args= -p <pid>`), `kill -TERM <pid>`, confirm it is
+  gone. Never kill by name, never a process you did not start.

package/agent-plugin/skills/charness-delegate-claude/summarize-events.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Summarize a detached `claude -p --output-format stream-json` worker log.
+
+Usage: summarize-events.py <events.jsonl> [<tool calls to show>]
+
+Prints the model, the last tool calls, the last text, the final result and the account's usage windows,
+so a manager can judge a worker's progress without reading the raw stream.
+"""
+
+import json
+import sys
+
+defaultToolCallCount = 8
+textPreviewLength = 300
+inputPreviewLength = 120
+
+
+def readEvents(path):
+    events = []
+    with open(path, encoding="utf-8", errors="replace") as file:
+        for line in file:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                events.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue  # a line still being written
+    return events
+
+
+def describeToolInput(toolInput):
+    if not isinstance(toolInput, dict):
+        return ""
+    for key in ("command", "file_path", "pattern", "description", "prompt"):
+        value = toolInput.get(key)
+        if isinstance(value, str) and value:
+            return " ".join(value.split())[:inputPreviewLength]
+    return ""
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__.strip())
+        return 2
+    toolCallCount = int(sys.argv[2]) if len(sys.argv) > 2 else defaultToolCallCount
+    events = readEvents(sys.argv[1])
+
+    model = None
+    toolCalls = []
+    lastText = ""
+    result = None
+    usageWindows = {}
+    for event in events:
+        eventType = event.get("type")
+        if eventType == "system" and event.get("subtype") == "init":
+            model = event.get("model")
+        elif eventType == "assistant":
+            for block in (event.get("message") or {}).get("content") or []:
+                if block.get("type") == "tool_use":
+                    toolCalls.append(f"{block.get('name')}: {describeToolInput(block.get('input'))}")
+                elif block.get("type") == "text" and block.get("text", "").strip():
+                    lastText = block["text"]
+        elif eventType == "result":
+            result = event
+        elif eventType == "rate_limit_event":
+            windows = (event.get("rate_limit_info") or {}).get("unifiedWindows") or {}
+            for name, window in windows.items():
+                usageWindows[name] = window
+
+    print(f"events: {len(events)}  model: {model}  tool calls: {len(toolCalls)}")
+    if toolCalls:
+        print("last tool calls:")
+        for call in toolCalls[-toolCallCount:]:
+            print(f"  - {call}")
+    if lastText:
+        print("last text: " + " ".join(lastText.split())[:textPreviewLength])
+    if result is None:
+        print("result: none yet (still running, or it died before finishing)")
+    else:
+        summary = {key: result.get(key) for key in ("subtype", "is_error", "num_turns", "total_cost_usd")}
+        print(f"result: {json.dumps(summary)}")
+        print("result text: " + " ".join(str(result.get("result", "")).split())[:textPreviewLength])
+    for name, window in sorted(usageWindows.items()):
+        print(f"usage {name}: {window.get('utilization')} (resets at {window.get('resetsAt')}, {window.get('status')})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/agent-plugin/skills/charness-delegate-opencode/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: charness-delegate-opencode
+description: "In a Charness-run session, use to launch, watch, finish and resume a builder, reviewer or researcher as a detached `opencode run` process instead of an in-process sub-agent: model and variant, deny rules, its JSON event log, the bot watch check, resuming the same session. Load charness-manager first."
+---
+
+# Detached OpenCode worker (Charness session)
+
+A worker is `opencode run`: it exits when its turn goes idle and keeps the session for a later run. Load
+`charness-manager` first — it holds the delivery loop and the watch check this skill arms.
+
+## Model and variant
+
+- The model and variant the user named; otherwise the ones this conversation runs on. `opencode models` lists
+  what the configured providers offer — pick a listed model and a variant it supports.
+
+## Launch
+
+1. Make a private run directory and write the brief into `<run-dir>/brief.md`: the task and its context (the
+   worker does not see this conversation), the skills it must load by name, every resource another live process
+   holds, "spawn no sub-agents", "wait for your own tests before ending your turn", and "report every changed
+   file and how you verified".
+2. Run it:
+
+```bash
+setsid nohup env OPENCODE_CONFIG_CONTENT='{"permission":{"bash":{"git push*":"deny","git reset --hard*":"deny","git clean*":"deny","git branch -D*":"deny"}}}' \
+  opencode run --auto --dir "<checkout>" --model "<provider>/<model>" --variant "<variant>" \
+  --format json --title "<scope>" \
+  < "<run-dir>/brief.md" > "<run-dir>/events.jsonl" 2> "<run-dir>/stderr.log" &
+echo $! > "<run-dir>/pid"
+```
+
+- `setsid nohup` detaches the worker from your process, so the bot stopping your idle process never ends it.
+- `--auto` approves every request that is not denied — the deny rules are the only guard, the brief is not one.
+  Never edit the global OpenCode permissions for this.
+- Without `--auto` the CLI refuses ordinary requests and the worker stalls.
+3. Check the PID: `ps -o args= -p "$(cat "<run-dir>/pid")"` must show `opencode run … --title <scope>`. If it
+   does not (the launcher handed over to a new process), take the newest match,
+   `pgrep -n -f "opencode.* run .*--title <scope>"` (a launcher may run the binary as a child: two matches), and
+   write that one PID into the pid file — the watch fires "worker exited" at once on a PID that is not the worker.
+4. Record the session id — the top-level `sessionID` of the first JSON event in `events.jsonl` — with the
+   checkout and run directory in the plan, then arm the watch check from `charness-manager` with this PID and
+   run directory.
+
+## Watch and finish
+
+- The log gets an event per finished step or tool call, not per token: one long command can leave it quiet. Add
+  the folder that command writes to into the watch check.
+- Read progress from the tool calls, not only the text events:
+
+```bash
+jq -r 'select(.type=="tool_use" or .type=="text") |
+  (.part.tool // "SAY") + (.part.state.metadata.exit // "" | if .=="" then "" else " exit=\(.)" end)
+  + " :: " + ((.part.state.title // .part.text // "") | gsub("\\s+";" ") | .[0:120])' \
+  "<run-dir>/events.jsonl" | tail -30
+```
+
+- Trust the `exit=` of a command over what the worker says about it.
+- Done means the process is gone AND its last turn holds the task's result without an `error` event or a failed
+  tool. A `step_finish` may still be followed by another step. When unsure: `opencode export <session-id>`.
+
+## Resume
+
+- Confirm the old PID is gone, then repeat the launch with `--session "<session-id>"`, a new brief and new log
+  files, and arm a new check. Keep the checkout, model and variant. Never `--continue` or `--fork`.
+- A turn stopped by a provider's usage limit: resume the same session with another provider's model whose
+  context window holds the session.
+- To stop a worker: confirm the PID is that worker (`ps -o args= -p <pid>`), `kill -TERM <pid>`, confirm it is
+  gone. Never kill the OpenCode server or a process you did not start.

package/agent-plugin/skills/charness-manager/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: charness-manager
+description: "In a Charness-run session (the bot's MCP tools such as schedule_create, answer_request, claude_profiles are present) use this INSTEAD of any other manager skill before you dispatch, watch or resume a worker — a detached `claude -p` or `opencode run` builder, reviewer, researcher or planner — and whenever the user calls you the manager. Drives a plan to done without writing code yourself, and watches every worker with a bot check that fires when the worker exits OR stalls."
+---
+
+# Manager in a Charness session
+
+You orchestrate: workers build, test, review and commit; you decide, keep the plan honest and keep the user
+informed. You never write product code and never review a diff yourself.
+
+## Modes
+
+- **autonomous** — the default for a scheduled or unattended run, or when the user says so. Drive a READY plan
+  (no draft marker, no open questions); ask nothing; decide from the plan and the project rules; stop and report
+  what you cannot resolve. Without a named plan pick one ready plan that a worker can finish alone (the oldest by
+  its file date); none → say "nothing to do" and stop.
+- **interactive** — the user is talking to you. Answer their question first, decide every point yourself and list
+  the decisions for them to correct, ask only about a fork you could not resolve.
+
+## Rules that never bend
+
+- Never force-push, tag, bump a version or merge a merge request.
+- You check a worker's result only through another agent's report, `git log`, `git show --stat` and the plan's
+  checkboxes — never by reading its code, running its tests or re-running its e2e yourself.
+- Parallel by default, on the same checkout — no worktree needed: reviewers and researchers run without limit
+  alongside everything else; several builders run at once when they edit independent parts of the code (name
+  each one's area in its brief; two tasks touching the same file queue).
+- Serialize only what shares state: builds, test runs (devices, ports, e2e lanes — through their locks) and
+  commits (one at a time, path-limited). Two workers never share a file, a port, a browser profile or a device at
+  once. Every new ask joins the queue the moment it is said; start it at once when nothing it needs is taken,
+  else tell the user its place.
+- A change the user can see is done only with a real end-to-end test that ran and passed. Never accept a stub, a
+  lower-level substitute or "test debt".
+- Interactive: a commit YOU make yourself (a plan edit, bookkeeping) needs the user's yes first; workers commit
+  their own work without asking.
+
+## Launching workers
+
+- Load `charness-delegate-claude` or `charness-delegate-opencode` before the first launch and follow it: the CLI the
+  user named, otherwise the CLI you run in.
+- Brief for a ready plan: its path, "implement it yourself, spawn no sub-agents", and — when several scopes go to
+  one builder — "your scopes are one batch: test each pointwise (unit tests and only its own new or changed e2e
+  flows), the full suites run once at the finish".
+- Brief without a plan: like a colleague who just walked in — the goal, file paths, what to change and why. Never
+  "based on your findings, implement it".
+- Name the skills the worker must load, never their content, and never restate project rules. Name every resource
+  another live process holds (a checkout, a port, a device).
+- Role skills such as `developer`, `task-review`, `review`, `commit`: name them when the project offers them.
+  Otherwise state the role in words — builder: implement, test, self-review, commit each scope, no push;
+  reviewer: read the commit range against the plan or the user's asks and report findings, change nothing.
+- Reuse the warm session: rework, the next small scope, or the next role on the same task resumes the SAME worker
+  session instead of starting a fresh one.
+
+## Watch every worker with a bot check
+
+Right after each launch, create ONE check for that worker run with `schedule_create`: cron `*/10 * * * *`,
+`isPinSilent: true`, a name like `watch <role> <scope>`, and this `checkCommand` with the real PID and run directory:
+
+```
+kill -0 <pid> 2>/dev/null || { echo "worker <pid> exited"; exit 1; }; [ -n "$(find "<run-dir>" -mmin -45 -print -quit)" ] || { echo "<run-dir>: no change for 45 min"; exit 2; }
+```
+
+- It fails on EITHER signal: the worker's process is gone, or nothing in its run directory changed for 45
+  minutes. A check that only runs `kill -0 <pid>` never fires on a hung worker — never arm one.
+- `isPinSilent: true`: the check's alert is pinned, and a worker that simply finished fires it too — a loud pin
+  per finished worker would notify the user for nothing. What the user must notice you ask as a question.
+- The run directory is where the worker writes all the time (its event log). A worker that runs one long command
+  may write nothing for a while: add the folder that command writes to (`find "<run-dir>" "<test-output-dir>" …`).
+- The check's `prompt` must stand on its own — the wake may reach a resumed or compacted you: the role, the scope
+  or plan path, PID, session id, run directory, and "read the result, decide, then cancel this check".
+- The first failure is ALSO the "worker finished" signal. On the wake read the worker's result first (its final
+  event, its exit, the end of its log), then decide: finished → the next step of the loop; stalled → look at its
+  last tool call, stop it, resume the same session; stopped by a usage limit → resume it at once on another account
+  (Accounts and usage limits).
+- Then cancel the check (`schedule_list` → `schedule_cancel`) — that also unpins its alert, so a finished worker
+  leaves nothing pinned. A new run gets a new check.
+- Never build your own watcher: no sleep loop, `CronCreate`, `ScheduleWakeup`, background job or tmux pane. They
+  live in your process, which the bot stops after an idle stretch.
+
+## Between wakes
+
+- After launching a worker and arming its check, write the worker state into the plan or draft (PID, session id,
+  account profile name, run directory, scope, check name), then END your turn. The bot stops an idle agent process and resumes the
+  conversation when the check wakes it; you lose nothing that is written down.
+- Start workers with `setsid nohup` (the delegate skills show the command), so stopping your own process never
+  takes a worker down.
+- A worker must never hand back a run it has not read: one that ended its turn with a build or test still in
+  flight is resumed to wait for it, read it and finish.
+
+## Delivery loop — a ready plan
+
+1. **Build.** One builder for the whole plan (or a group of small scopes); it commits each scope as it is green.
+   A large or risky scope, or an independent part running in parallel, may get a builder of its own.
+2. **Bookkeeping.** A finished scope flips its `[x]`; the commit that flips the plan's last box also moves the
+   plan file to `completed/`.
+3. **Finish — only when the whole task is done, never per scope:**
+   1. A fresh reviewer reviews ALL the task's commits once. Its brief: the plan path or the user's asks nearly
+      verbatim, and the commit range — nothing else. Findings go back to a builder as rework, then a new review.
+   2. Clean → a builder runs ALL test suites in full and fixes every failure.
+   3. Any fixes in 2 → a separate reviewer reviews just those fixes; a change it makes sends you back to 2.
+   Each loop runs up to 20 cycles while the findings are concrete local fixes, telling the user about each cycle
+   past the third — even when new findings keep landing in the same area. A major finding, or the 20 cycles used
+   up: stop, leave the work for inspection, report. Never propose cutting the agreed scope to escape the loop.
+4. **Push** only when the user allowed it (in chat or in their own instructions); otherwise report it ready to
+   push — as a question the user will notice (below).
+
+## No plan yet — interactive
+
+- **Bugs and small reworks:** capture each into a living plan the moment it is said (stable ids, never renumber,
+  never drop a deferral). An unambiguous one goes to a builder at once; only a fork you cannot resolve goes to
+  the user first.
+- **A feature or idea:** capture a draft; a researcher worker investigates the code and the web, decides every
+  point itself and returns a summary, its decisions and only the forks it could not resolve. Show them, record
+  the locked decisions, and ask before switching to building.
+
+## Accounts and usage limits
+
+- Before every Claude worker launch call `claude_profiles` with the worker's model and start the worker with
+  `CLAUDE_CONFIG_DIR=<configDir>` of `recommended` (nothing when it is null). A new worker goes to the account whose
+  weekly limit resets soonest. Never launch on an account billed to API credits unless the user asked.
+- Record the profile name beside the worker's session id. Every resume calls `claude_profiles` with
+  `currentProfile` = that name, so a warm worker stays on its account.
+- A worker stopped by a usage limit resumes its SAME session at once, never a fresh worker (which would redo the
+  work): call `claude_profiles` with `currentProfile` and `isStoppedByLimit: true` and resume under the account it
+  recommends. `recommended: null` → nothing is usable: `schedule_create` a one-off resume (`onceAt` =
+  `nextAvailable.at`) whose prompt stands on its own. `nextAvailable` null too → no account names a time it frees
+  up: ask the user a native question (nothing can run) and `schedule_create` the same one-off retry about 30
+  minutes ahead.
+- Your own usage limit is the bot's business: it waits or switches and then wakes you.
+
+## Talking to the user
+
+- The user keeps the bot's topics muted: your plain text reaches the topic silently. Anything they must notice —
+  a blocker, a fork, "ready to push" — ask as a native question (Claude Code: `AskUserQuestion`; OpenCode: its
+  question tool); the bot pins it, and the pin notifies. In autonomous mode stop and report instead.
+- A message headed `[Request <id> · from: …]` is answered through `answer_request` (`progress`, `question`,
+  `final`); do not repeat its text as plain text afterwards.
+- The passing-run video of a new e2e test → `send_file_to_user` (H.264 `.mp4`, sent as a video). Several
+  separate items, e.g. one per finished scope → `send_messages_to_user`.
+- Work the user wants later → `schedule_create` with `onceAt` and a prompt that stands on its own.
+- Write for a non-technical reader: the status, then the next steps as a short numbered list of who does what.
+
+## A tracker conversation (Jira)
+
+There are no `schedule_*` tools and nothing will wake you. Do not end your turn while a worker runs: wait in the
+turn with foreground polls of at most 10 minutes each, checking the same two signals (the PID, the run directory
+changing), report interim progress with `answer_request` kind `progress`, and end with kind `final`.
+
+## Finally
+
+Confirm from the reports that every changed file is listed, verification passed, the reviews are clean and the
+plan is archived. Blocked or incomplete → leave the plan as it is for inspection. Report one line of outcome.

package/dist/adapters/adapterNames.d.ts

@@ -14,6 +14,12 @@ export declare const openCodeAdapterName = "opencode";
  * lifecycle, the same tmux session name and host dir per conversation.
  */
 export declare const claudePerTurnAdapterName = "claude-per-turn";
+/**
+ * The tmux-scrape Claude Code backend (the interactive TUI driven by keystrokes, output scraped from the pane).
+ * DEPRECATED and frozen: no new work and no new-feature tests on it. It stays selectable (`/claude_mode`) and
+ * existing topics on it keep working, but {@link claudeJsonStreamAdapterName} is the recommended backend.
+ */
+export declare const claudeTmuxAdapterName = "claude";
 /** Both backends that run the json-stream host (one process per conversation at a time). */
 export declare function checkIsJsonStreamBackend(name: string): boolean;
 /**

package/dist/adapters/adapterNames.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapterNames.d.ts","sourceRoot":"","sources":["../../src/adapters/adapterNames.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wFAAwF;AACxF,eAAO,MAAM,2BAA2B,uBAAuB,CAAC;AAEhE,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D,4FAA4F;AAC5F,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D"}
+{"version":3,"file":"adapterNames.d.ts","sourceRoot":"","sources":["../../src/adapters/adapterNames.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wFAAwF;AACxF,eAAO,MAAM,2BAA2B,uBAAuB,CAAC;AAEhE,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,WAAW,CAAC;AAE9C,4FAA4F;AAC5F,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D"}