Command recovery and uncertain outcomes

Assign one command ID to a logical mutation and freeze its body. Reusing the ID for different content is rejected.

A response was lost

The Client's supported project/file/runtime helpers do not repeat a mutation POST automatically. They attempt bounded lookup of its original ID. An unknown result exposes ApiCommandOutcomeUnknownException.CommandId; caller cancellation can expose ApiCommandCanceledException without proving Core cancelled the command.

Reconnect with the same approved credential/principal and inspect GetCommandResultAsync(originalCommandId, token). Continue polling an existing operation rather than starting another one. Update methods have their own explicit lookup workflow.

Persist a journal of command IDs and frozen payloads before transmission when your application needs recovery across its own restarts. Store the approved credential separately using protected storage. A new command ID represents new work, not a retry marker.

For HTTP clients, use GET /api/v1/commands/{commandId} for the supported project/file/runtime/settings families, GET /api/v1/runtime/commands/{commandId} for runtime starts, or GET /api/v1/updates/commands/{commandId} for update commands. Lookup is authorized for that operation's family and principal. A runtime.control grant alone does not authorize runtime lookup; include runtime.read.

If a command lookup identifies a file operation or run, continue tracking that existing ID. An unknown or evicted result is not evidence that nothing happened. Refresh state and let the user decide how to proceed when external effects cannot be established.

Retention limits

Command results are bounded and tied to the running Host. Expiry, eviction or Host restart can make lookup unknown. Reconcile actual state before deciding whether to issue a new action.

There is no general exactly-once guarantee for external effects. A timeout can occur after an external action was accepted.

Run history and a durable installation result are separate from command caches. Retaining a run does not restore an old session or grant permission to replay a mutation.