Mercury CLI

Notes

Keeping Mercury's agents in the right checkout

· by @dubsthedev

A session could enter a worktree and then run its first shell command in the checkout it had just left. The git watcher could stay behind too, so later session records named the wrong branch.

Both are fixed in 1.0.0-beta.18. This release came out of using Mercury across every provider it supports to build Mercury, including the parts that launch work and bring it back after an interruption. A command that passes in the wrong checkout tells you nothing about the change you meant to test.

The checkout follows the agent

The Agent tool now takes cwd, the folder a sub-agent works in. A sub-agent isolated in a git worktree can build there, and a session's own worktree comes ready to build. The first shell command after a worktree switch runs in the new checkout.

The worktree and continuation fixes also keep the folder, the effort setting and the project definition when a sub-agent resumes. If the recorded folder is gone, the continuation notice names it and says where the sub-agent now runs. The sub-agent's own prompt gets the same note, on automatic recovery too.

I wanted this for the review loop. A continued agent has to know whether it's still in its isolated checkout or has been moved, or the next edit lands somewhere other than the code it just reviewed.

The tagged integration test launches a sub-agent in a named folder, asks its shell where it is, continues it by message and asks again. A second proof checks that an isolated worktree has the dependency links it needs to run its build fixture. Both check where commands actually run.

A busy provider pauses the work

Provider overload could end a sub-agent with a bare failure, even when the parent was waiting for it inline. Once the retry budget was spent, the task was gone instead of waiting for recovery.

Now Mercury retries quietly on growing waits first. A sub-agent that stays refused pauses. The notes say it probes once an hour with a single request and comes back on its own when the provider does, whatever the provider, and whether it was in the background or the parent was waiting inline. The parent gets one pause notice, and an inline task's completion arrives later as a notification.

There was a lifecycle fault under that too: a paused sub-agent could be swept out of the list before its probe brought it back. It stays on the list now.

A provider's stated usage reset is handled on its own. Scheduled wakes and watches wait for it. A watch holds what lands while the usage window is closed and delivers it together on the first turn after the window reopens, and a self-paced wake never resumes a session you parked on purpose.

A lost reply does not launch twice

The release notes also record a session being created twice after a lost reply. The daemon could have admitted the launch already while the caller was still waiting to hear back.

Retrying in that spot risks a second session for work that already started. Beta.18 gives each launch its own key, including launches through the crew and the manager, and a crew spawn retries only a frame that was never sent. A missing acknowledgement doesn't mean no agent started, and the recovery now assumes one did.

Damaged state is named

Recovery also depends on what Mercury can read back from disk. Beta.18 fixes a saved attachment or notice that had lost its shape crashing compaction, and damaged task and recovery records throwing or being counted as good data.

The storage changes check a record's shape before using it. A bad row is named once and skipped, never repaired in place. A store file Mercury refuses to read shows on the doctor's Store quarantines row. A configuration field of the wrong shape is dropped and named, and the rest of the file is read, so one bad entry no longer resets the whole file.

That's the part I care about. The loss is visible instead of a half recovery pretending to be a full one.

What was checked

The last hosted release entry in the tagged gate ledger is all green, run 35849682619. The release page puts the count at 135 suites, and records the earlier local pool at 129 of 135 with the six reds in the checks themselves, corrected before the tag. Those are two stages of the same release.

The release record carries the four platform archives and their checksums. An existing install updates with:

mercury update