ADR 0243: Remove unusable and unused commands
Date: 2026-11-10 Status: Accepted
Context
Section titled “Context”A 60-day review of usage records from the hosts that run Harnery counted how often each command path ran. Four top-level commands stood out:
| Command | Paths | Runs in 60 days | Why |
|---|---|---|---|
harn conversations |
6 | 0 | Needs conversation providers that the host passes in context.conversations. No known host passes them, so every call fails. |
harn inbox (including inbox watch) |
4 | 1 | Needs an inbox service in context.coordinationInbox. No known host passes one, so every call fails with “coordination inbox is not configured by this host”. |
harn messages |
1 | 1 | Needs the same inbox service and fails the same way. |
harn sync |
6 | 0 | Copies identities and archived journals with rclone. It works, but no host configured a remote and nobody ran it. |
The working routes for the same jobs ran constantly in the same window:
harn agents inbox list ran 1,060 times, and session prompt hooks read the
same inbox in-process. harn agents ping is how agents send each other
messages. ADR 0238 kept inbox and messages as messaging commands; this
review showed that only the agents forms of them ever worked.
The usage records cover only some hosts and harnesses, so a count of zero means “not seen run”, not “unused everywhere”. For the first three commands that gap does not matter: they cannot run without a host service that no host supplies.
Alternatives considered
Section titled “Alternatives considered”- Keep the commands and wire the services in each host. Rejected: the
agents inboxandagents pingcommands already do the inbox and messaging jobs with a built-in service, and no one asked for host-supplied conversation history in the command line. - Hide the commands instead of removing them. Rejected: a hidden command that always fails is still code, tests and docs to maintain, and Harnery is pre-1.0, so it cuts over directly instead of carrying aliases.
- Keep
syncas an optional feature. Rejected: it had no configured remote and no users, andharn backupalready covers durable copies of.harnery/through restic, which can itself use an rclone remote.
Decision
Section titled “Decision”Remove the four commands. This is a breaking change to the command surface, made on purpose.
What is removed
Section titled “What is removed”- Commands. The
inbox,messages,conversationsandsyncregistrations insrc/commander.ts, withsrc/commands/messages.ts,src/commands/conversations.ts,src/commands/sync.tsand their test files. - Host context fields.
coordinationInboxandconversationsleave the program context. They existed only to hand services to the removed commands. A host that still sets them gets a type error, which is the intended signal. - The
syncconfiguration section. Thesyncblock in.harnery/config.jsoncand the config schema, its reader, theHARNERY_SYNC_REMOTEandHARNERY_SYNC_PREFIXvariables, and the~/.config/harnery/sync.jsonfallback file. A project that still has asyncblock gets a schema warning in its editor; Harnery ignores the block. - The
rclonedoctor check. It reported whetherharn synccould run. Nothing in Harnery runs rclone any more. A restic repository on an rclone remote still needs rclone, and restic reports that itself. - Docs. The
cli/syncpage and thesyncsections of the configuration reference, the first-run guide, the landing page and the README.
What stays, and why
Section titled “What stays, and why”harn agents inbox(list,statusandwatch). It is built by the sameregisterInboxCommandfunction insrc/commands/inbox.ts, with the built-in peer inbox service, so that file stays whole.harn agents ping, the way agents message each other.- The
./core/inboxexport. It backsagents inbox,agents pingand the prompt hooks. - The
./core/conversationsexport and its storage families. No removed command was its only user: the package root re-exports it, the storage framework tests use it, and it is public API that a host can still build on. Whether it goes is a separate decision.
No removed command owned a folder under .harnery/, so nothing joins the
harn storage retire list from ADR 0239.
Consequences
Section titled “Consequences”harn inbox,harn messages,harn conversationsandharn syncnow fail as unknown commands. Useharn agents inboxfor the inbox andharn agents pingto send a message. There is no replacement forconversationsorsync.- A host that passed
coordinationInboxorconversationstocreateHarneryProgrammust drop those fields. harn doctorno longer lists anrclonecheck.