# Release notes

What changed in each release since 2.0, newest first, with what to do on every machine that shares your config root, and how to move from dotagents. How to install a new release is in [Upgrade](setup.md#upgrade).

## To 3.1

Nothing to migrate by hand. A workspace session that is already open keeps its old panes until you close it; run the workspace command again to get the new layout.

- New: `tackroom dash`, a live screen for a terminal pane. It is a terminal view again, after `tackroom tui` was removed in 3.0, and it works differently. `tui` was read-only, with four tabs that loaded once. `dash` is one screen that refreshes itself (the sync state every 30 seconds, the crons every 5 minutes, and on `r`), draws itself again at once when the pane is resized, and acts: Enter runs the selected launchd job now, `p` pauses or resumes it, and `s` syncs, each after a y/n question. It shows the overall state, the failing jobs and those whose last run failed first, by the same job health as the web view, and what is wrong with a harness that drifted. It needs a terminal; elsewhere use `tackroom status` and `tackroom cron collect --table`. See [terminals.md](terminals.md#dash).
- Changed: `tackroom rex`, `tackroom tmux`, `tackroom zellij` and `tackroom tern` open two panes instead of three: `tackroom dash` across the full width on top, with 70% of the height, and the shell below it, which has the focus. The `tackroom status` and `tackroom cron collect --table` panes are replaced by the dash. In Tern the shell is the upper pane and the two share the height, because Tern splits only right and down and has no size option. In Rex the dash pane is labelled `dash`, and the panes no longer wait for Enter to run their command again.
- Changed: `tackroom tui` still fails as an unknown command, and now names `tackroom dash`.
- New: Overview in `tackroom view` has a rail under its headline where every enabled harness hangs a nameplate: straight when in sync, crooked from one hook when it needs a sync, on the floor when it fails, empty hooks when it is not installed. The plates swing when the pointer nudges them, after a sync and when a state changes, and stay still with reduced motion. See [view.md](view.md).

## To 3.0.2

Nothing to migrate by hand. If you read `tackroom status` or `tackroom cron collect --table` in a script, note the changes below; `status --json` and `cron collect` without `--table` are unchanged.

- Changed: `tackroom status` is one screen by default. It prints a title with the overall state, the repo link, the sources and the lock check, then one table with a row per harness. A harness gets a block under the table only when it needs attention: its config could not be read, it drifted, or it lists something to act on. What to do comes last, and a synced setup prints nothing after the table, so the last line is no longer `Everything is synced.`. The title says `synced` or `needs attention`. In a window too narrow for the bordered table, the table loses its borders, then the columns no harness uses, then becomes one line per harness, and the sources lose their URLs where those would wrap. `tackroom status --verbose` prints the block of every harness, with the full lists and native paths, as `status` did before.
- Changed: `tackroom cron collect --table` fits the terminal. On a terminal wider than the table it prints as before. On a narrower one both tables lose their borders, and the jobs table then loses columns (`problems`, `runs`, `source`, `schedule`), then shortens the `id` and the `last run` until it fits. Lines under Outputs and Problems wrap between words. The access table cuts its `detail` the same way. A long `id` is cut in the middle, so the end that tells launchd labels apart stays. A last run that failed shows `exit N` in red. Into a pipe or a file the output keeps every column. The access table now comes first, then the jobs, then Outputs and Problems, so the jobs and problems are the last lines on screen.
- Changed: `tackroom tmux`, `tackroom zellij` and `tackroom rex` put `tackroom status` above the shell on the left, with 70% of that half, and `tackroom cron collect --table` at full height on the right. The shell had the whole left half and the two command panes a quarter of the window each. `tackroom tern` puts the shell above the status pane, in equal halves, because Tern splits only right and down. A session that already exists keeps its old layout: close it and run the command again to get the new one. See [terminals.md](terminals.md).
- Changed: in the Rex workspace the status and crons panes are labelled `status` and `crons`, and Enter in either pane runs its command again, so the pane refreshes without reopening the workspace.

## To 3.0.1

Nothing to migrate by hand, with two things to know. If you use the Herdr panel, copy the mods from `herdr/tackroom/mods/` again. A sync run with a second config file next to `tackroom.yaml`, such as a web view started with `--config`, now stops with an error unless that file lists the pinned skill sources as `tackroom.yaml` does.

- Changed: the web view has a new look. In a window 1100 px wide or more, the Overview puts what is failing or needs attention in the main column and everything else in a rail on the right. Issues and cron jobs are cards with a status icon, section headings carry a count, and on a desktop with a mouse the buttons are 36 px tall instead of 44. Nothing was renamed or moved to another page, and the buttons do what they did.
- Fixed: the audit missed a command split over lines in a script. A download whose `| sh` sat on the next line, after a backslash or after a pipe at the end of the line, did not block. A line that ends with a backslash or a pipe is now also read together with the line after it, so `curl ... \` followed by `| sh` is CRITICAL like the one-line form. Markdown is unchanged. Nothing is retroactive: a pin already in the lock keeps syncing ([skills.md](skills.md#the-audit-gate)).
- Fixed: the audit blocked a skill whose text only names the pattern. "Prefer a package manager over `curl | sh`" was a CRITICAL `remote-exec` finding, so a new pin of that skill did not sync until you accepted it. `curl | sh` and `wget | sh` with nothing between the command and the pipe are no longer a finding, in the gate and in the `tackroom doctor` warning: they name the pattern and download something only where a config file such as `~/.curlrc` supplies the URL. A download with a URL, an option or a variable before the pipe is CRITICAL as before. ([skills.md](skills.md#the-audit-gate)).
- Fixed: in the web view, Run now, Pause and Resume looked dead for a long time. While one job's action ran, every job's buttons were greyed out, and an action first waited for any crons collect in progress, which lasts as long as the slowest host takes to answer over SSH. An action now starts at once. Only the job it acts on has its buttons off, and the button you clicked reads Starting…, Pausing…, Resuming… or Saving…; every other job stays clickable. An action or a host probe that runs past its timeout now returns when the timeout ends, not when the command it started exits.
- Fixed: the Crons tab of the Herdr panel and of the web view left a job whose last run failed out of the line under the headline, so "2 of 18 jobs failing" was followed by counts that added up to 17. The line now starts with it ("1 last run failed, 12 healthy, 2 paused, 1 not run yet"). In the panel, a last run such as "16 min ago" no longer wraps onto a second line in the per-machine list. The web view's fix comes with the release; if you use the Herdr panel, copy the mods from `herdr/tackroom/mods/` again.
- Fixed: a config that named Qwen Code `qwen`, as the other harnesses are named by their short names, was read as an unknown custom harness. It got skills only, and `config inventory`, the web view and the Herdr panel showed `qwen` in lowercase and said it takes no roles; MCP servers, hooks, roles and the root file never reached it. `qwen` is now read as `qwen-code`, as `claude-code` is read as `claude`, in `agents:`, in `--agents` and in the `agents:` lists of MCP servers, hooks and skill sources, and `status` and `config inventory` report it as `qwen-code`. The next sync adds what Qwen Code gets: `skills.directories` in `~/.qwen/settings.json`, your MCP servers and hooks, the roles in `~/.qwen/agents` and `~/.qwen/QWEN.md`. It deletes nothing: the skills link an earlier sync made in `~/.qwen/skills` stays, and `status` counts it as external. `tackroom.yaml` is not rewritten, though a command that edits it, such as `mcp add`, saves the name as `qwen-code`. A config that lists both `qwen` and `qwen-code` now stops with `config agent qwen-code is duplicated`, as `claude` with `claude-code` does; delete one of the two entries ([harnesses.md](harnesses.md#config-keys-and-detection)).
- Fixed: when an outside skill source no longer had a folder listed in its `skill_dirs`, for example because upstream deleted it, `sync` and `pull` stopped with `skill directory "..." not found in cloned external source ...` and nothing else synced, for any source or harness. `skill update` failed the same way, or, for a source without `materialize: true`, pinned the commit without the folder, so every sync after it failed. Now that source alone is blocked: sync keeps its pin and its skill copies, prints a warning and syncs everything else, and `skill update` keeps its previous pin and updates the other sources. `status`, `sync --dry-run` and `config inventory` list it as blocked with the folder and the commit, and `doctor` warns. To clear it, remove or rename the folder in `skill_dirs` in `tackroom.yaml` ([skills.md](skills.md#what-add-writes)). The web view and the Herdr panel show such a source with its reason and that fix, not as an audit finding to accept; if you use the Herdr panel, copy the mods from `herdr/tackroom/mods/` again.
- Fixed: `skill update <name>` dropped from `tackroom.lock` the pin and the materialized skills of every other source whose `url` or `branch` in `tackroom.yaml` no longer matched its lock entry, and the next sync then failed with `collides with unrelated canonical skill`. The entry now stays until a sync or an update of that source replaces it. If a lock already lost pins this way, restore it from git (`git checkout <commit> -- tackroom.lock` in the config root) and run `tackroom sync`.
- Fixed: a sync run with a second config file in the config root, for example from a web view started with `--config ~/.agents/crons.yaml`, emptied `tackroom.lock` and deleted the materialized skill copies in `skills/` whenever that file did not list the outside skill sources, and still reported success. Every config file in a folder shares the lock and `skills/`. Now `sync`, `pull`, `sync --dry-run`, `skill sources add` and the web view's Sync stop before they touch the lock, `skills/` or a harness when the file is not `tackroom.yaml`, a `tackroom.yaml` sits next to it and it leaves out a source the lock pins, or lists it with another url, branch or `materialize`; the error names the sources. `pull` checks after its `git pull`, so an incoming commit that fixes the file lets it sync. If it already happened, restore `tackroom.lock` and `skills/` from git (`git checkout <commit> -- tackroom.lock skills` in the config root), then run `tackroom sync` without `--config` or with `--config` pointing at `tackroom.yaml`.

## To 3.0

- New: `tackroom tmux` and `tackroom zellij`. Each opens a session named `tackroom` in the config root with a shell, `tackroom status` and `tackroom cron collect --table`, and takes `--config PATH` and `--dry-run`, as `tackroom tern` and `tackroom rex` do. A second run shows the existing session. See [terminals.md](terminals.md#tmux) and [terminals.md](terminals.md#zellij)
- Removed: the bundled memory system. tackroom no longer ships memory tiers, the scripts under `memory/` or the `rem` and `knowledge-sync` tools, and `sync` no longer builds Go tools under `memory/tools/`. A memory file now reaches your harnesses as a file listed under `instructions:` ([memory.md](memory.md)).
- Changed: `setup --memory` is still accepted and does nothing. `--memory basic` or `--memory memsearch` prints one line saying so, and setup goes on. `tackroom memsearch`, `setup memsearch` and `status memsearch` are gone, and so are the memsearch lines in `status` and `doctor`. `setup` no longer adds or rewrites memory hooks, in `tackroom.yaml` or in a harness's own config. The sync it runs removes a harness registration only when the memory script it runs is retired, as described below.
- What an existing config keeps: its memory hooks stay in `tackroom.yaml` and sync as ordinary hooks. While a hook entry points at a script under `memory/hooks/`, enabled or not, every file under `memory/` stays, and the first sync stops tracking them in `.tackroom-starter.json` with one note; after that they are yours to delete. With no such hook entry at that first sync, it removes the scripts you never edited and lists the ones you did once. Any sync then also removes a hook registration in a harness's own config that still runs a removed or missing memory script, such as a Pi or OMP module or a Factory `hooks.json` entry left from a memory hook you deleted from `tackroom.yaml`; it backs each one up first, as for any removed hook. A harness turned off with `enabled: false` is not synced, so its registrations stay: `tackroom hook remove --dry-run --agents <name> memory/hooks` lists them, and the same command without `--dry-run` removes them. `memory/tools/`, built `rem` and `knowledge-sync` binaries and `memsearch.conf` are left alone. Details are in [memory.md](memory.md#coming-from-the-bundled-memory).
- `rem` and `knowledge-sync` now live in [the rem repository](https://github.com/yourconscience/rem).
- Changed: the 72-hour wait for a new pin of an outside skill source, or a new npm or PyPI version, is now called a cooldown, and the 72 hours are the minimum release age. The rule itself is unchanged. Output that said `held`, `hold ends` or `held 41h of 72h` now says `cooldown`, `cooldown ends` and `cooldown 41h of 72h`; `status` and `sync --dry-run` list such items under "in cooldown or blocked (skipped by sync)". `--allow-fresh` and `--reason` keep their names and still skip the cooldown.
- Changed: `tackroom.lock` records cooldowns under `cooldowns:`, each with `cooldown_until`, instead of `holds:` and `hold_until`. Nothing to do by hand: the old keys are still read with the same meaning, so an item in cooldown stays in cooldown, and the next command that writes the lock rewrites them as the new keys. In a lock with both keys, an entry under `cooldowns:` wins over one under `holds:` for the same item and ref, and a `holds:` entry with no match is kept. tackroom 2.x does not read `cooldowns:`: a 2.x machine that rewrites a shared lock drops it, and with it any recorded `--allow-fresh` decision, which leaves the item in cooldown. Upgrade every machine that shares the lock.
- Removed: the `held` field of `sync --dry-run --json`, which breaks scripts that read it. The same list, every item sync skips, is now `skipped`, and an item in cooldown there has `"kind": "cooldown"` instead of `"kind": "held"`; a blocked item keeps `"kind": "blocked"`. The lock rows of the web view's `/api/inventory` use `"state": "cooldown"` instead of `"state": "held"`. There is no alias for the old names.
- Changed: the Herdr panel reads `skipped` and is updated in this release; copy the mods from `herdr/tackroom/mods/` again. It still reads `held` from an older tackroom.
- Removed: `tackroom tui`, deprecated since 2.x. It now fails as an unknown command and names the replacement: `tackroom view`, or `tackroom status`, `tackroom cron collect --table` and `tackroom doctor` in a terminal.
- New: `status --json` and `sync --json` list the items sync skips under `skipped`, as `sync --dry-run --json` does; `[]` when there are none.
- New: `--allow-fresh=<item>` prints a warning on stderr for each name that matches nothing in cooldown, with the items that are, and exits 0 as before.
- Fixed: `tackroom status` no longer says "none configured" for the external skill lock when every source is in cooldown or blocked; it shows the counts.
- Fixed: `sync --dry-run` plans the skills a materialized source would add, including one released with `--allow-fresh`. Before, it said `planned none` and the sync then added them.
- Fixed: `sync --json` printed a line from git ahead of the JSON document when a source was blocked. git's output now goes to stderr.
- Fixed: `sync` no longer prints `materialized <from> -> <to>` when the copy did not change.
- Fixed: `sync` reported a memory script you had edited on every run. It lists the script once, stops tracking it and leaves the file alone.
- Fixed: a command that edits `tackroom.yaml` or `tackroom.local.yaml` (`skill sources add`, `mcp add` and `remove`, `config set`, `setup`, the web view) changes only the lines of the entry it touches. Blank lines, comments, an empty list such as `hooks: []`, CRLF line endings and a missing final newline are kept, and untouched entries no longer gain `agents: []`. Before, every such write reformatted the whole file.
- Changed: a first `tackroom setup` writes the starter `tackroom.yaml` as it ships, with the detected agents filled in: it keeps `hooks: []` and its blank lines, and no longer adds `mcp_servers: []`.
- New: a security fix skips the cooldown. When `sync` finds an exact npm or PyPI version in cooldown, it asks [OSV](https://osv.dev) whether a published advisory names that version as its fix; if one does, sync takes the version at once, prints `cooldown skipped for <item> (<ref>): security fix: GHSA-...` and records it in `tackroom.lock` as `--allow-fresh` would, with the advisory ids as the reason. If OSV cannot be reached, the cooldown applies as before. `status` and `sync --dry-run` make no lookup, and git skill sources are not covered ([skills.md](skills.md)).
- New: `trusted_packages` in `tackroom.yaml` or `tackroom.local.yaml` lists the packages, as `npm:<name>` or `pypi:<name>`, whose new versions skip the cooldown. Without the key the list is `npm:@openai/codex`, `npm:@anthropic-ai/claude-code` and `npm:@earendil-works/pi-coding-agent`; a key you write replaces it, so `trusted_packages: []` gates every package. Before, `@openai/codex` was exempt in code and nothing else could be.
- Changed: the audit no longer blocks Markdown text that only describes a risk. A CRITICAL pattern counts one level lower, and so does not block, when it sits in double quotation marks or follows never, do not, don't, avoid, instead of, for example, such as, flag, detect or warn in the same clause. `doctor audit` still lists it as HIGH. A script that pipes a download into a shell blocks as before ([skills.md](skills.md)).
- New: `tackroom skill sources add` accepts a repository that is itself one skill, with `SKILL.md` at its root. It is recorded as `skill_dirs: [.]` and named by the `name:` in that file, else by the source name.
- Changed: `skill sources add --all` skips a skill name that two folders both hold, prints one line per skipped name and adds the rest. Before, it refused the whole repository.
- Changed: a source you wrote by hand with `skill_dirs: [.]` on a repository with a root `SKILL.md` is now named by the `name:` in that file. If that differs from the source name, the next sync installs the skill under the new name and removes the old copy.
- Changed: the first line of the README and the landing page now leads with what does not port between agents: MCP servers, hooks and subagents.
- Fixed: the audit treated every triple-quoted Python string as a docstring and counted a match inside it one level lower, so a script could hold `curl ... | sh` in a string, run it with `subprocess`, and still be pinned. Only a real docstring, the first statement of a module, class or function, is lowered now. A pin already in the lock keeps syncing, since the gate checks only a new or changed pin; `tackroom doctor audit` lists such a match as CRITICAL. A new or changed pin that does this is blocked until you accept or remove it.
- New: Gemini CLI is supported again (key `gemini`, detected by `gemini` on `PATH`), with the adapter 2.7 had: skills read from `~/.agents/skills`, stdio and remote MCP servers and hooks in `~/.gemini/settings.json`, roles in `~/.gemini/agents`, and the root file `~/.gemini/GEMINI.md`, shared with Antigravity CLI. A config that still names `gemini`, which 2.8 ignored, syncs to it again with no edit, including a server, hook or source MCP whose `agents:` list names only `gemini`. See [harnesses.md](harnesses.md).
- New: a job under `crons.jobs` takes an optional `output`, the path or glob where its results land. `cron add` and `cron edit` take `--output PATH`, and `--output ""` removes it. `cron collect` JSON carries `output` and `output_expanded` (expanded only for a job on this machine), `--table` lists them under "Outputs", and the web view shows them in the job's details ([crons.md](crons.md)).
- Changed: building from source needs Go 1.26.7 or newer; it needed Go 1.25. Release binaries are still built with Go 1.27.
- Changed: `tackroom view` starts the view in the background when none runs, opens it and returns at once. That view exits after 30 minutes without requests; an open page keeps it up. `--foreground` serves in the terminal as before. A launchd job or systemd unit that runs `tackroom view` keeps working: under a service manager, detected from `XPC_SERVICE_NAME` or `INVOCATION_ID` when stdout is not a terminal, plain `view` serves in the foreground. `--foreground` is the explicit form. A view an older tackroom started from a terminal restarts onto this release as a background view. See [view.md](view.md#starting-stopping-and-the-caller-contract).
- New: `tackroom view --json` prints `url`, `addr`, `pid`, `started` and `idle_timeout` as one JSON object. Scripts and plugins call it instead of reading `view.addr` and `view.token`, which stay. `tackroom view --stop` stops the running view. A running view records its process in `view.pid` and a background one writes `view.log`.
- New: `ui.view.addr`, `ui.view.idle_timeout` and `ui.view.open_browser` in `tackroom.yaml` or `tackroom.local.yaml` ([Settings](view.md#settings)). `config validate` refuses a non-loopback address and an idle timeout that is not `0` or at least `2m`, so the page's request once a minute always keeps an open view up.
- Changed: the web view and the Herdr panel lead with one answer, counted from the sync state, the machines and the crons: "2 failing, 1 needs attention", "All clear", or "Checking…" while one is still loading. Under it come what fails and what needs attention, each with its fix or its actions, and everything else on one line per kind; both group the same rows the same way, so a pending sync is one row and items in cooldown fold into everything else. The web view has a sidebar from 900px wide, and a top bar, a bottom dock and sheets for Sync, a job and its log on a phone; Skills, Roles and MCP & hooks are lists instead of matrices. Copy the mods from `herdr/tackroom/mods/` again to get the panel's. See [view.md](view.md#find-your-way-around).
- Changed: a `ui` block in `tackroom.local.yaml` replaces only the `ui` keys it sets. Before, it replaced the whole shared `ui` block, so a local `ui:` without `links` dropped the shared links.
- Changed: the Herdr panel's Web button, the Tern crons block's Web button and Rex's Open tackroom View on Crons run `tackroom view --json`, so they start the view when none runs. Copy the Herdr mod, the Tern plugin and `rex/tackroom.lua` again. With an older tackroom the Herdr button opens a running view as before, and the Tern and Rex ones say "Web needs a newer tackroom".
- Changed: `--secure-cookie` implies `--foreground`, and a view that restarts itself after an upgrade serves in place with `--foreground`, so a view behind `tailscale serve` keeps running. A background view takes `PATH` from your login shell, so it finds the same harnesses as a terminal; the caller's own variables win. Under `nohup`, a foreground view no longer exits on SIGHUP.
- Fixed: a view that restarts itself after an upgrade adds `--no-open` to its arguments only when it is not there yet. Before, each restart added another one.
- Known limit: for an outside skill source the cooldown counts from the commit's committer date, which whoever makes the commit sets, so a backdated commit is not held. npm and PyPI versions go by the registry's publish time. [skills.md](skills.md#the-audit-gate) lists what else the cooldown does not cover.
- Known limit: the audit is a pattern check per line, not a parser or a sandbox, so a skill written to evade it can hide a command from it. One case: Python 3.12 and later let an f-string hold a nested string that uses the f-string's own delimiter, such as `f"""{'''"""'''}"""`; the audit then loses track of where the f-string ends, so a line inside it that starts with `#` counts as a comment ([skills.md](skills.md#the-audit-gate)).
- Going back: `npm install -g tackroom@2.8.0` installs the previous release; the Homebrew tap carries only the latest one. 2.8.0 loads a `tackroom.yaml` and `tackroom.lock` written by 3.0, but it reads cooldown entries only under their old names, `holds:` and `hold_until`, and the memory scripts 3.0 removed do not come back.

## To 2.8

- New: Devin (key `devin`, detected by `devin` on `PATH`), which covers Devin CLI and the Devin Local agent in Devin Desktop. It gets skills (read from `~/.agents/skills`, mirrored into `~/.config/devin/skills` only when the config root is elsewhere), stdio and remote MCP servers in `~/.config/devin/mcp_config.json`, and a root file at `~/.config/devin/AGENTS.md`. tackroom writes it no roles and no hooks. Devin loads the role files in `~/.agents/agents/` itself when that is the config root, with their tool names as written, and it loads Claude Code's hooks by default, so a copy from tackroom would run twice. Devin also reads `~/.claude/CLAUDE.md` by default. With an `instructions:` list in `tackroom.yaml`, a machine with both loads it as a second rule unless you set `read_config_from.claude` to `false` in `~/.config/devin/config.json`; without one, Devin loads the root file once. Checked against Devin CLI 3000.12.57 without signing in. See [Devin](harnesses.md#devin).

## To 2.7.1

Nothing to migrate by hand: `tackroom.yaml` and `tackroom.lock` keep their formats.

- Fixed: `tackroom setup` on a config root that already has `tackroom.yaml` (a rerun, or a clone on another machine) no longer brings back starter files you deleted, such as a starter role, the `tackroom` skill or `plugin.json`. Starter files now go only into a config root with no `tackroom.yaml`. A memory tier that is on, including one `setup --memory basic` turns on, still gets its missing files under `memory/`. A config root holding only a `tackroom.yaml` you wrote by hand no longer gets the starter roles and skill from `setup`.
- Fixed: `setup` no longer rewrites `tackroom.yaml` when its content does not change. Before, every run reformatted it (blank lines dropped), which left a change in a cloned config repository and could stop `git pull --ff-only` there.
- Fixed: `sync`, and the sync `setup` runs, no longer add a `holds:` entry to `tackroom.lock` for an npm or PyPI version that was already older than 72 hours when first looked up. On a new machine every pinned Pi package or MCP server version was new, so its first sync changed the lock. Entries already in the lock are handled as before; one an earlier release wrote with a `hold_until` in the past and no `allowed` can be deleted and committed once every machine runs this release.
- Changed: Pi packages are looked up only on a machine where Pi is detected. A machine without Pi makes no registry lookup for them and records no hold; a decision already in the lock still applies there.
- Changed: release binaries are built with Go 1.27. They were built with Go 1.25, which no longer gets security fixes: `govulncheck` reports 14 standard-library vulnerabilities in the 2.7.0 binary and none in a 1.27.4 build. Building from source still needs Go 1.25 or newer.

- Fixed: `skill sources add --latest` holds a head younger than 72 hours instead of pinning and syncing it. The lock records the hold and no pin, and nothing reaches an agent until the hold ends or you release it. `add` now takes `--allow-fresh` and `--reason`, as `skill update` does.
- Fixed: `skill sources add` runs the audit gate. A source with an unaccepted CRITICAL finding is neither pinned nor linked until you accept it with `tackroom doctor audit accept`.
- Fixed: `skill update` of one source no longer pins other sources that are held or blocked.
- Fixed: a release recorded for a held commit applies to that commit. A branch head that moved afterwards gets its own hold.
- Fixed: `status`, `sync`, `sync --dry-run` and the view list a hold or block created by `skill update`, with an override that works: `tackroom skill update <name> --allow-fresh=<item>`.
- Changed: `tackroom doctor audit` labels its first count as heuristic findings.

## To 2.7

Nothing to migrate by hand: `tackroom.yaml` and `tackroom.lock` keep their formats.

- New: `tackroom setup --overlay NAME` copies `overlays/NAME.yaml`, a complete `tackroom.local.yaml` committed in the config repository, into place before the first sync, for machines of one kind such as cloud VMs: `tackroom setup --from <repository url> --overlay cloud --no-cron`. A different `tackroom.local.yaml` is never overwritten; setup lists it as needing your attention and exits 1. An unknown name stops setup before it syncs anything. See [Machine overlays](setup.md#machine-overlays).
- New: `tackroom hosts fix [HOST...]` runs the fix `tackroom hosts` names (`tackroom setup`, `pull` or `sync` on that machine, over SSH) and prints the machine's new row; `--dry-run` only prints it. A fix that commits and pushes is still printed for you to run. `tackroom hosts setup user@host` sets up another machine from this one with `tackroom setup --from`, and `--install` installs tackroom there first. `hosts --json` adds `fix_runnable` to each host.
- Changed: for a machine that has tackroom but no config, `tackroom hosts` now names `tackroom hosts setup HOST` as the fix, not a bare `tackroom setup` there, which would start an unrelated config.
- New: the Claude Code pane syncs and edits, as the Herdr panel does. When something waits, Sync shows the plan, with what it removes or overwrites, before it applies it, and applies only that plan. Harnesses, MCP servers and hooks have Turn on and Turn off, MCP servers and hooks add or remove a harness, and with more than one machine in `crons.hosts` a Machines section shows each one's health. It needs tackroom 2.6 or newer as the plugin's `tackroom` program; with an older one the pane stays as before and says to update tackroom. Update the Claude Code plugin to get it.

## To 2.6

Nothing to migrate by hand: `tackroom.yaml` and `tackroom.lock` keep their formats. One thing changes on its own: a hook you turned off in the config is now removed from the agents on the next sync (below).

- New: the Herdr panel syncs and edits. Overview has a Sync button that shows the plan, with what it removes or overwrites, before it applies it. Harnesses, MCP servers and hooks have Turn on and Turn off, and MCP servers and hooks add or remove an agent, as the web view's switches and cells do. Copy the two mods from `herdr/tackroom/mods/` again to get it. With an older tackroom the panel stays read-only.
- Fixed: the Herdr panel could stay on "Loading…" (the crons panel on "Collecting…") for good when Herdr created it hidden, as it does at start: its first loads never returned. They now start a moment later.
- New: `tackroom config set <section/name/field> <value>` changes one field, as the web view's switches do, for example `tackroom config set mcp_servers/exa/enabled false`. An entry defined in `tackroom.local.yaml` is changed there. The path must name a field that section's entries have; a misspelled field, a shorter path or `null` is refused.
- New: `sync --dry-run --json` adds `plan`, `destructive` and `plan_digest`, and `tackroom sync --plan-digest DIGEST` syncs only while the plan is still the one with that digest and `tackroom.yaml` and `tackroom.local.yaml` are unchanged. `destructive` lists every removal (skills, roles, MCP servers, hooks, plugins, Pi packages, starter files) and every role overwrite.
- Fixed: turning a hook off, or removing an agent from it, now removes it from that agent on the next sync. Before, `sync` reported "up to date" and the command stayed registered until `tackroom hook remove`. The native file is backed up first, so `tackroom restore latest` puts it back. `status` lists such a hook as `hooks stale`, and `--json` as `agents[].hooks.stale`. This applies to hooks `tackroom.yaml` still declares; a registration of a hook you deleted from the config is left alone, as before.
- Changed: the web view's Sync now also asks you to tick hook and Pi package removals.

## To 2.5.1

Nothing to migrate by hand: `tackroom.yaml` and `tackroom.lock` keep their formats.

- Fixed: a role with `tools: []` was written with no `tools` key, so Claude Code, GitHub Copilot CLI, Gemini CLI, Kimi Code, OMP and Pi gave it every tool. They now get no tools, and the next sync, including the periodic `tackroom pull`, rewrites those copies. `tools: ""` now also means no tools. Codex, Cursor, Factory Droid, OpenCode, Qwen Code and Grok Build cannot express it and keep the harness default; see [Tools](roles.md#tools).
- The Herdr panel moved to `herdr/tackroom/`, a package Herdr's mod gallery can list, with a recipe that adds the button and the panel to the layout you use. The `tackroom` layout in `herdr/layouts/` is gone; if you copied it, it keeps working. To update the panel, copy the two mods from `herdr/tackroom/mods/`, or paste the gallery line in [herdr.md](terminals.md#install) to your agent. Where the notes below say to copy `herdr/mods/tackroom`, copy `herdr/tackroom/mods/tackroom` instead.

## To 2.5

`tackroom.yaml` and `tackroom.lock` keep their formats. Scripts that run `tackroom setup --yes` keep working.

- `tackroom setup` no longer asks anything. It does what `setup --yes` did: imports everything your agents have (copies; a differing native file is backed up before it is replaced), installs the periodic job, and ends with a short summary instead of the full sync report. Unlike `--yes`, it initializes git only on a first setup (no `tackroom.yaml` yet), so a config you kept out of git stays that way; it never changes the memory tier of an existing `tackroom.yaml` without `--memory` (`basic` on a new one); and it exits 1 whenever the summary lists something that needs you, possibly after the sync, commit and job are already done. To review imports and confirm each step as before, run `tackroom setup --review`; `--verbose` prints the full report. `--yes` is still accepted and does nothing, so scripts keep working.
- New: `tackroom setup --from <git url>` sets up another machine in one command. It clones your config repository into the config root, or pulls it when it is already a clone of that URL, then sets up from it. A config root with other content is refused and left as it is. See [Multi-machine](setup.md#set-up-another-machine).
- Changed: a native role is shared, and later replaced, only when the role tackroom writes keeps every field and the instructions of the native file. A role with a field tackroom cannot write (such as `permissionMode` or `sandbox_mode`), with different copies in different agents, or that is a link to a file elsewhere stays each agent's own, and setup adds no starter role of that name, so a fresh setup ends synced. Where the config already has a role of that name, the native file is left in place and listed with how to fix it, and only that file: the rest of that agent still syncs (before, one such file kept the whole agent from syncing). `sync --replace-conflicts` replaces the roles that pass this check, which it did not do before. A role imported without frontmatter no longer gets an invented model, effort or a description holding a machine path.
- If 2.4 left role conflicts on a machine (`status` or `sync` listed a role as "exists but is not tackroom-managed", and that agent got nothing), the first sync after upgrading, including the unattended periodic `tackroom pull`, now syncs that agent. It backs up and links that agent's skill folders and `CLAUDE.md`-style instructions files that are identical to the shared copy, and writes the shared roles into it, including roles a 2.4 setup imported from another agent without the fields tackroom cannot write (such as `sandbox_mode` or `permissionMode`) or, for a Codex role with `"""` instructions, with the raw TOML as its instructions. The conflicting role files themselves stay in place. Right after upgrading, before the next periodic run, run `tackroom sync --dry-run` to see what it would change. To keep a role as one agent's own, rename that agent's file so its name differs from the shared role's. To stop sharing a role, delete `~/.agents/agents/<name>.md` and remove the copies tackroom already wrote into the other agents' folders (they start with a `Generated by tackroom` line); sync does not remove them.
- Fixed: importing a Codex role whose `developer_instructions` is a `"""` multi-line string no longer copies the raw TOML into the instructions.
- Fixed: rerunning `setup` no longer removes the memory hooks from each agent's config only for the sync to add them back.
- Changed: `sync` (and so `setup`) backs up a native file or skill folder that is identical to the shared copy before linking it, as it already did for different ones, so `tackroom restore latest` puts back everything a run replaced.
- Fixed: with many agents, the web view's Skills, Roles and MCP & hooks tables showed no names. The name column now keeps its width and the table scrolls sideways inside its card.
- `setup` lists instructions files it merged from several agents into `AGENTS.md` as needing your attention, and `setup --dry-run` now says what the run would do: whose copy it keeps and which roles stay each agent's own.

## To 2.4

Nothing to migrate by hand: `tackroom.yaml` and `tackroom.lock` keep their formats. If your periodic sync job dates from before 2.0, run `tackroom cron` once (below).

- New: `tackroom hosts` shows tackroom on every machine in `crons.hosts`: its version, whether it is set up and synced, and its config commit against this machine's, with the command that fixes what is wrong. With more than one host, the view's Overview and the Herdr panel's Overview show the same as a Machines block. Copy `herdr/mods/tackroom` again to get it in the panel. See [commands.md](commands.md#check-health).
- Fixed: `tackroom setup` stopped with `config hook memory-session-start targets unknown agent "claude"` when `tackroom.local.yaml` listed an agent, for example one turned off on that machine. It also stopped on any machine with Grok Build installed, reading `~/.grok/config.toml` as JSON. Both now set up; a harness config tackroom cannot read is reported as a warning and its MCP servers are left out of the import.
- If you first installed the periodic sync job with a tackroom before 2.0, run `tackroom cron` once. That job sources `~/.profile` first, and when the file is missing (common with zsh) or fails, `/bin/sh` stops before tackroom runs: the job never synced and its log stayed empty. `tackroom status` and `tackroom doctor` now name this case.
- Deprecated: `tackroom tui`. It still runs, with a notice, and will be removed in 3.0. Use `tackroom view` (on a desktop, a phone or in a side panel) or the [Herdr panel](terminals.md#herdr-panel); in a terminal, `tackroom status`, `tackroom cron collect --table` and `tackroom doctor` print the same facts.

## To 2.3

Nothing to migrate by hand: `tackroom.yaml` and `tackroom.lock` keep their formats.

- `tackroom view` works on a phone and in a narrow side panel: larger text and tap targets, matrices that stack into rows, a web app manifest so it can go on a home screen, and a page that asks for the token when a phone opens it without one. See [On a phone](view.md#on-a-phone).
- The view's Overview lists outside sources as pinned, held or blocked, with the reason and the command that overrides it. The view now applies the freshness hold and the audit gate the way `tackroom status` does, so it no longer offers a sync for a skill that sync would skip.
- New: `tackroom config inventory` prints the view's inventory as JSON.
- The Herdr panel is now a `tackroom` panel with Overview, Skills, Roles, MCP & hooks and Crons tabs. Copy `herdr/mods/tackroom` and the `tackroom` layout again to get it; the old `crons.svg` icon is replaced by `tackroom.svg`. See [terminals.md](terminals.md#herdr-panel).

## To 2.2

Nothing to migrate by hand: `tackroom.yaml` and `tackroom.lock` keep their formats. One thing moves on its own, for Codex users with plugin sources (below).

- New: Codex settings. Keys under `settings:` on the `codex` agent are written into `~/.codex/config.toml`; every other key in that file is kept. See [Per-harness settings](setup.md#per-harness-settings).
- New: `tackroom cron add`, `cron edit` and `cron remove` for jobs tackroom owns on this machine, with the same actions in the web view and the Herdr panel. See [crons.md](crons.md#add-edit-and-remove-owned-jobs).
- `tackroom view` uses the Graphite theme and now has a light theme that follows the OS setting.

Codex now installs an agent-plugins-spec source with `mcp: true` as a native plugin, through `codex plugin`. `tackroom.yaml` and `tackroom.lock` keep their formats. See [Codex plugins](plugins.md#codex-plugins).

- If a source with `mcp: true` already synced into Codex, the next `tackroom sync` moves it. It removes that source's skill links from `~/.codex/skills` and the `[mcp_servers]` rows tackroom wrote for it, backs up `~/.codex/config.toml`, and installs `<name>@tackroom` with `codex plugin add`. Codex then also gets the plugin's `streamable-http` servers.
- A source that sets `skills:`, `skill_dir:` or `skill_dirs:`, that sets no `mcp: true`, or that lists Codex in `exclude_agents` or leaves it out of `mcp_agents` keeps its links and rows.
- `codex` must be on `PATH`. A failed `codex plugin` call is reported for the Codex plugin surface only; the other surfaces still apply.
- To keep one source out of Codex, set `enabled = false` under `[plugins."<name>@tackroom"]` in `~/.codex/config.toml`, or add `codex` to its `exclude_agents`.

## To 2.1

Nothing to migrate: `tackroom.yaml` and `tackroom.lock` keep their formats.

- A download piped into a shell (`curl ... | sh`, `wget ... | bash`, `base64 -d ... | sh`) in an external skill is now a CRITICAL audit finding. A new or changed pin with that pattern is skipped until you accept it with `tackroom doctor audit accept`. Pins already in the lock keep syncing, and your own skills are reported, never blocked.
- The Hermes memory bridge is gone. The next `tackroom sync` deletes `memory/hooks/sync.sh`, `sync-memory-to-vault.sh`, `sync-vault-to-memory.sh` and `memory/lib/sync.py` from your config root if you never edited them. Edited copies are reported and left alone. `tackroom setup` removes the old sync hook commands from native configs.
- `tackroom doctor` no longer fails because an external skill is held or blocked. It passes, counts them and says what to do next.
- Install with Homebrew or npm. The install script is no longer offered.
- New: `tackroom tui`, a read-only terminal view. It was removed in 3.0.

## To 2.0

tackroom 2.0 removes the Hermes and OpenClaw harnesses (with their hooks, MCP adapters, setup defaults and doctor checks), the `hermes` and `openbot` cron sources, the `tackroom skill promote` command, the macOS app, the HarnessKit coexistence notes, and the legacy `tackroom view --port/--host/--no-token/--name` flags.

- `tackroom.lock` gains two keys: `accepted:` (audit decisions) and `holds:` (freshness holds). An older tackroom that rewrites the shared lock drops both, so upgrade every machine that shares the config root before syncing.
- `setup` now installs the periodic sync job (`tackroom pull`) by default, every 15 minutes. It was opt-in at 30 minutes. `--no-cron` skips it.
- If you use Hermes or OpenClaw, tackroom leaves their native files in place and stops managing them. Delete them yourself if you no longer need them.

## The `claude` key

In `tackroom.yaml` and `--agents`, Claude Code is `claude`, since 1.2.0. The former name `claude-code` is still accepted. A tackroom older than 1.2.0 does not know `claude`, so upgrade every machine that shares the config.

## From dotagents

tackroom 1.0 is the dotagents CLI under a new name. An existing config root needs its files renamed once; tackroom refuses to run while `dotagents.yaml`, `dotagents.local.yaml` or `.dotagents-starter.json` still exist without their new names.

```bash
dotagents cron --remove                        # only if you installed the cron entry
cd ~/.agents
git mv dotagents.yaml tackroom.yaml
git mv dotagents.lock tackroom.lock
git mv .dotagents-starter.json .tackroom-starter.json
mv dotagents.local.yaml tackroom.local.yaml    # only if you have one
```

Then:

- In `.gitignore`, replace `dotagents.local.yaml` with `tackroom.local.yaml` so machine-local overrides stay out of git.
- Move `skills/dotagents` to `skills/tackroom`. If you never edited it, copy the [`skills/tackroom` folder](https://github.com/yourconscience/tackroom/tree/main/skills/tackroom) from the tackroom repository over it; otherwise replace `dotagents` with `tackroom` inside it.
- Install tackroom, run `tackroom sync`, then `tackroom cron` if you use it, and remove the old `dotagents` binary.

Role files that dotagents rendered into harness folders are adopted and rewritten on the first sync.
