Recover a broken session

Sessions end badly. The machine sleeps mid-closeout, the terminal dies, or you simply walked away three days ago and never wrote anything down. mcue has a specific path for each, and none of them require editing state by hand.

Picking the right path

When unsure, start with review. It reads state without advancing it, so it cannot make the situation worse.

Interrupted closeout

mcue recover payments-api

recover completes an interrupted closeout by writing a degraded checkpoint — one explicitly marked as incomplete rather than pretending to be a full record.

That marking is the important part. A checkpoint that silently claims to be complete when half its fields were never answered is worse than no checkpoint, because you will trust it later.

Closing out when you cannot answer everything

mcue closeout payments-api --degraded

Use this when you genuinely do not know the outcome or the next action — the build is still running, you are being pulled into something else, the answer depends on someone else. It records what you do know and flags the rest as missing.

A degraded checkpoint is honest. Inventing a plausible next action to satisfy the prompt is not.

Capturing a session after the fact

mcue closeout payments-api --retroactive

For the session that ended on Thursday when it is now Monday. Retroactive closeouts are marked as such, so the history distinguishes "recorded at the time" from "reconstructed later" — which matters when you are judging how much to trust the record.

Write what you can actually remember. A retroactive closeout saying "cannot recall the blocker; the failing test was TestRefundRetry" is more useful than a confident reconstruction that is subtly wrong.

Reading the result

A resume packet built from a degraded or retroactive checkpoint says so. When you see that marker, treat the surrounding account as partial and check the repository state before acting on it.

mcue resume payments-api
mcue history payments-api     # browse the checkpoint history

After a recovery

Once you are back in a known state, close out normally at the end of the next real session. That writes a complete checkpoint and leaves the degraded one in history, where it stays as an accurate record that this period was messy.

Do not try to retroactively "fix" a degraded checkpoint into a complete one. The gap is information.

When the problem is distributed, not local

If the trouble is two machines disagreeing rather than one session ending badly, this is the wrong page. See Authority and conflicts and mcue reconcile <project-id>.

When the problem is the install

mcue doctor

Resolves which binary is running, its version, where $MCUE_HOME points, and whether that directory is readable and writable. Run it before assuming your state is corrupt — a surprising share of "my state is broken" turns out to be two installs or an unexpected MCUE_HOME.

Hosted closeouts and uncertain acceptance

The browser retains your draft and a request ID before submitting it. If the response is lost, use Retry this request: the same ID and exact fields resolve the original acceptance. Download recovery copy preserves the submitted fields before you clear browser data or change devices. Draft text remains in this browser for your account until accepted; it is not an accepted checkpoint.

Hosted MCP closeout, lane_create and lane_close require a caller-retained request_id. A retry must reuse both the ID and identical fields. A different payload under that ID is refused. An unknown outcome never calls for a fresh ID. A conflict needs explicit reconciliation; an intentionally edited successor gets a new ID and links to the original closeout with replaces_request_id.

not_saved means storage was not confirmed: keep the recovery fields returned to the caller. A durable pending attempt is separate from accepted history. Neither an error log nor an agent’s promise to remember is a durability guarantee.

For coordinated incident recovery, pause competing writers, inventory overlapping work, and process eligible CLI queues before replaying any hosted record. Replay only the final hosted records not already covered by accepted work; retain unresolved conflicts for human reconciliation rather than forcing a winner.

Large-project recovery limits

These are the limits of the installed CLI today. They are transfer ceilings, not history ceilings: never delete accepted history to fit a transfer.

• First publish: mcue publish accepts at most 500 files and 5 MiB. A local project already above that size cannot first connect to the Hub. The refusal names the limit and uploads nothing.
• Whole-project reads: the CLI reads at most 6 MiB per Hub response. mcue clone and the pre-read refresh download a whole-project snapshot, so a project that has grown past that size on the Hub cannot be cloned or refreshed by the installed CLI. The failure is explicit, applies none of that response, and leaves pending local intent and the sync cursor untouched.
• Backups: the project owner can download a streamed backup of accepted state from the Hub. Treat an interrupted download as incomplete; it cannot be verified or restored.

Bounded, manifest-pinned transfers that remove the whole-project assumption from publish, clone, export and restore are implemented and under review. This page will document the commands when the CLI release that carries them is installable from the tap. Until then, an installed CLI reports the limits above.

Resolving retained hosted requests

The lane recovery panel lets you download submitted intent, retry an unresolved request, or explicitly mark it covered by an accepted checkpoint. Compare accepted history and all known CLI queues first. Discarding a recovery copy prevents replay of that ID and does not delete accepted history. Edited successors use a fresh ID linked to the original request.

Unresolved copies have no automatic expiry and are capped at 100 requests / 32 MiB per actor/project. Identity and acceptance receipts remain until account/project deletion. Explicit copy deletion clears active recovery content; historical backup copies follow the deployment's backup retention. Downloaded files and browser storage are independent copies. Keep them private and clear them separately.

Damaged local metadata

Stop writers and preserve the original project directory, link and queue together. Do not hand-edit files under ~/.mcue to bypass a recovery error, and do not force a queue through a conflict. To inspect accepted state without touching the damaged replica, clone the project into a separate empty MCUE_HOME and compare it against the original before reconciling selected edits. Unreadable local intent cannot be assumed to have reached the Hub; record that uncertainty for operator review instead of forcing a replay.