Check a Works with doctor

When you create or join a Works in the desktop, the setup steps it shows come from the same check described here. Running it from a terminal is useful when a dispatch or a land is refused and you want the whole list at once.

Run it

hm --works <path-to-your-works> works doctor

Doctor reads the Works and its repositories and prints one line per finding, then a summary. It changes nothing unless you ask it to.

Each finding has a severity, a code and a message:

[ERROR] <code>: <message>
[WARN] <code>: <message>
[INFO] <code>: <message>

• ERROR means the Works cannot do something it should, such as dispatch onto a Line. Any error makes doctor exit with a failure.
• WARN means something needs your attention but blocks nothing yet.
• INFO is a note about how the Works is set up. It never fails the check.

When there are no errors, doctor ends with works ok and exits successfully. That makes it usable as a gate in a script.

What it checks

In order, doctor looks at:

1. The Works itself. The settings file, the charter, the roster of seats and the executor settings all have to be present. A Works missing any of them stops here, because the later checks depend on them.
2. Each Line's workspace. Every Line in the roster needs a repository wired to it. A Line with none is line.unwired, and the message names the hm works wire command that fixes it.
3. Freshness. A workspace that has fallen behind what has already landed is reported, so new work is not cut from an old copy.
4. Work in progress. Manifest worktrees that are dirty, on the wrong branch, or left behind after a land.
5. Landing. Whether the landing branch can be reached the way the Works is set to land, and whether any manifest the ledger calls landed never actually reached the landing branch (gatehouse.ledger_landed_unintegrated).
6. Executors. Whether the agent runtime each seat uses can authenticate.

Doctor reports what it finds rather than stopping at the first problem, so one run gives you the full list.

Read it as JSON

hm works doctor --json

This prints the same report as a single document with an ok field and a findings list, each finding carrying severity, code and message. The exit code is the same as without --json, so a script can check either.

Repairs

hm works doctor --fix

--fix applies the repairs that are safe to make without asking, which today means removing exact duplicate workspace entries, and then reports as usual.

Two related commands clear the most common findings:

• hm works settle restores files hm generates itself and brings clean workspaces up to date. It leaves your own edits alone unless you pass --stash or --discard.
• hm works wire connects a repository to a Line, which clears line.unwired.

Run --help on either before using it. For what a Line and a workspace are, see seats, hands and lines.