diff --git a/docs/hosted-source-review-2026-10-03.md b/docs/hosted-source-review-2026-10-03.md
index 63f16a34..bd301598 100644
--- a/docs/hosted-source-review-2026-10-03.md
+++ b/docs/hosted-source-review-2026-10-03.md
@@ -122,8 +122,35 @@ temporary upload scratch and that reservation's local journal. A failed reply
uses the existing exact-reservation reconciliation instead of blindly issuing
another action. Published snapshots, live Codex files and unknown scratch stay
intact. These commands do not change the schedule or grant deletion approval.
-The customer-facing confirmation controls and actual-R2 cleanup/recovery proof
-remain separate work.
+The acceptance-gated dashboard now exposes these controls. Actual-R2
+cleanup/recovery proof remains separate work.
+
+### Acceptance-gated unfinished-upload controls
+
+From the hosted setup's saved-key or verified-backup screen, open **If a hosted
+backup is stuck**, then **Check upload status**. The app inspects the exact
+local pending reservation with its confirmed individual key. Reviewing status
+does not authorize release, intentional deletion, or another upload.
+
+For an unpublished upload, a separate unchecked confirmation enables **Release
+this unfinished upload**. The server checks the same opaque reservation again;
+an old selection cannot release its replacement. The checkbox resets when an
+action starts or the reservation changes. A published upload has no release
+control: return to backup for verification, or contact Joshua if a reviewed
+deletion upload requires operator help. Do not remove local retry state by hand.
+
+While cleanup is pending, the app preserves the journal, displays that another
+backup cannot start, and requires a fresh confirmation to finish cleanup. A
+lost reply stays uncertain until another status check. A release request clears
+the pending review only after confirmed release. Previously verified receipts, published
+backups, live Codex files, schedules, subscriptions and deletion approvals are
+not changed by these controls. Returning to backup closes the review only;
+it does not abandon an upload. Background enablement is refused while a known
+unfinished upload remains. Restart does not replay a release or retain consent.
+
+`tests/manual_hosted_setup_fixture.py` serves the real dashboard on loopback
+with clearly labelled simulated states and no file, Keychain, billing or
+provider access. It is for rendered interaction review, not hosted acceptance.
The baseline is never erased or treated as a first backup. No remote snapshot
or referenced chunk is deleted; old publication records remain selectable under
@@ -133,10 +160,11 @@ real-service/independent-Mac recovery proof remains required before release.
## Remaining release work
-The confirmation path is operator-only, not yet buyer UI. Tests exercise real
+Intentional-deletion confirmation is still operator-only, not yet buyer UI.
+Unfinished-upload controls exist only behind the hosted acceptance gate. Tests exercise real
source inventory/staging and retry logic with synthetic service/crypto boundaries;
they are not production, real-R2 or clean-Mac certification. Integrate a clear
-buyer review/confirmation and pending-cleanup flow, complete those independent
+buyer intentional-deletion review/confirmation, prove cleanup against actual R2, complete those independent
recovery checks, and certify the original full release objective.
Owner: the primary Codex Backup implementation task. The clean sibling task
diff --git a/src/codex_migrate/vault_dashboard.py b/src/codex_migrate/vault_dashboard.py
index f58acfa2..5598abde 100644
--- a/src/codex_migrate/vault_dashboard.py
+++ b/src/codex_migrate/vault_dashboard.py
@@ -25,6 +25,7 @@
.hosted-step label{display:block;margin:14px 0 8px;font-weight:700}.hosted-step input,.hosted-step select{max-width:100%;width:100%;margin-bottom:14px}.hosted-step button{margin:8px 0}.hosted-step .actions input{width:auto}.view-backup #hosted-recovery-panel,.view-conversations #hosted-recovery-panel{display:none!important}#hosted-recovery-error{color:#ffc3c8}#hosted-recovery-status{color:var(--muted)}
.view-conversations #hosted-setup-panel,.view-recovery #hosted-setup-panel{display:none!important}#hosted-setup-error{color:#ffc3c8}#hosted-setup-status{color:var(--muted)}
.brand small,.protection{font-size:14px}
+#setup-upload-confirmation{display:flex;align-items:flex-start;gap:12px;font-weight:500}#setup-upload-confirmation input{flex:0 0 auto;width:20px;height:20px;min-width:20px;margin:3px 0 0}#setup-upload-reference{overflow-wrap:anywhere;font-size:14px}
@media print{#hosted-setup-panel,#hosted-recovery-panel{display:none!important}}
@@ -139,6 +140,22 @@
+
+If a hosted backup is stuck
+
Check the unfinished upload before retrying or releasing it. This does not delete published backups, change Codex files, stop the schedule, or cancel hosted storage.
+
+
+
+
Unfinished upload
+
+
+
Releasing this upload keeps your previously published backups and live Codex work. It does not create a new backup or cancel your subscription.
+
+
+
+
+
If this upload already published, return to backup to resume its verification. If a deletion-reviewed upload cannot resume there, email Joshua. Do not delete local backup state yourself.
+
Background backups
Check for changes every 30 minutes while this Mac is awake and online. Backups run without a browser window. Only changed content is uploaded; previous verified versions are kept.
@@ -421,7 +438,7 @@
const fmt=n=>{const units=["B","KB","MB","GB","TB"];let i=0;while(n>=1000&&i=100?0:n>=10?1:2)} ${units[i]}`};
async function api(path,data){const response=await fetch(path,{method:data===undefined?"GET":"POST",headers:{"X-Codex-Migrate-Token":token,"Content-Type":"application/json"},...(data===undefined?{}:{body:JSON.stringify(data)})});const type=response.headers.get("Content-Type")||"";const body=type.includes("application/json")?await response.json():await response.text();if(!response.ok)throw Error(body.error||"The local request failed");return body}
function fail(error){$("error").textContent=error.message;$("status").textContent=""}
-let hostedSetupTimer=null,hostedSetupInterval=0,hostedSetupPhase=null,hostedSetupEpoch=0;
+let hostedSetupTimer=null,hostedSetupInterval=0,hostedSetupPhase=null,hostedSetupEpoch=0,hostedUploadReservation=null;
function hostedSetupView(data){
const panel=$("hosted-setup-panel"),focusOwned=panel.contains(document.activeElement),phaseChanged=data.phase!==hostedSetupPhase;
$("setup-recovery").value=data.enabled&&data.phase==="key_save"&&data.status!=="running"?data.recovery_key||"":"";
@@ -431,15 +448,27 @@
const running=data.status==="running";
for(const block of panel.querySelectorAll("[data-setup-phase]"))block.hidden=running||block.dataset.setupPhase!==data.phase;
for(const control of panel.querySelectorAll("button,input,textarea"))control.disabled=running;
+ const pending=data.pending_upload;
+ if(running||phaseChanged||hostedUploadReservation!==pending?.reservation_id)$("setup-abandon-confirm").checked=false;
+ hostedUploadReservation=pending?.reservation_id||null;
+ $("setup-upload-tools").hidden=running||!["key_ready","backup_ready"].includes(data.phase);
+ const canRelease=pending?.can_abandon===true&&data.phase==="pending_upload";
+ $("setup-upload-confirmation").hidden=!canRelease;
+ $("setup-abandon-upload").hidden=!canRelease;
+ $("setup-abandon-upload").disabled=running||!canRelease||!$("setup-abandon-confirm").checked;
+ $("setup-abandon-upload").textContent=pending?.remote_status==="active"?"Release this unfinished upload":"Finish upload cleanup";
+ const uploadMessages={active:"This upload has not published. You can return to backup to retry it, or confirm release below.",cleanup_pending:"The service is cleaning up this unfinished upload. Keep its local retry state. Check again later; another backup cannot start until release is confirmed.",released:"The service released this upload. Confirm Finish upload cleanup to retire only its verified temporary files and retry journal.",published:"This upload has published. It cannot be released here. Return to backup and resume verification before relying on it."};
+ $("setup-upload-detail").textContent=pending?uploadMessages[pending.remote_status]||"Upload status needs support review.":"";
+ $("setup-upload-reference").textContent=pending?"Upload reference: "+pending.reservation_id:"";
const background=data.background||{enabled:false};
$("setup-background").hidden=!data.last_backup;
- $("setup-enable-schedule").disabled=running||background.enabled||data.phase!=="backup_ready"||data.last_backup?.source_coverage!=="complete"||data.last_backup?.at_risk_threads!==0;
+ $("setup-enable-schedule").disabled=running||Boolean(pending)||background.enabled||data.phase!=="backup_ready"||data.last_backup?.source_coverage!=="complete"||data.last_backup?.at_risk_threads!==0;
$("setup-disable-schedule").disabled=running||!(background.enabled||background.can_stop);
const backgroundMessages={awaiting_check:"Enabled; the first scheduled check has not finished yet.",running:"A scheduled backup check is running.",failed:"The last scheduled check failed. New work may not be backed up; previous verified versions are kept.",needs_attention:"The last scheduled capture needs attention. Do not assume all new work is protected.",verified:"The last scheduled backup completed.",unchanged:"The last scheduled check found no changes."};
$("setup-background-status").textContent=background.enabled?`${backgroundMessages[background.status]||"Background status needs attention."}${background.last_checked_at?" Last check: "+new Date(background.last_checked_at).toLocaleString()+".":""}${background.error?" "+background.error:""}`:background.error||"Background backups are off. You can still back up manually.";
- const messages={start:"Verify your purchase email to connect this Mac.",email:"Check your purchase email for the setup code.",pairing_checkpoint:"The connection still needs to be saved.",pairing_uncertain:"The saved connection needs confirmation.",paired:"This Mac is connected. Automatic protection is not active.",key_save:"Save your recovery key outside this Mac, then confirm your saved copy.",key_ready:"Saved recovery key confirmed. Automatic protection is not active.",backup_ready:data.last_backup?.status==="needs_attention"?"Backup coverage needs attention. Automatic protection is not active.":"Hosted backup verified. Automatic protection is not active."};
+ const messages={start:"Verify your purchase email to connect this Mac.",email:"Check your purchase email for the setup code.",pairing_checkpoint:"The connection still needs to be saved.",pairing_uncertain:"The saved connection needs confirmation.",paired:"This Mac is connected. Automatic protection is not active.",key_save:"Save your recovery key outside this Mac, then confirm your saved copy.",key_ready:"Saved recovery key confirmed. Automatic protection is not active.",pending_upload:"An unfinished upload needs attention. New work may not be backed up.",backup_ready:data.last_backup?.status==="needs_attention"?"Backup coverage needs attention. Automatic protection is not active.":"Hosted backup verified. Automatic protection is not active."};
$("setup-backup-receipt").textContent=data.last_backup?`${data.last_backup.status==="needs_attention"?"The encrypted capture has incomplete or at-risk content. Keep previous good versions and contact Joshua if you need help.":data.last_backup.status==="unchanged"?"No changes were found; the existing hosted snapshot was verified again.":"The hosted snapshot and its encrypted conversation manifest were verified."} Last completed check: ${new Date(data.last_backup_checked_at).toLocaleString()}.`:"";
- const working={send_code:"Requesting your setup email…",pair:"Saving and connecting this Mac…",retry_save:"Retrying the saved connection…",resolve:"Checking the saved connection…",reauthorize:"Preparing email verification…",prepare_key:"Preparing the same protected recovery key…",confirm_key:"Checking your saved recovery key…",first_backup:"Encrypting, uploading and verifying your Codex backup… Keep this Mac awake.",enable_schedule:"Enabling background backups…",disable_schedule:"Stopping background backups…"};
+ const working={send_code:"Requesting your setup email…",pair:"Saving and connecting this Mac…",retry_save:"Retrying the saved connection…",resolve:"Checking the saved connection…",reauthorize:"Preparing email verification…",prepare_key:"Preparing the same protected recovery key…",confirm_key:"Checking your saved recovery key…",first_backup:"Encrypting, uploading and verifying your Codex backup… Keep this Mac awake.",enable_schedule:"Enabling background backups…",disable_schedule:"Stopping background backups…",check_upload:"Checking this unfinished upload with the service…",abandon_upload:"Requesting release of this exact upload… Its retry state stays until release is confirmed.",leave_upload_review:"Returning to backup…"};
$("hosted-setup-status").textContent=running?working[data.step]||"Checking setup…":messages[data.phase]||"Setup needs attention.";
$("hosted-setup-error").textContent=data.error||"";
if(focusOwned&&(phaseChanged||document.activeElement.disabled||(!running&&document.activeElement===$("hosted-setup-status")))){
@@ -498,6 +527,11 @@
$("setup-check-backup-ready").onclick=()=>hostedSetupStep("resolve");
$("setup-enable-schedule").onclick=()=>hostedSetupStep("enable_schedule");
$("setup-disable-schedule").onclick=()=>hostedSetupStep("disable_schedule");
+$("setup-check-upload").onclick=()=>hostedSetupStep("check_upload");
+$("setup-check-upload-again").onclick=()=>hostedSetupStep("check_upload");
+$("setup-leave-upload").onclick=()=>hostedSetupStep("leave_upload_review");
+$("setup-abandon-confirm").onchange=()=>{const button=$("setup-abandon-upload");button.disabled=button.hidden||!hostedUploadReservation||!$("setup-abandon-confirm").checked};
+$("setup-abandon-upload").onclick=()=>{if(!$("setup-abandon-confirm").checked||!hostedUploadReservation)return;const reservation_id=hostedUploadReservation;$("setup-abandon-confirm").checked=false;return hostedSetupStep("abandon_upload",{reservation_id,confirm_abandon:true})};
$("setup-copy-key").onclick=async()=>{try{await navigator.clipboard.writeText($("setup-recovery").value);$("hosted-setup-status").textContent="Key copied. Save it outside this Mac before confirming."}catch(error){$("hosted-setup-error").textContent="Copy failed. Select the recovery key and copy it manually."}};
let hostedRecoveryTimer=null,hostedRecoveryState=null,hostedRecoveryPhase=null,hostedRecoveryEpoch=0,hostedRecoveryPoll=0,hostedRecoveryPending=false;
function hostedRecoveryView(data){
diff --git a/src/codex_migrate/vault_hosted_setup_flow.py b/src/codex_migrate/vault_hosted_setup_flow.py
index 697cb4b5..2c2d69d6 100644
--- a/src/codex_migrate/vault_hosted_setup_flow.py
+++ b/src/codex_migrate/vault_hosted_setup_flow.py
@@ -21,6 +21,7 @@
from codex_migrate.vault_hosted_recovery_flow import purchase_token
from codex_migrate.vault_hosted_key_setup import HostedKeySetup
from codex_migrate.vault_hosted_manual import back_up_hosted_history
+from codex_migrate.vault_hosted_pending import pending_hosted_upload, abandon_hosted_upload
from codex_migrate.vault_hosted_connection import active_binding
from codex_migrate.vault_hosted_schedule import (
SERVICE_ORIGIN, hosted_schedule_status, install_hosted_schedule, remove_hosted_schedule,
@@ -52,6 +53,7 @@ def __init__(self, registry, source_home=None):
self._lock = threading.Lock()
self._proof = {}
self._recovery_key = None
+ self._pending_upload = None
self._keys = HostedKeySetup(registry)
self._binding = registry.read().get("hosted_setup_device")
if self._binding is not None:
@@ -86,6 +88,8 @@ def __init__(self, registry, source_home=None):
def snapshot(self):
with self._lock:
result = copy.deepcopy(self._public)
+ if self._pending_upload is not None:
+ result["pending_upload"] = dict(self._pending_upload)
if self._last_backup is not None:
result["last_backup"] = copy.deepcopy(self._last_backup["receipt"])
result["last_backup_checked_at"] = self._last_backup["checked_at"]
@@ -112,7 +116,9 @@ def stage(self, action, payload):
fields = {"send_code": {"purchase_link"}, "pair": {"code"},
"retry_save": set(), "resolve": set(), "reauthorize": set(),
"prepare_key": set(), "confirm_key": {"recovery_key"},
- "first_backup": set(), "enable_schedule": set(), "disable_schedule": set()}
+ "first_backup": set(), "enable_schedule": set(), "disable_schedule": set(),
+ "check_upload": set(), "leave_upload_review": set(),
+ "abandon_upload": {"reservation_id", "confirm_abandon"}}
phases = {"send_code": {"start", "email"}, "pair": {"email"},
"retry_save": {"pairing_checkpoint"},
"resolve": {"pairing_uncertain", "paired", "key_ready", "backup_ready"},
@@ -121,7 +127,10 @@ def stage(self, action, payload):
"confirm_key": {"key_save"},
"first_backup": {"key_ready", "backup_ready"},
"enable_schedule": {"backup_ready"},
- "disable_schedule": {"backup_ready", "pairing_uncertain"}}
+ "disable_schedule": {"backup_ready", "pairing_uncertain", "pending_upload"},
+ "check_upload": {"key_ready", "backup_ready", "pending_upload"},
+ "leave_upload_review": {"pending_upload"},
+ "abandon_upload": {"pending_upload"}}
with self._lock:
if (action not in fields or not isinstance(payload, dict) or
set(payload) != fields[action] | {"apply"} or
@@ -131,11 +140,20 @@ def stage(self, action, payload):
self._public["phase"] not in phases[action]):
raise MigrationError("Finish the current backup setup step first.")
if action == "enable_schedule" and (
+ self._pending_upload is not None or
self._last_backup is None or
self._last_backup["receipt"]["source_coverage"] != "complete" or
self._last_backup["receipt"]["at_risk_threads"] != 0):
raise MigrationError("Review incomplete backup coverage before enabling automatic backups.")
values = {name: payload[name] for name in fields[action]}
+ if action == "abandon_upload" and (
+ values["confirm_abandon"] is not True or
+ not isinstance(values["reservation_id"], str) or
+ not re.fullmatch(_UUID, values["reservation_id"]) or
+ self._pending_upload is None or
+ self._pending_upload["can_abandon"] is not True or
+ values["reservation_id"] != self._pending_upload["reservation_id"]):
+ raise MigrationError("Review and confirm this exact unpublished upload first.")
if action == "send_code":
values["purchase_link"] = purchase_token(values["purchase_link"])
if action == "pair":
@@ -158,6 +176,10 @@ def run():
"retry with this same connection and key. Previously verified snapshots "
"are kept. Automatic protection is not active; contact "
"joshua@segeren.com if needed." if action == "first_backup" else
+ "Upload status or cleanup could not be confirmed. Keep its pending state. "
+ "Use Check upload status before trying again; previously verified backups "
+ "are kept. Contact joshua@segeren.com if needed."
+ if action in ("check_upload", "abandon_upload") else
"The schedule change could not be confirmed. Check background status "
"before retrying. Existing backups are kept; contact joshua@segeren.com."
if action in ("enable_schedule", "disable_schedule") else
@@ -205,6 +227,56 @@ def _claim(self, client):
self._binding["deviceId"], apply=True))
def _perform(self, action, values):
+ if action == "leave_upload_review":
+ # Leave the view, not the durable upload. No journal, reservation,
+ # published backup or schedule is removed by this navigation step.
+ self._update(phase="backup_ready" if self._last_backup else "key_ready")
+ return
+ if action in ("check_upload", "abandon_upload"):
+ if self.source_home is None:
+ raise MigrationError("The backup source has not been configured.")
+ path, key_id = self._keys.backup_metadata(self._binding)
+ anchor = {**self._binding, "keyId": key_id}
+ if action == "check_upload":
+ result = pending_hosted_upload(self.source_home, self._binding["deviceId"],
+ str(path), expected_binding=anchor)
+ # The transport boundary returns only this fixed public shape.
+ if not isinstance(result, dict):
+ raise MigrationError("The pending-upload status is invalid.")
+ fields = {"pending", "automatic_protection_verified"}
+ if result.get("pending") is True:
+ fields |= {"reservation_id", "snapshot_id", "local_phase", "remote_status", "can_abandon"}
+ if (set(result) != fields or
+ type(result["pending"]) is not bool or result["automatic_protection_verified"] is not False or
+ result["pending"] and (
+ any(not isinstance(result[k], str) or not re.fullmatch(_UUID, result[k])
+ for k in ("reservation_id", "snapshot_id")) or
+ result["local_phase"] not in ("reserving", "active", "cleanup_pending") or
+ result["remote_status"] not in ("active", "cleanup_pending", "released", "published") or
+ type(result["can_abandon"]) is not bool or
+ result["can_abandon"] != (result["remote_status"] != "published"))):
+ raise MigrationError("The pending-upload status is invalid.")
+ with self._lock:
+ self._pending_upload = dict(result) if result["pending"] else None
+ self._public["phase"] = ("pending_upload" if result["pending"] else
+ "backup_ready" if self._last_backup else "key_ready")
+ return
+ result = abandon_hosted_upload(self.source_home, self._binding["deviceId"],
+ str(path), expected_binding=anchor, reservation_id=values["reservation_id"], apply=True)
+ if (not isinstance(result, dict) or set(result) != {
+ "applied", "reservation_id", "status", "automatic_protection_verified"} or
+ result["applied"] is not True or result["reservation_id"] != values["reservation_id"] or
+ result["status"] not in ("cleanup_pending", "released") or
+ result["automatic_protection_verified"] is not False):
+ raise MigrationError("The upload cleanup receipt is invalid.")
+ with self._lock:
+ if result["status"] == "released":
+ self._pending_upload = None
+ self._public["phase"] = "backup_ready" if self._last_backup else "key_ready"
+ else:
+ self._pending_upload = {**self._pending_upload,
+ "remote_status": "cleanup_pending", "local_phase": "cleanup_pending"}
+ return
if action in ("enable_schedule", "disable_schedule"):
if self.source_home is None:
raise MigrationError("The backup source has not been configured.")
@@ -234,6 +306,7 @@ def _perform(self, action, values):
self.registry.sync_recovery_checkpoint()
with self._lock:
self._last_backup = saved
+ self._pending_upload = None
self._public["phase"] = "backup_ready"
return
if action == "prepare_key":
diff --git a/tests/manual_hosted_setup_fixture.py b/tests/manual_hosted_setup_fixture.py
new file mode 100644
index 00000000..ed28c85d
--- /dev/null
+++ b/tests/manual_hosted_setup_fixture.py
@@ -0,0 +1,108 @@
+"""Loopback-only rendered UI fixture, not cloud or encryption acceptance.
+
+No Codex files, accounts, Keychain, provider or billing calls. This serves the
+actual dashboard with explicitly labelled synthetic unfinished-upload states.
+Run with PYTHONPATH=src python3 tests/manual_hosted_setup_fixture.py.
+"""
+
+import argparse
+import json
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import urlsplit
+
+from codex_migrate.vault_dashboard import VAULT_HTML
+
+
+RESERVATION = "11111111-1111-4111-8111-111111111111"
+SNAPSHOT = "22222222-2222-4222-8222-222222222222"
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--state", choices=("active", "cleanup_pending", "released", "published"), default="active")
+ args = parser.parse_args()
+ state = {"remote": args.state, "phase": "pending_upload"}
+
+ def public():
+ result = {"enabled": True, "phase": state["phase"], "status": "ready",
+ "automatic_protection_verified": False, "upload_authorized": False,
+ "last_backup_checked_at": "2026-10-03T00:00:00+00:00",
+ "last_backup": {"status": "published", "source_coverage": "complete", "at_risk_threads": 0},
+ "background": {"enabled": False}}
+ if state["remote"] is not None:
+ result["pending_upload"] = {"pending": True, "reservation_id": RESERVATION,
+ "snapshot_id": SNAPSHOT, "local_phase": "active", "remote_status": state["remote"],
+ "can_abandon": state["remote"] != "published", "automatic_protection_verified": False}
+ return result
+
+ class Handler(BaseHTTPRequestHandler):
+ def log_message(self, *args):
+ pass
+
+ def send(self, code, value, content_type="application/json"):
+ data = value.encode() if isinstance(value, str) else json.dumps(value).encode()
+ self.send_response(code)
+ self.send_header("Content-Type", content_type)
+ self.send_header("Content-Length", str(len(data)))
+ self.send_header("Cache-Control", "no-store")
+ self.send_header("X-Content-Type-Options", "nosniff")
+ self.end_headers()
+ self.wfile.write(data)
+
+ def do_GET(self):
+ path = urlsplit(self.path).path
+ if path == "/vault":
+ self.send(200, VAULT_HTML.replace("
Connect this Mac
",
+ "
Connect this Mac
SIMULATED UI FIXTURE — no real backup, account or subscription.