Reconcile sandbox commands before repeating them

A lost response leaves an outcome question

When an HTTP request times out, the command may not have started, may still be running or may already have finished. Treat that as an unknown outcome until evidence resolves it. Repeating the command under a new identity can duplicate file writes, external requests or other effects. Lupin's durable command path requires an Idempotency-Key and reserves the command attempt before invoking the provider. Store that key with the resource identifier, command and expected artifact. It is part of the task's execution record, not a disposable transport header generated anew on every retry.

Understand the reconciliation guard

A repeated accepted or uncertain command returns reconciliation_required rather than automatically executing again. This protects the boundary from blindly replaying an unknown effect. It is not a guarantee that the server can return the original result or reconstruct every stdout byte. A command-level reservation also does not deduplicate requests the program makes internally to other services. If your script performs a consequential external mutation, use that service's own idempotency protocol and the user's exact authorization. The two layers answer different questions: whether the sandbox command was accepted and whether its internal side effect was applied once.

Inspect history and current state

Use the runs endpoint to inspect command metadata and status, then observe the relevant artifact or process state where authorized. Lupin's normalized history response does not promise the original full stdout and stderr, so avoid claiming to have reviewed them if the initial result was lost. A matching command in history is useful evidence but may need correlation with time and task-specific output. For a pure transform, compare the input digest and expected output manifest. For a server process, inspect its health and intended port instead of launching another copy immediately.

curl -X POST "https://api.lupin.sh/v0/containers/$CONTAINER_ID/runs" \
  -H "Authorization: Bearer $LUPIN_API_KEY" \
  -H "Idempotency-Key: inspect-workspace-001" \
  -H "Content-Type: application/json" \
  -d '{"command":"pwd","timeout_seconds":30}'

Design commands that expose completion

Write outputs to a temporary path, validate them and promote them to a final path only at a known completion point when the workload permits it. Include a task-specific manifest that identifies the input and completed stage. These techniques make local computation easier to reconcile, but they do not make arbitrary external effects reversible. Avoid scripts whose only completion signal is a friendly log line followed by additional work. Keep a bounded diagnostic summary and explicit process exit status. Use stable task identities inside the program where useful without leaking control-plane API keys into the guest.

Choose a new attempt consciously

After reconciliation, decide whether the original work succeeded, failed before its effect or remains uncertain. A new attempt should record why it is safe and what changed, and it should receive its own operation identity. If the effect cannot be determined, stop dependent work and involve the authorized operator rather than bypassing the guard with a new key. Save verified partial artifacts and clean up idle runtime independently. A reliable retry system does not promise that every uncertain operation can be replayed; it preserves enough evidence to make the next action deliberate and reviewable.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

• docs.boat.dev · long-running-tasks · command-history ↗Checked 2026-11-05
• docs.python.org · 3 · library · subprocess.html ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.