overcode 0.5.7__tar.gz → 0.5.8__tar.gz

{overcode-0.5.7/src/overcode.egg-info → overcode-0.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overcode
-Version: 0.5.7
+Version: 0.5.8
 Summary: A supervisor for managing multiple Claude Code instances in tmux
 Author: Mike Bond
 Project-URL: Homepage, https://github.com/mkb23/overcode
@@ -111,6 +111,7 @@ The TUI displays all agents with live status updates, showing:
 - **Agent hierarchy** - parent/child delegation with follow mode and reporting
 - **Cost budgets** - per-agent spending limits with automatic enforcement
 - **Sleep mode** - pause agents and exclude them from stats
+- **Shutdown and revive**: `overcode shutdown` stops agents, jobs, daemons and tmux sessions and keeps the agent records. After a reboot, `overcode revive --all` brings the agents back with their conversations.
 
 ### Supervisor Daemon
 An optional Claude-powered orchestrator that:
@@ -168,6 +169,7 @@ Aggregate agents from multiple machines into one dashboard:
 | `q` | Quit (or detach in tmux split) |
 
 See the [TUI Guide](docs/tui-guide.md) for all keyboard shortcuts.
+Every key can be remapped, and a `vscode` preset avoids the keys VSCode's terminal swallows: `overcode keys --use vscode` (see [Configuration → Keybindings](docs/configuration.md#keybindings)).
 
 ## Documentation
 

{overcode-0.5.7 → overcode-0.5.8}/README.md

@@ -69,6 +69,7 @@ The TUI displays all agents with live status updates, showing:
 - **Agent hierarchy** - parent/child delegation with follow mode and reporting
 - **Cost budgets** - per-agent spending limits with automatic enforcement
 - **Sleep mode** - pause agents and exclude them from stats
+- **Shutdown and revive**: `overcode shutdown` stops agents, jobs, daemons and tmux sessions and keeps the agent records. After a reboot, `overcode revive --all` brings the agents back with their conversations.
 
 ### Supervisor Daemon
 An optional Claude-powered orchestrator that:
@@ -126,6 +127,7 @@ Aggregate agents from multiple machines into one dashboard:
 | `q` | Quit (or detach in tmux split) |
 
 See the [TUI Guide](docs/tui-guide.md) for all keyboard shortcuts.
+Every key can be remapped, and a `vscode` preset avoids the keys VSCode's terminal swallows: `overcode keys --use vscode` (see [Configuration → Keybindings](docs/configuration.md#keybindings)).
 
 ## Documentation
 

{overcode-0.5.7 → overcode-0.5.8}/docs/README.md

@@ -11,6 +11,7 @@ Welcome to the overcode documentation. Overcode is a TUI supervisor for managing
 | [CLI Reference](cli-reference.md) | Complete reference for all commands and options |
 | [Configuration](configuration.md) | Config file, environment variables, and presets |
 | [Advanced Features](advanced-features.md) | Sleep mode, remote monitoring, and more |
+| [Skill Profiles](skill-profiles.md) | Named sets of skills switched on per agent, instead of always on |
 | [Agent Backends](backends.md) | Running opencode/Codex/Grok agents; support matrix and flag mapping |
 | [Claude Session Files](claude-session-files.md) | How token counting and cost estimation works internally |
 

{overcode-0.5.7 → overcode-0.5.8}/docs/cli-reference.md

@@ -20,6 +20,7 @@ overcode launch --name <name> [options]
 | `--skip-permissions` | | Auto-deny permission prompts |
 | `--bypass-permissions` | | Bypass all permission checks (dangerous) |
 | `--parent` | | Name of parent agent (auto-detected if launched from within an agent) |
+| `--no-parent` | | Launch top-level instead of as the calling agent's child. Only the overagent may use it from inside an agent, for agents you will drive yourself (a guard against accidents, not a sandbox) |
 | `--follow` | `-f` | Stream child output, block until report or timeout |
 | `--on-stuck` | | Policy when child stops without reporting: `wait` (default), `fail`, `timeout:DURATION` |
 | `--oversight-timeout` | | Shorthand for `--on-stuck timeout:DURATION` (e.g., `5m`, `1h`, `30s`) |
@@ -29,6 +30,7 @@ overcode launch --name <name> [options]
 | `--budget` | `-b` | Cost budget in USD (deducted from parent if parent has budget) |
 | `--wrapper` | `-w` | Wrapper script: path or name from `~/.overcode/wrappers/` (e.g., `devcontainer`) |
 | `--no-inherit` | | Don't inherit settings from the parent agent (see below) |
+| `--skills` | | Skill profile to switch on; `none` for none. Default: the parent's, then the folder's pinned profile. See [Skill Profiles](skill-profiles.md) |
 | `--session` | | Tmux session name (default: `agents`) |
 
 **Parent settings inheritance (#433):** when launched from within an agent (or with `--parent`), the child inherits the parent's `provider`, `model`, `wrapper`, agent-teams setting, and permission mode for any of those not given explicitly. Resolution order is: explicit flag > parent setting > `new_agent_defaults` in `~/.overcode/config.yaml` > built-in default. So a parent pinned to Bedrock spawns Bedrock children unless told otherwise. Use `--no-inherit` to skip the parent and resolve from config defaults only.
@@ -107,6 +109,85 @@ overcode kill <agent-name> [--no-cascade] [--session <session>]
 
 By default, killing a parent also kills all its descendants (deepest-first).
 
+### `overcode restart`
+
+Restart an agent with the same launch configuration, resuming its conversation.
+
+```bash
+overcode restart <agent-name> [--fresh] [--model <model>] [--session <session>]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--fresh` | Start a new conversation instead of resuming |
+| `--model`, `-m` | Relaunch on this model (kept for later restarts) |
+
+If the agent's tmux window is gone (it was killed, or the machine rebooted),
+`restart` revives it in a new window instead.
+
+### `overcode revive`
+
+Bring back agents whose tmux window is gone, for example after a reboot.
+
+```bash
+overcode revive <agent-name> [--fresh] [--dry-run]
+overcode revive --all [--all-sessions] [--fresh] [--dry-run]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--all`, `-a` | Revive every dead agent, parents before children |
+| `--all-sessions` | With `--all`: every overcode tmux session, not just this one |
+| `--fresh` | Start new conversations instead of resuming |
+| `--dry-run`, `-n` | List what would be revived, change nothing |
+
+Each agent is relaunched in a new window with its full launch context. It
+resumes its previous conversation when one is recorded and its backend can
+resume. Otherwise it starts fresh, and the output gives the reason. Done
+children and children that filed a report are skipped. The monitor daemon is
+started if it isn't running. In the TUI, the command palette has the same
+action: **Revive all dead agents**.
+
+### `overcode shutdown`
+
+Stop everything overcode is running.
+
+```bash
+overcode shutdown [--dry-run] [--yes] [--force] [--keep-jobs] [--all] [--timeout <s>]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run`, `-n` | List what would be stopped, change nothing |
+| `--yes`, `-y` | Skip the confirmation (the plan is printed first otherwise) |
+| `--force` | Kill agent windows without a graceful exit |
+| `--keep-jobs` | Leave the `jobs` tmux session running |
+| `--all`, `--all-sessions` | Every overcode tmux session, not just this one |
+| `--timeout` | Seconds to wait for agents to exit before killing their windows (default 10) |
+
+Steps run in this order:
+
+1. The supervisor daemon.
+2. Agents, children first. Each gets its backend's exit keys, then its window is killed.
+3. The `jobs` tmux session.
+4. The monitor daemon, the web server, the presence logger, and any legacy PID files.
+5. overcode's tmux sessions: the agents session, `oc-view-*`, the `overcode` split layout and the supervisor controller.
+
+Agent records are kept, so `overcode revive --all` brings the agents back
+later with their conversations. The shared pieces (the split and controller
+sessions, the presence logger) are left alone while another overcode tmux
+session is still running.
+
+The tmux session you run the command from is killed last. An agent that runs
+`shutdown` itself is not exited, and its window closes with that session.
+
+In the TUI, the command palette has **Shut down overcode**. Run it twice to
+confirm, and the TUI exits at the end. A web server with
+`web.allow_control: true` also takes `POST /api/shutdown`. Its default body
+stops only the supervisor, the monitor and the web server, and agents keep
+running. `{"scope": "all"}` does the full shutdown, and `"dry_run": true`
+returns the plan instead.
+
 ### `overcode rename`
 
 Rename an agent, keeping its conversation, status history and costs.
@@ -441,6 +522,29 @@ overcode supervisor-daemon watch [--session <session>]
 
 ---
 
+## Skill Profile Commands
+
+See [Skill Profiles](skill-profiles.md) for the whole picture.
+
+| Command | What it does |
+|---------|--------------|
+| `overcode skills list` | The library, each CLI's always-on skills, profiles and pinned folders |
+| `overcode skills profile set <name> <skill>...` | Create a profile or replace its skills |
+| `overcode skills profile add\|remove <name> <skill>...` | Change a profile's skills |
+| `overcode skills profile show <name>` | What a profile adds and hides for each CLI |
+| `overcode skills profile list` / `delete <name>` | List or delete profiles |
+| `overcode skills profile emoji <name> [emoji]` | The emoji the PRF column shows for a profile; no emoji goes back to the default 🎒 |
+| `overcode skills pin <profile> [dir]` / `unpin [dir]` | New agents in a folder (and below) get this profile |
+| `overcode skills library add\|remove <path>` | Read library skills from another folder too |
+| `overcode skills adopt <skill>...` | Move always-on personal skills into the library |
+
+```bash
+overcode skills library add ~/Code/team-skills
+overcode skills profile set research shirka dataviz
+overcode skills pin research ~/Code/papers
+overcode launch -n reader -d ~/Code/papers        # gets 'research'
+```
+
 ## Wrapper Commands
 
 ### `overcode wrappers list`
@@ -504,6 +608,22 @@ overcode config path
 
 ---
 
+## Key Commands
+
+### `overcode keys`
+
+Show the TUI's effective keys, grouped like the command palette, with where each comes from: `default` (in code), the preset's name, or `override` (your config). See [Configuration → Keybindings](configuration.md#keybindings).
+
+```bash
+overcode keys                        # every scope
+overcode keys --scope command_palette
+overcode keys --preset vscode        # preview a preset (with your overrides)
+overcode keys --conflicts            # warnings only: unknown actions, duplicate keys, swallowed keys, shadowed passthru keys
+overcode keys --use vscode           # switch preset (writes keys.preset to config.yaml)
+overcode keys --presets              # list presets
+overcode keys --all --json           # include palette commands with no key; machine-readable
+```
+
 ## Activity Commands
 
 What the [usage log](configuration.md#usage-log) has recorded about how you

{overcode-0.5.7 → overcode-0.5.8}/docs/configuration.md

@@ -110,7 +110,6 @@ sisters:
 # Overrides built-in defaults shown in the "Available Skills" (ASK) column
 skill_emoji:
   overcode: 🐙           # Default: 🐙 (built-in)
-  delegating-to-agents: 👥  # Default: 👥 (built-in)
   claude-api: 🔌         # Default: 🔌 (built-in)
   simplify: ✨            # Default: ✨ (built-in)
   shirka: 🔬             # Custom skill example
@@ -163,8 +162,11 @@ new_agent_defaults:
   provider: web               # "web" (Claude.ai OAuth) or "bedrock" (AWS)
   wrapper: ""                 # Wrapper script name or path (e.g., "devcontainer")
   backend: claude-code        # claude-code | opencode | opencode2 | codex | grok — see docs/backends.md
+  skill_profile: research     # Skill profile when neither parent nor folder sets one — see docs/skill-profiles.md
 ```
 
+Skill profiles, the skill library and folder pins live under a `skills:` key; see [Skill Profiles](skill-profiles.md).
+
 These apply to agents created via both the CLI (`overcode launch`) and the TUI (`n` key). CLI flags override config defaults, and for child agents the parent's settings take precedence over config defaults (#433): explicit flag > parent setting > config default > built-in default. Use `--no-inherit` to skip the parent.
 
 Setting `wrapper: devcontainer` makes all new agents launch inside a Docker container by default. See the [Wrappers Guide](wrappers.md) for details.
@@ -205,7 +207,7 @@ exact footprint and the `overcode hooks uninstall-backend` cleanup commands.
 
 By default, a handful of TUI hotkeys are forwarded straight to the focused agent's Claude Code session rather than being handled by overcode: `Enter`, `Esc`, `1`–`5` (for numbered prompts), and `Ctrl+O`.
 
-You can toggle these on and off from inside the TUI with `Ctrl+K`, which saves your choices to `config.yaml`. For more advanced customization — remapping a slot to send a different key, or adding fully new passthru keys — edit `~/.overcode/config.yaml` directly:
+You can toggle these on and off from inside the TUI with `Ctrl+K` (`^` under the vscode [key preset](#keybindings)), which saves your choices to `config.yaml`. For more advanced customization — remapping a slot to send a different key, or adding fully new passthru keys — edit `~/.overcode/config.yaml` directly:
 
 ```yaml
 passthru_keys:
@@ -229,6 +231,60 @@ passthru_keys:
 
 Only deltas from the defaults are written — a fresh config keeps the section empty. Disabled slots show `☐` in the modal; remapped slots show their target in yellow.
 
+## Keybindings
+
+Every TUI key can be changed under `keys:` in `~/.overcode/config.yaml` (#510):
+
+```yaml
+keys:
+  preset: vscode                     # default | vscode
+  overrides:                         # main-screen actions
+    jump_to_agent: [ctrl+j, J]       # action -> one key or a list
+    toggle_monochrome: null          # unbind
+    reverse_sort: R                  # palette-only commands can be bound too
+  scopes:                            # keys inside widgets
+    command_palette:
+      cursor_down: [down, ctrl+n]
+    command_bar:
+      toggle_expand: ctrl+l
+```
+
+- **Layers.** The default keys are the ones in code (`SupervisorTUI.BINDINGS` plus each widget's own list). A preset is a delta on top of them, and `overrides` / `scopes` are a delta on top of the preset. Each entry names an action and gives its *complete* key list, replacing what the layer below bound.
+- **Action names** are the palette's: `overcode view actions` lists them, and `overcode keys` shows every scope's actions with their current keys.
+- **Key names** are Textual's (`ctrl+p`, `question_mark`, `pagedown`, `J` for shift+j). Characters (`?`, `@`, `|`), caret (`^P`) and tmux (`C-p`, `M-j`) spellings are accepted too.
+- **Scopes:** `app` (the main screen, which `overrides` sets), `command_bar`, `command_palette`, `fullscreen_preview`, `summary_prompt_lab`.
+- **Problems are warnings, never crashes:** an unknown action or scope, a key bound twice in one scope, a key the preset avoids, a typing key bound inside a text field, or a key that shadows a [passthru key](#passthru-keys). The TUI mentions them at startup; `overcode keys --conflicts` lists them.
+
+```bash
+overcode keys                  # effective keys, grouped, with source (default / preset / override)
+overcode keys --preset vscode  # what a preset would give you (with your overrides)
+overcode keys --conflicts      # only the warnings
+overcode keys --use vscode     # switch preset (writes keys.preset)
+overcode keys --presets        # list presets
+```
+
+The palette's **Key preset** command switches preset and rebinds the running TUI immediately. The help overlay (`h`), the palette and the footer always show the keys in effect.
+
+### VSCode preset
+
+VSCode's integrated terminal runs some keys as VSCode commands instead of passing them to the program (`terminal.integrated.commandsToSkipShell`). On Linux/Windows that takes `Ctrl+P` (Quick Open), `Ctrl+K` (chord prefix), `Ctrl+G` (recent directory), `Ctrl+E`, `Ctrl+J` and `Ctrl+F`; on every OS it takes `Ctrl+Space`, ``Ctrl+` ``, `Ctrl+Tab`, `Ctrl+Q` and `F1`. On macOS most workbench shortcuts use Cmd, so the Ctrl keys get through there, but they still clash with VSCode habits. The `vscode` preset moves off all of them:
+
+| Action | Default | vscode |
+|---|---|---|
+| Jump to agent | `Ctrl+P` | `Space` |
+| Rename agent | `Ctrl+N` | `N` |
+| Send Ctrl+O to agent | `Ctrl+O` | `v` |
+| Passthru keys… | `Ctrl+K` | `^` |
+| Cycle focal repo | `Ctrl+R` | `@` |
+| Enhanced context | `Ctrl+T` | `+` |
+| Tmux toggle key… | `Ctrl+G` | `\|` |
+| Command bar: multi-line | `Ctrl+E` | `Ctrl+L` |
+| Palette: next / previous | `↓` `Ctrl+N` `Ctrl+J` / `↑` `Ctrl+P` `Ctrl+K` | `↓` / `↑` |
+
+It also recommends a tmux pane toggle key other than `Ctrl+Space` (`Tab`, the default); your `tmux.toggle_key` is never changed for you. `overcode doctor` suggests the preset when it sees `TERM_PROGRAM=vscode`.
+
+The alternative is to keep the default keys and let VSCode pass them through: add the command with a `-` prefix to `terminal.integrated.commandsToSkipShell` (e.g. `"-workbench.action.quickOpen"` for `Ctrl+P`), set `terminal.integrated.allowChords` to `false` for `Ctrl+K`, or set `terminal.integrated.sendKeybindingsToShell` to `true`.
+
 ## Standing Instruction Presets
 
 Presets are saved in `~/.overcode/presets.json`. View available presets:
@@ -616,8 +672,7 @@ Overcode displays emoticons for available skills in the TUI's "Available Skills"
 
 | Skill | Default Emoji | Purpose |
 |-------|:-------------:|---------|
-| `overcode` | 🐙 | Overcode CLI commands reference |
-| `delegating-to-agents` | 👥 | Parallel agent delegation |
+| `overcode` | 🐙 | Running and managing agents through overcode |
 | `claude-api` | 🔌 | Claude API/SDK development |
 | `simplify` | ✨ | Code quality review |
 | `commit` | 📦 | Git commit creation |
@@ -639,7 +694,7 @@ skill_emoji:
 ```
 
 Emoticons appear in:
-- TUI "Available Skills" (ASK) column when viewing agents with `--full` detail
+- TUI "Available Skills" (ASK) column when viewing agents with `--full` detail. Hover an agent's emoji cell (skills, PRF, tools, wrapper, status detail) to see what each emoji stands for.
 - Skill selection dialogs
 - Agent summary outputs
 

{overcode-0.5.7 → overcode-0.5.8}/docs/design/README.md

@@ -12,6 +12,13 @@ This directory contains technical design documents, architecture analysis, and i
 - **Audience:** Contributors, architects, anyone considering remote agent monitoring integration
 - **Key Finding:** ACP covers ~25-30% of overcode features; recommend hybrid model (sister protocol for control, ACP for observability)
 
+### Background Shell Classification (proposal)
+- **File:** `background-shell-classification.md`
+- **Status:** Proposal / Not implemented
+- **Date:** October 2026
+- **Summary:** Telling an agent's background shells apart: services (never finish, don't wake the agent), batch work (finishes and wakes it) and watchers (fire on a condition; stuck once their target has ended). Proposes reading live shells from the process table, a rules → runtime signals → target liveness → cached LLM classifier pipeline, and `overcode jobs wait` so watchers can't outlive their target. Issue #515; builds on #507.
+- **Audience:** Contributors
+
 ### Model Alias Resolution (proposal)
 - **File:** `model-alias-resolution.md`
 - **Status:** Proposal / Not implemented

overcode-0.5.8/docs/design/background-shell-classification.md

@@ -0,0 +1,103 @@
+# Background shells: services, batch work and watchers
+
+- **Status:** Proposal / Not implemented
+- **Date:** October 2026
+- **Issue:** [#515](https://github.com/mkb23/overcode/issues/515)
+- **Builds on:** #507 (the status model where yellow means "idle at the prompt, but work in flight elsewhere will wake it")
+
+## Problem
+
+Since #507, an agent sitting at the prompt while it has background shells running shows **yellow** with a `bg_task` badge ("background shell or task running"). The evidence is Claude Code's status bar (`· N shells ·`), because no hook fires when a background shell exits. Live-verified on Claude Code 2.1.286: a background Bash's PreToolUse and PostToolUse land about 70 ms apart, and its completion arrives later only as a fresh UserPromptSubmit.
+
+That badge treats every background shell the same, but they mean very different things for the question yellow answers: *will this agent pick itself back up without you?*
+
+| Kind | Examples | Finishes? | Wakes the agent? | What overcode should show |
+|---|---|---|---|---|
+| **Service** | dev servers, `npm start`, `vite`, `uvicorn`, `serve --forever`, `tail -f` | Never, by design | No | A neutral "server up" badge. Not work in flight: an agent whose only background shell is a service is effectively idle. |
+| **Batch** | builds, test suites, benchmarks, data jobs | Yes | Yes, when it ends | Yellow, as today |
+| **Watcher** | `until … \| grep -q …; do sleep N; done`, `overcode follow X`, `gh run watch N`, `sleep N && check` | When its condition comes true | Yes, when it fires | Yellow while its target is alive. **Stuck** when the target has ended and the watcher is still polling. |
+
+### The case that prompted this
+
+An agent stayed yellow for about 6h40m. Its only background shell was a hand-rolled wait loop:
+
+```sh
+until overcode jobs tail <job> -n 40 | grep -qE 'expected marker|Error|Traceback'; do sleep 3; done
+```
+
+The job it watched had never started (see *Related bug*). The job's pane showed only a shell parse error, which matches none of those words, so the loop polled every 3 s indefinitely. The agent looked busy the whole time, and nothing pointed at the dead watcher.
+
+## Design
+
+### 1. Know which shells are alive, and what they run
+
+The status-bar count says *how many* shells are running, never *which*. The process table says both. On macOS and Linux, each Claude Code background shell is a child of the agent CLI's process:
+
+```
+claude --session-id …            ← the agent (pid known to overcode)
+└─ /bin/zsh -c source …/shell-snapshots/… && eval '<command>' …
+   └─ sleep 3                    ← a poll loop's current iteration
+```
+
+overcode already tracks the agent's pid for CPU and memory sampling (`process_resources.py`). Listing its children, and parsing the `eval '<command>'` back out, gives the live shells with their commands and ages. It can also be joined to the PreToolUse that launched each one (`tool_input.command`, `description`, `run_in_background`) by command text. This replaces the status-bar count as the source of truth, with the count kept as a fallback where the process walk isn't available (e.g. agents inside containers).
+
+### 2. Classify each shell
+
+Cheapest signal first. Each later step runs only when the earlier ones are inconclusive.
+
+1. **Rules on the command and description.** Claude's `description` field is often explicit ("Start dev server", "Wait for CI").
+   - **Service:** `serve`, `start`, `dev`, `--watch`, `--forever`, `tail -f`, `docker compose up`, a `--port` flag with no terminating step.
+   - **Watcher:** `until`/`while` loops around `sleep`, `overcode follow`, `overcode jobs tail` inside a loop, `gh run watch`, `gh pr checks --watch`, `kubectl wait`.
+   - **Batch:** everything else.
+2. **Runtime behaviour**, from the same process walk:
+   - A **listening socket** under the shell (`lsof -a -p <pids> -iTCP -sTCP:LISTEN`) means service.
+   - A **recurring `sleep` child**, a new pid every few seconds, means a poll loop.
+   - **CPU time increasing** means it's doing work. Near-zero CPU for a long time, outside a poll loop, means it's waiting on something.
+   - **Output growing**: Claude writes each background shell's output to a task file. Growth means alive and producing.
+3. **Target liveness, for watchers.** Extract the target from the command and check it:
+   - `overcode follow X` / `overcode jobs tail X` → the agent or job's state
+   - `gh run watch N` → the run's state
+   - `kubectl wait …` → leave as unknown
+
+   A watcher whose target has ended (or never started) but is still polling is **stuck**. That would have flagged the case above within seconds of the job failing.
+4. **An LLM classifier for whatever is still ambiguous.** Use the summarizer path that already exists, prompted with the command, description, age and runtime signals, returning `service | batch | watcher` plus a target if it's a watcher. Cache the result per command hash, so each distinct command is classified once.
+
+### 3. What the person sees
+
+- **DTL badges** split the current `bg_task`:
+  - ⚙️ batch (yellow, wakes the agent)
+  - 👀 watcher (yellow)
+  - 🖥 service (neutral: doesn't make the agent yellow on its own)
+  - ⚠️ stuck watcher
+- **Colour:**
+  - services alone don't hold an agent yellow;
+  - batch and live watchers do;
+  - a stuck watcher shows a warning, and possibly escalates to red with "watcher stuck: target ended" (open question).
+- **Hover** on DTL lists each shell: command, kind, age, CPU, and for watchers what they're watching and whether it's still alive.
+
+### 4. Prevention
+
+Detection catches stuck watchers; better tools stop agents writing them.
+
+- **Add `overcode jobs wait <job> [--until REGEX] [--timeout D]`.** It exits 0 when the pattern appears, and non-zero when the job ends or fails first, or the timeout passes. It never outlives its target. A watcher written this way can't get stuck, and its target is explicit.
+- **The overcode skill** already tells agents to run servers as `overcode bash` jobs (visible in the jobs list and monitor bar) rather than Claude background shells. It should also steer agents to `jobs wait` / `follow` instead of hand-rolled loops. Then Claude's own background shells are mostly batch and watcher work, which is the easy part to classify.
+
+## Related bug
+
+`job_launcher.py` builds the job's tmux command as one line:
+
+```python
+f"echo '│ Command: {command}' && "   # raw command inside single quotes
+…
+f"eval '{escaped_cmd}'; "             # this one is escaped
+```
+
+A job command containing a single quote (e.g. `…; echo 'done'`) breaks the quoting of the whole line. The job never runs, `overcode jobs _complete` never fires, and with unlucky contents, fragments of the command run unquoted in the header. The job name and directory are interpolated the same way. **Fix:** build the header lines with `shlex.quote`. This is independent of the rest of this design and worth fixing first.
+
+## Open questions
+
+1. Should a service alone keep an agent yellow? Proposed: **no**. Show it, but the agent is idle.
+2. Should a stuck watcher turn the agent red, or only add a warning badge?
+3. Should overcode ever kill a stuck watcher itself? Proposed: **no**. Flag it, and let the person or the agent decide.
+4. Where should the process walk run: in the daemon's per-tick resource sampling (where the pid is already known) or in a slower housekeeping pass? Shells change rarely, so every 10–30 s is probably enough.
+5. Containers and remote sisters: the process walk only sees local processes. Fall back to the status-bar count there.

{overcode-0.5.7 → overcode-0.5.8}/docs/design/opencode-stats-reader-performance.md

@@ -230,8 +230,51 @@ lock, and the worst race is one duplicated parse.
 - The Claude backend's `read_window_token_usage` re-parses JSONL at the
   same 1 Hz cadence with no cache. It has not been reported as a problem.
 
+## Follow-up: the burn rate reuses the stats scan (#517)
+
+At fleet scale the per-scan cost was no longer the issue; the number of
+scans was. The status bar's burn rate asks every agent for its window usage
+once a second, and each answer was a full scan. The TUI's stats sweep scans
+again every 5 s. That is six scans per agent per 5 s. A 23-agent fleet
+profiled at ~37% CPU, with `_scan_messages` in 76% of samples.
+
+#517 proposed memoizing both `get_stats` and `get_window_token_usage` for
+60 s. It was not merged, for the same reason as #476's patch. The token,
+cost and context columns have a 5 s freshness contract, and the TUI's
+own 5 s sweep (not the daemon's 60 s sync) is what keeps them there. A
+60 s cache would have let them go up to a minute stale. Bucketing `since`
+to 60 s also summed up to 59 s of turns that had already left the window.
+
+What shipped instead:
+
+- `get_stats` is never cached. Its scan, which it runs anyway, now also
+  builds a `WindowIndex`: the assistant turns' token usage, sorted by
+  `time_created`, with suffix sums. The scan publishes it under (store,
+  table, conversation ids).
+- `get_window_token_usage` reuses a published index younger than
+  `WINDOW_INDEX_MAX_AGE_SECONDS` (10 s, inside the burn rate's 5-30 s
+  contract), else scans and publishes one itself. The index answers any
+  `since` exactly with a bisect, so the per-second sliding window costs
+  nothing extra and there is no bucketing error.
+- Indexes are immutable and shared by v1 and v2 (the table is in the key).
+  The store is bounded at 256 entries, and expired entries are evicted
+  first.
+
+At the TUI's cadence on the 2.3 GB generated store, 23 agents:
+
+| owned ids per agent | before | after |
+|---|---|---|
+| 1 | 24-33 ms/s | 9-10 ms/s |
+| 3 | 74-101 ms/s | 17-22 ms/s |
+| 8 | 101-152 ms/s | 24-34 ms/s |
+
+(The ranges span opencode and opencode2.) What remains is `get_stats` every
+5 s, which the columns' contract requires, plus a connection and session-row
+lookup per window call. Tests: `TestWindowIndexReuse`, `TestWindowIndex` and
+`TestWindowIndexStore` in `tests/unit/test_opencode_scan_cost.py`.
+
 ## References
 
-- Issue #476
+- Issues #476, #517
 - `scripts/make_opencode_store.py`, `scripts/bench_opencode_scan.py`
 - `docs/design/agent-agnostic-backends-opencode.md` (the reader's origin)

{overcode-0.5.7 → overcode-0.5.8}/docs/design/scaling-audit-2026-09-22.md

@@ -587,6 +587,20 @@ Return early when the probe is disabled, cap the buffer, and prune the preferenc
 5. **Count tmux commands, then cut them at source.** Persistent RealTmux in the daemon and web tier; one `list-panes -F` for pids and pane activity per sync; capture only panes whose activity changed, 40 lines for enrichment (R7, R9, R11).
 6. **Log status changes, not samples.** A history row on change plus a periodic keepalive, byte-based hook-log rotation with truncated inputs, presence tail-reads (R10, R12, R13).
 
+## Follow-up (2026-10-06): R15-R18 were not in the fix programme
+
+The fix programme above covered R1-R14, which shipped in 0.5.5. R15-R18 were
+never scheduled, and the scale tier only built Claude fleets, so nothing
+budgeted the other backends. A user then hit the opencode burn-rate rescan at
+37% CPU (#517, fixed). Since then:
+
+- `scripts/bench_backends.py` and `tests/scale/test_backend_budgets.py` budget
+  the opencode, opencode2, codex, grok and hermes readers at the TUI's cadence.
+- R15 is tracked in #524 (codex), #525 (grok), #526 (opencode row cache) and
+  #527 (hermes). Each issue has a strict xfail budget.
+- R16-R18 were re-checked against main and are tracked in #528: 3 fixed
+  incidentally, 9 partly fixed, 7 open.
+
 ## What history says
 
 100 prior incidents were mined from git history, GitHub issues and PRs, `AUDIT.md` and the March 2026 UX performance analysis, each checked against current source. Most still-open ones added a cache or cap to one call site and left its siblings alone; the tiered capture from #161 was silently lost and only rediscovered in 0.5.4.

overcode-0.5.8/docs/release-notes-0.5.8.md

@@ -0,0 +1,8 @@
+# Overcode 0.5.8 Release Notes
+
+- **Agents show their own model and effort.** Another Claude in the same repo (the IDE, a terminal, an agent in another overcode session) could become an agent's conversation, and `/clear` could move an agent back to the one it left. The agent's hooks now decide.
+- **Skill profiles (#499).** Named sets of skills per agent, edited with `W`. `delegating-to-agents` is merged into one rewritten `overcode` skill (`overcode skills install` to update).
+- **Status colours (#507).** Background shells and subagents show yellow, not red. A re-prompt after an interrupt or an answered permission shows the right colour. Restarting the TUI no longer rings every red agent's bell.
+- **`restart` keeps the agent's model (#505)**, and `restart --model` changes it. Light mode, bulk revive, `shutdown` and configurable keys (#508–#510).
+- **PR column reads Claude Code's own PR link (#489).** A JOB column per agent (#463), and clicking a row switches the pane to it.
+- **Fixes:** multi-line launch prompts submit; no emoji too new for VS Code's terminal (#504); the overagent can launch top-level agents.

overcode-0.5.8/docs/skill-profiles.md

@@ -0,0 +1,117 @@
+# Skill Profiles
+
+Agent CLIs treat installed skills as **always on**. Anything in `~/.claude/skills` is offered to every Claude Code session, and opencode reads the same folder (plus `~/.agents/skills`). So installing a skill for one project switches it on everywhere, in more than one tool.
+
+Skill profiles turn that around:
+
+- **The library** holds skills that are *installed but off*. No agent CLI looks there by itself.
+- **A profile** is a named list of skills, such as `research` or `ios`.
+- **Launching an agent with a profile** switches its skills on *for that agent only*. Your other personal skills are hidden for that session.
+- **A folder can be pinned** to a profile, so new agents started there get it by default.
+
+Nothing is written into your project folders or into `~/.claude`. When the agent ends, its skills go with it.
+
+Supported backends: **Claude Code** and **opencode**. Other backends launch as normal and ignore the profile.
+
+## The library
+
+Library skills come from:
+
+1. `~/.overcode/skills/`: copy skill folders (each with a `SKILL.md`) in here.
+2. Any folders you add, such as skill or plugin repos checked out in your code root:
+
+   ```bash
+   overcode skills library add ~/Code/team-skills
+   ```
+
+overcode searches these folders for `SKILL.md` files. It skips hidden folders and `node_modules`, and goes no more than 6 levels deep. Repos stay where you keep them, and `git pull` updates every profile that uses them. If two folders have a skill with the same name, the first one wins; `overcode skills list` warns about it.
+
+Don't add a folder that an agent CLI already reads, like `~/.claude/skills` or `~/.agents/skills`. Its skills would be always on regardless of profiles, and `overcode skills` warns if you do.
+
+To move always-on skills into the library (it asks first):
+
+```bash
+overcode skills adopt shirka pdf
+```
+
+## Profiles
+
+```bash
+overcode skills profile set research shirka dataviz   # create or replace
+overcode skills profile add research pdf
+overcode skills profile remove research dataviz
+overcode skills profile show research                 # what it adds and hides
+overcode skills profile list
+overcode skills profile delete research
+```
+
+A profile can name a skill by its frontmatter `name` or its folder name.
+
+In the TUI, press **`W`** (or choose *Skill profiles…* in the `/` palette):
+
+- The dialog lists every skill, with the ones agents use most at the top, and a checkbox for the selected profile.
+- `space` switches the highlighted skill on or off, `← →` changes profile, `n` makes a new one, and `D D` deletes it.
+- `p` pins the profile to the focused agent's folder.
+- Always-on skills show which CLIs load them (`on: Claude+opencode`) and are marked *hidden* when the profile leaves them out.
+
+## Which profile an agent gets
+
+The first of these that applies:
+
+1. `overcode launch --skills <profile>`, or the **Skills** field in the new-agent dialog (`n`). `--skills none` means no profile.
+2. The parent agent's profile, for child agents (skip it with `--no-inherit`).
+3. The profile pinned to the folder, or its nearest pinned parent folder:
+
+   ```bash
+   overcode skills pin research ~/Code/papers     # default: the current folder
+   overcode skills unpin ~/Code/papers
+   ```
+
+   Pins live in `~/.overcode/config.yaml`, not in the folder.
+4. `new_agent_defaults.skill_profile` in config, or the *Skill profile* row in the `G` dialog.
+
+An agent without a profile launches exactly as before, with nothing hidden.
+
+The profile is recorded on the agent and applied again on every restart, so edits to a profile take effect the next time an agent starts. The **PRF** column shows each agent's profile as one emoji; hover it to see the profile's name and skills. Pick a profile's emoji with `overcode skills profile emoji <name> <emoji>` (🎒 until you do).
+
+## What happens at launch
+
+overcode builds `~/.overcode/skill-profiles/<profile>/`, a folder of links to the profile's library skills, and then:
+
+| | Profile skills added | Other personal skills hidden |
+|---|---|---|
+| **Claude Code** | `--plugin-dir <profile folder>`. The skills appear as `<profile>:<skill>` | `skillOverrides: {"<skill>": "off"}` in the launch `--settings` |
+| **opencode** | `OPENCODE_CONFIG_DIR=<profile folder>`, alongside `~/.config/opencode` | `"skill": {"<skill>": "deny"}` in `OPENCODE_PERMISSION`, which removes them from the list the model sees |
+
+What counts as a *personal* skill for each CLI:
+
+- **Claude Code:** `~/.claude/skills/<name>/`.
+- **opencode:** everything under `~/.claude/skills`, `~/.agents/skills` and `~/.config/opencode/skill(s)`, including skills synced from claude.ai.
+
+A project's own skills (its `.claude/skills` or `.opencode/skill`) and each CLI's built-in skills are never hidden.
+
+A profile skill that the CLI already loads as a personal skill is left as it is: not linked a second time, and not hidden.
+
+## Config
+
+```yaml
+# ~/.overcode/config.yaml
+skills:
+  library_paths:
+    - ~/Code/team-skills
+  profiles:
+    research: [shirka, dataviz]
+    ios: [swift-helper]
+  folders:
+    ~/Code/papers: research
+  profile_emoji:        # what the PRF column shows
+    research: 🔬
+new_agent_defaults:
+  skill_profile: research
+```
+
+## Limits
+
+- **Wrappers** (e.g. devcontainer): the profile folder links to paths on the host, so a container only sees them if those paths are mounted.
+- **Codex, Grok, Hermes:** not supported yet. The launch goes ahead without the profile.
+- **Remote launches** on a sister use that machine's own config.