@maudecode/talaria-web 1.19.0 → 1.21.0

package/sidecar/talaria_sidecar/agent_mutation.py

@@ -29,6 +29,8 @@ _SESSIONS = {}
 _SESSIONS_LOCK = threading.Lock()
 _CONSENTS = {}
 CONSENT_SECONDS = 300
+# One lease exchange, including the worker's unwind after a refused drain.
+LEASE_SECONDS = 330
 
 
 def _close(session):
@@ -119,7 +121,59 @@ def _native_source_repair(root):
         raise
 
 
-def recovery_receipts(runtime, *, watch=False):
+def _receipt_candidates(path, pattern, cache):
+    """Cache discovery, never receipt presence; missing paths watch their nearest existing ancestor."""
+    key = (path, pattern)
+    if cache is not None:
+        ancestor = path
+        while True:
+            try:
+                stat = ancestor.stat()
+                break
+            except FileNotFoundError:
+                if ancestor == ancestor.parent:
+                    raise
+                ancestor = ancestor.parent
+        stamp = (ancestor, stat.st_dev, stat.st_ino, stat.st_mode, stat.st_mtime_ns, stat.st_ctime_ns, stat.st_size)
+        now = time.monotonic()
+        previous = cache.get(key)
+        if previous is not None and previous[0] == stamp and 0 <= now - previous[1] < 1:
+            return previous[2]
+    if pattern is not None:
+        try:
+            # glob suppresses enumeration errors, which cannot authorize Agent admission.
+            with os.scandir(path) as children:
+                found = tuple(path / child.name for child in children if Path(child.name).match(pattern))
+        except FileNotFoundError:
+            found = ()
+    else:
+        try:
+            found = (path,) if any(' refs/talaria/autostash/pending/' in line for line in path.read_text().splitlines()) else ()
+        except FileNotFoundError:
+            found = ()
+    if cache is not None:
+        if len(cache) >= 16:
+            cache.clear()  # Bound retained paths if an installer repeatedly redirects Git metadata.
+        cache[key] = (stamp, now, found)
+    return found
+
+
+def _process_presence(pid):
+    """A stdlib rearm trigger only; native identity verification alone decides recovery."""
+    if os.name == 'nt' or pid <= 0:
+        return 'unknown'
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return 'exited'
+    except PermissionError:
+        pass
+    except (OSError, OverflowError):
+        return 'unknown'
+    return 'present'
+
+
+def recovery_receipts(runtime, *, watch=False, discovery_cache=None):
     """Read only the configured checkout's receipts without importing its possibly torn code."""
     root, home = runtime.agent_dir, runtime.hermes_home
     if root is None:
@@ -133,24 +187,29 @@ def recovery_receipts(runtime, *, watch=False):
     paths = [services.recovery_path(root, home), marker, native,
              root / '.update-incomplete', root / '.lazy-refresh-incomplete',
              gitdir / 'hermes-update-pull', root / '.hermes-update-zip-swap']
-    paths.extend(home.glob(native.name + '.*.claim'))
+    paths.extend(_receipt_candidates(home, native.name + '.*.claim', discovery_cache))
     common = gitdir
     try:
         common = (gitdir / (gitdir / 'commondir').read_text().strip()).resolve()
     except FileNotFoundError:
         pass
-    paths.extend((common / 'refs/talaria/autostash/pending').glob('*'))
+    paths.extend(_receipt_candidates(common / 'refs/talaria/autostash/pending', '*', discovery_cache))
     packed = common / 'packed-refs'
-    try:
-        if any(' refs/talaria/autostash/pending/' in line for line in packed.read_text().splitlines()):
-            paths.append(packed)
-    except FileNotFoundError:
-        pass
+    paths.extend(_receipt_candidates(packed, None, discovery_cache))
     def stamps(candidates):
         result = []
         for path in sorted(set(candidates)):
             try:
                 stat = path.lstat()
+                if path == services.recovery_path(root, home):
+                    # Completed correlation is history, not admission debt. Malformed evidence fails closed.
+                    try:
+                        state = services.ServiceRecovery(root, home, None, None, None).state
+                    except RuntimeError:
+                        state = {}
+                    if (state.get('update_operation', {}).get('recovered_revision') and not state.get('transaction')
+                            and not state['entries'] and not state.get('sync_failed')):
+                        continue
                 result.append((str(path), stat.st_ino, stat.st_mtime_ns, stat.st_size))
             except FileNotFoundError:
                 pass
@@ -169,15 +228,23 @@ def recovery_receipts(runtime, *, watch=False):
                     watched.append(common / ref)
         except (OSError, UnicodeError):
             pass
+        lifecycle = []
         try:
             body = json.loads(services.recovery_path(root, home).read_text())
             for baseline in body.get('tree', {}).get('baselines', []):
                 changed = [*baseline.get('dirty_at_pause', []), *baseline.get('move_paths', [])]
                 changed.extend(path for paths in baseline.get('landed', {}).values() for path in paths)
                 watched.extend(root / path for path in changed if isinstance(path, str) and not Path(path).is_absolute() and '..' not in Path(path).parts)
+            # A retained gateway's exit or successor rearms exhausted recovery without changing any receipt.
+            for entry in body.get('entries', []):
+                if entry.get('purpose') == 'gateway' and isinstance(entry.get('home'), str):
+                    watched.append(Path(entry['home']) / 'gateway.pid')
+                    pids = {**entry.get('retired_processes', {}), **entry.get('processes', {})}
+                    lifecycle.extend(('process', int(pid), _process_presence(int(pid))) for pid in sorted(pids, key=int))
         except (OSError, ValueError, TypeError, AttributeError):
             pass  # The receipt's own stamp still rearms corrected evidence; the worker reports its exact refusal.
         found.extend(stamps(watched))
+        found.extend(lifecycle)
     return found, marker
 
 
@@ -186,6 +253,19 @@ def recover_retained(runtime, ctx, *, probe=False, complete_revision=None):
     receipts, _ = recovery_receipts(runtime, watch=True)
     fingerprint = hashlib.sha256(json.dumps(receipts).encode()).hexdigest() if receipts else ''
     result = {'ok': not receipts, 'owed': bool(receipts), 'fingerprint': fingerprint, 'detail': ''}
+    def correlated():
+        if runtime.agent_dir is None:
+            return {}
+        try:
+            state = services.ServiceRecovery(runtime.agent_dir.resolve(), runtime.hermes_home, None, None, None).state
+        except RuntimeError:
+            return {}  # Discovery retains malformed debt; the leased worker reports its refusal.
+        operation = state.get('update_operation')
+        if operation and ((state.get('transaction') or {}).get('operation_id') == operation['operation_id'] or (not recovery_receipts(runtime)[0] and operation.get('recovered_revision'))):
+            return {'operation': operation, **({'revision': operation['recovered_revision']} if operation.get('recovered_revision') else {})}
+        return {}
+    association = correlated()
+    result.update(association)
     if complete_revision is not None:
         if not isinstance(complete_revision, str) or not re.fullmatch(r'[a-f0-9]{40}', complete_revision):
             raise InvalidParams('A verified loaded revision is required to complete recovery.')
@@ -203,6 +283,8 @@ def recover_retained(runtime, ctx, *, probe=False, complete_revision=None):
     env.update(HERMES_HOME=str(runtime.hermes_home), HERMES_DISABLE_LAZY_INSTALLS='1',
                PYTHONPATH=str(Path(__file__).parents[1]) + os.pathsep + str(root))
     try:
+        if complete_revision is None:
+            runtime.retire()
         with tempfile.TemporaryFile() as stdout, tempfile.TemporaryFile() as stderr:
             child = subprocess.Popen([sys.executable, '-m', 'talaria_sidecar.agent_mutation', '--recover-current', str(root), complete_revision or ''],
                                      cwd=root, env=env, stdin=subprocess.PIPE, stdout=stdout, stderr=stderr)
@@ -231,18 +313,28 @@ def recover_retained(runtime, ctx, *, probe=False, complete_revision=None):
                     child.kill()
                     child.wait()
         remaining, _ = recovery_receipts(runtime, watch=True)
-        return {**result, **reply, 'owed': bool(remaining),
+        return {**result, **reply, **(correlated() if association else {}), 'owed': bool(remaining),
                 'fingerprint': hashlib.sha256(json.dumps(remaining).encode()).hexdigest() if remaining else ''}
     finally:
         _ACTION_LOCK.release()
 
 
+def _drain_progress(result):
+    progress = result.get("progress") if isinstance(result, dict) and result.keys() == {"progress"} else None
+    if (not isinstance(progress, dict) or progress.get("phase") != "gateway_drain"
+            or not isinstance(progress.get("deadline_seconds"), (int, float)) or isinstance(progress["deadline_seconds"], bool)
+            or not 0 <= progress["deadline_seconds"] <= services.GATEWAY_DRAIN_CEILING
+            or not isinstance(progress.get("services"), list) or not all(isinstance(name, str) for name in progress["services"])):
+        return None
+    return {"phase": "gateway_drain", "deadline_seconds": progress["deadline_seconds"], "services": progress["services"]}
+
+
 def _exchange(session, request, ctx):
     with session["lock"]:
         if request is not None:
             session["proc"].stdin.write(json.dumps(request) + "\n")
             session["proc"].stdin.flush()
-        deadline = time.monotonic() + 330
+        deadline = time.monotonic() + LEASE_SECONDS
         while True:
             ctx.check_cancelled()
             if time.monotonic() >= deadline:
@@ -254,6 +346,14 @@ def _exchange(session, request, ctx):
             if line is None:
                 raise RpcError("Agent writer lease exited; its pause journal retains recovery.", condition="agent_update_unsafe")
             result = json.loads(line)
+            if isinstance(result, dict) and "progress" in result:
+                progress = _drain_progress(result)
+                if progress is None:
+                    raise RpcError("Invalid Agent writer lease response.", condition="agent_update_unsafe")
+                # The worker's own drain deadline is bounded; unwind keeps the ordinary lease margin.
+                deadline = max(deadline, time.monotonic() + progress["deadline_seconds"] + LEASE_SECONDS)
+                ctx.emit("progress", progress)
+                continue
             if not isinstance(result, dict) or not isinstance(result.get("ok"), bool):
                 raise RpcError("Invalid Agent writer lease response.", condition="agent_update_unsafe")
             return {"ok": result["ok"], "skipped": result.get("skipped") is True, "detail": str(result.get("detail") or ""),
@@ -278,6 +378,11 @@ def call(runtime, ctx, params):
             raise InvalidParams("resolved profile homes are required")
         if any(Path(home).resolve().is_relative_to(root.resolve()) for home in homes):
             raise InvalidParams("Agent profile homes must stay outside the source checkout to survive update cleanup")
+        operation_id = params.get('operation_id')
+        baseline = params.get('baseline_revision')
+        if operation_id is not None and (not isinstance(operation_id, str) or not re.fullmatch(r'[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}', operation_id)
+                or not isinstance(baseline, str) or not re.fullmatch(r'[a-f0-9]{40}', baseline)):
+            raise InvalidParams('An operation requires its immutable baseline revision.')
         intent = params.get('intent', '')
         refresh_token = params.get('refresh_token')
         if not isinstance(intent, str) or len(intent) > 1024:
@@ -306,7 +411,7 @@ def call(runtime, ctx, params):
                 stderr.close()
                 return {"ok": False, "skipped": False, "detail": "A gateway lifecycle action is still running."}
             try:
-                proc = subprocess.Popen([sys.executable, "-m", "talaria_sidecar.agent_mutation", str(root), revision, json.dumps(homes), binding or ""],
+                proc = subprocess.Popen([sys.executable, "-m", "talaria_sidecar.agent_mutation", str(root), revision, json.dumps(homes), binding or "", json.dumps({"operation_id": operation_id, "baseline_revision": baseline}) if operation_id else ""],
                                         cwd=root, env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=stderr, text=True)
             except BaseException:
                 stderr.close()
@@ -357,7 +462,12 @@ def call(runtime, ctx, params):
                 _CONSENTS[nonce] = {key: session[key] for key in ('root', 'revision', 'homes', 'intent')}
                 _CONSENTS[nonce].update(binding=confirmation['binding'], expires=time.monotonic() + CONSENT_SECONDS)
             result['refresh_confirmation'] = {'token': nonce, 'services': confirmation['services']}
+        if action == 'begin' and not result['ok'] and 'refresh_confirmation' not in result:
+            probe = recover_retained(runtime, ctx, probe=True)
+            correlation = probe.get('operation')
+            result['recovery_required'] = bool(correlation and correlation['operation_id'] == params.get('operation_id')) if params.get('operation_id') else probe['owed']
         if action == "begin" and result["ok"]:
+            runtime.retire()
             return {**result, "token": token}
         if action != "finish" and result["ok"]:
             return result
@@ -449,7 +559,7 @@ def _writer_ledger(root, identity):
     return found
 
 
-def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None):
+def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None, operation=None):
     if os.name not in {"posix", "nt"}:
         raise RuntimeError("A cooperative Agent writer lease is unavailable on this platform; source was not changed.")
     sys.path.insert(0, str(root))
@@ -478,6 +588,13 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
         if not found["ok"]:
             raise RuntimeError("The installed Agent revision could not be verified before quiescence.")
         initial = found["detail"]
+        if operation and operation['baseline_revision'] != initial:
+            raise RuntimeError('The Agent baseline changed before the operation acquired its native lease.')
+        previous = recovery.state.get('update_operation')
+        if operation and previous and recovery.state.get('transaction') and previous['operation_id'] != operation['operation_id']:
+            raise RuntimeError('The previous update operation still owns native recovery.')
+        if operation and previous and previous['operation_id'] == operation['operation_id'] and (previous['target_revision'] != revision or previous['baseline_revision'] != operation['baseline_revision']):
+            raise RuntimeError('The immutable target or baseline changed within the same update operation.')
         initial_tree = records.tree_state(root)
         if initial_tree is None or initial_tree.get("pre_sha") != initial or initial_tree.get("dirty_at_pause") is None:
             raise RuntimeError("The Agent source baseline could not be proved before quiescence.")
@@ -562,7 +679,10 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
                      unmapped_pids=[e["pid"] for e in gateway_entries if not e.get("kind")],
                      identities=owner_identities, resume_needed=bool(gateway_entries))
         records.record_pause(token, adopted, claims)
-        recovery.state.setdefault('transaction', {'revision': revision, 'homes': sorted(map(str, homes))})
+        transaction = recovery.state.setdefault('transaction', {'revision': revision, 'homes': sorted(map(str, homes))})
+        if operation:
+            recovery.state['update_operation'] = {**operation, 'target_revision': revision, 'stage': 'install', 'source_moved': False}
+            transaction['operation_id'] = operation['operation_id']
         recovery.save(token)
         if legacy:
             whole, why = records.tree_is_whole(token, root)
@@ -583,12 +703,16 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
         records.mark_stop_requested(token, sorted({pid for e in gateway_entries for pid in (e['pid'], e.get('service_pid', e['pid']))}))
         for entry in backend_entries:
             recovery.stop(entry, stopped)
-        gateway_deadline = recovery.gateway_deadline()
+        # Every profile shares the longest native drain; the lease reports it so its RPC keeps custody.
+        gateway_deadline = recovery.gateway_deadline(homes)
+        if gateway_entries:
+            send({'progress': {'phase': 'gateway_drain', 'deadline_seconds': round(max(gateway_deadline - time.monotonic(), 0), 3),
+                               'services': sorted({services._name(e) for e in gateway_entries})}})
         for entry in gateway_entries:
             if stopped.is_set() or time.monotonic() >= gateway_deadline:
                 raise RuntimeError('Gateway drain has not completed; its durable resume obligation is retained.')
             if entry.get('processes'):
-                services.verify_processes(entry, records)
+                recovery.verify_processes(entry)
             recovery.gateway_requested(entry)
             for pid in {entry['pid'], entry.get('service_pid', entry['pid'])}:
                 records.mark_stop_sent(token, pid)
@@ -670,6 +794,8 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
                 gate = modules["update_cmd_pause_gate"]._checkout_move(token, revision, paths=paths, revert=True) if mutating else contextlib.nullcontext({})
                 if mutating:
                     recovery.state['transaction']['dependencies_verified'] = False
+                    if args[0] in {'merge', 'reset', 'checkout'} and recovery.state.get('update_operation'):
+                        recovery.state['update_operation'].pop('source_moved', None)
                 move_marker = None
                 if args[0] == 'merge' and '--ff-only' in args or args[0] == 'reset' and '--hard' in args:
                     commit = modules['update_cmd_commit']
@@ -693,6 +819,8 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
                             recovery.state['transaction']['dependencies_verified'] = True
                     else:
                         result = {'ok': False, 'detail': 'The source move did not leave a verified whole target; native rollback remains owed.'}
+                if result['ok'] and move_marker is not None and recovery.state.get('update_operation'):
+                    recovery.state['update_operation']['source_moved'] = revision != recovery.state['update_operation']['baseline_revision']
                 if result["ok"] and applying and whole_before:
                     after = records.tree_state(root)
                     if before is None or after is None or before["pre_sha"] != after["pre_sha"]:
@@ -703,11 +831,17 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
                             baseline.update(after)
                     records.write(token)
                 recovery.save(token)
+            if not result['ok'] and recovery.state.get('update_operation'):
+                recovery.state['update_operation'].setdefault('attempt_error', result.get('detail', '')[:2000])
+                recovery.state['update_operation'].setdefault('failed_stage', recovery.state['update_operation']['stage'])
+                recovery.save(token)
             send(result)
     except BaseException as exc:
         error = str(exc)
     finally:
         try:
+            # Cancellation or a lost lease pipe ends the drain wait; the retained debt keeps the gateway owed.
+            unwind_deadline = time.monotonic() if stopped.is_set() else gateway_deadline
             if token:
                 live = any(records.identity_is_live({"pid": int(pid), "ct": ct}) for pid, ct in token.get("identities", {}).items())
                 found = _command(modules["update_custody"].git_argv(["git"], ["rev-parse", "HEAD"]), root, 10, threading.Event(), modules["update_custody"])
@@ -720,7 +854,7 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
                 if live and not changed and not sync_failed and records.tree_is_whole(token, root)[0]:
                     # An untouched gateway must not strand a backend stopped earlier in a partial pause.
                     recovery.save(token)
-                    recovery.resume(_writer_ledger, gateway_deadline=gateway_deadline)
+                    recovery.resume(_writer_ledger, gateway_deadline=unwind_deadline)
                 if live or sync_failed or (changed and needs_sync and not locals().get("response", {}).get("ok")):
                     raise RuntimeError("Gateway resume remains owed until writer drain and dependency repair complete.")
                 whole, why = records.tree_is_whole(token, root)
@@ -729,6 +863,9 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
                 pending = _command(modules['update_custody'].git_argv(['git'], ['for-each-ref', '--format=%(objectname)', 'refs/talaria/autostash/pending/']), root, 10, threading.Event(), modules['update_custody'])
                 if not pending['ok'] or pending['detail']:
                     raise RuntimeError('Gateway resume remains owed until retained local Agent edits are restored.')
+                if recovery.state.get('update_operation'):
+                    recovery.state['update_operation']['stage'] = 'gateway_restart'
+                    recovery.save(token)
                 if token.get("resume_needed"):
                     if bootstrap_repair:
                         records.write({**token, "resume_needed": True}, owner=records.UNOWNED)
@@ -742,7 +879,7 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
                 if token.get("resume_needed") or token.get("resume_deferred"):
                     raise RuntimeError("Gateway resume could not be verified; its obligation is retained.")
                 recovery.save(token)
-                recovery.resume(_writer_ledger, gateway_deadline=gateway_deadline)
+                recovery.resume(_writer_ledger, gateway_deadline=unwind_deadline)
             if token and not handed_off:
                 records.discharge(token)
                 from .runtime import AgentRuntime
@@ -751,6 +888,8 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
                     recovery.state['transaction']['runtime_revision'] = found['detail']
                     recovery.save(token)
                 else:
+                    if recovery.state.get('update_operation'):
+                        recovery.state['update_operation'].update(stage='agent_ready', recovered_revision=found['detail'])
                     recovery.state.pop('transaction', None)
                     recovery.save()
         except BaseException as exc:
@@ -758,21 +897,31 @@ def _worker(root, revision, homes, requests, stopped, send, refresh_binding=None
             if token and not handed_off:
                 records.write({**token, "resume_needed": True}, owner=records.UNOWNED)
         finally:
-            lock.release()
+            try:
+                if error and token and recovery and recovery.state.get('update_operation') and (recovery.state.get('transaction') or {}).get('operation_id') == recovery.state['update_operation']['operation_id']:
+                    operation = recovery.state['update_operation']
+                    operation.setdefault('attempt_error', error[:2000])
+                    operation.setdefault('failed_stage', operation['stage'])
+                    recovery.save(token)
+            finally:
+                lock.release()
     send({"ok": error is None, "detail": error or ""})
 
 
 def _resume_current(root, custody, stopped=None, complete_revision=None):
+    # Resolve target PM code in a fresh stdlib process, after any source/dependency change.
     try:
-        from hermes_cli._launchers import resolve_store_python
-        python = resolve_store_python(root)
+        launchers = importlib.import_module('hermes_cli._launchers')
+        if not Path(launchers.__file__).resolve().is_relative_to(root):
+            raise RuntimeError('Recovery loaded another Agent bootstrap selector.')
+        bootstrap = launchers.resolve_store_python(root)
     except ModuleNotFoundError as exc:
-        if exc.name != "hermes_cli._launchers":
+        if exc.name != 'hermes_cli._launchers':
             raise
-        python = None
-    if python is None:
-        python = next((path for path in (root / ".venv/bin/python", root / "venv/bin/python", root / "venv/Scripts/python.exe") if path.is_file()), Path(sys.executable))
-    result = _command([str(python), "-m", "talaria_sidecar.agent_mutation", "--resume-leased", str(root), complete_revision or ""], root, 660, stopped or threading.Event(), custody, cooperative=True)
+        bootstrap = None
+    # A copied macOS venv interpreter can be its own _base_executable and later be retired.
+    bootstrap = bootstrap or getattr(sys, '_base_executable', None) or sys.executable
+    result = _command([str(bootstrap), "-m", "talaria_sidecar.agent_mutation", "--select-resume", str(root), complete_revision or "", sys.executable], root, 660, stopped or threading.Event(), custody, cooperative=True)
     try:
         reply = json.loads(result["detail"]) if result["ok"] else {}
         return {**reply, "ok": result["ok"] and reply.get("ok") is True, "detail": str(reply.get("detail") or result["detail"])}
@@ -780,6 +929,46 @@ def _resume_current(root, custody, stopped=None, complete_revision=None):
         return {"ok": False, "detail": "The current Agent could not verify its retained gateway resume obligation."}
 
 
+def _recovery_environment(root):
+    """Reuse PM's selector and packaged launch policy without copying its facts/path rules."""
+    sys.path.insert(0, str(root))
+    environments = importlib.import_module('pm.environments')
+    if any(not Path(sys.modules[name].__file__).resolve().is_relative_to(root)
+           for name in ('pm', 'pm.environments', 'hermes_constants')):
+        raise RuntimeError('Recovery loaded another Agent environment selector.')
+    selected = environments.committed_venv(root)
+    if selected is None:
+        if environments.install_state_dir(root).exists():
+            raise RuntimeError('No dependency environment is committed for this Agent install; recovery remains owed.')
+        selected = environments.selected_venv(root)
+    return environments, selected
+
+
+def _select_resume(root, complete_revision, legacy_python):
+    if (root / 'pm').exists():
+        environments, selected = _recovery_environment(root)
+        command = environments.venv_command(root, selected)
+        environment = str(selected)
+    else:
+        python = next((path for venv in ('.venv', 'venv')
+                       for path in (root / venv / 'bin/python', root / venv / 'Scripts/python.exe') if path.is_file()), Path(legacy_python))
+        command, environment = [str(python)], ''
+    # Keep bin/python intact: realpath would turn a POSIX venv into its bare tool.
+    argv = [*command, '-m', 'talaria_sidecar.agent_mutation', '--resume-leased', str(root), complete_revision or '', environment]
+    os.execv(argv[0], argv)
+
+
+def _verify_recovery_environment(root, expected):
+    from .runtime import _check_site_packages_python
+    environments, selected = _recovery_environment(root)
+    if str(selected) != expected or environments.venv_python_version(selected) != sys.version_info[:2]:
+        raise RuntimeError('Agent recovery dependency environment changed or has an incompatible Python ABI.')
+    site = environments.site_packages(selected)
+    if not site.is_dir() or site.resolve() not in {Path(entry).resolve() for entry in sys.path if entry}:
+        raise RuntimeError('Agent recovery did not enter its selected dependency environment.')
+    _check_site_packages_python()
+
+
 def _resume_worker(root, stopped=None, complete_revision=None):
     sys.path.insert(0, str(root))
     from hermes_cli import update_lock, update_pause_record as records, process_identity, update_cmd_posix_pause
@@ -820,7 +1009,13 @@ def _resume_worker(root, stopped=None, complete_revision=None):
         if revision not in {r for b in tree.get('baselines', []) for r in [b.get('pre_sha'), *b.get('move_targets', []), *b.get('landed', {})]}:
             return {'ok': False, 'detail': 'Installed revision is outside the retained transaction; recovery was refused.'}
         moved = any(b.get('pre_sha') != revision for b in tree.get('baselines', []))
+        operation = recovery.state.get('update_operation')
+        if operation and any(sha != operation['baseline_revision'] for b in tree.get('baselines', []) for sha in b.get('landed', {})):
+            operation['source_moved'] = True
         transaction = recovery.state.get('transaction') or {}
+        operation = recovery.state.get('update_operation')
+        if operation and transaction.get('operation_id') != operation['operation_id']:
+            recovery.state.pop('update_operation', None)
         if recovery.state.get('sync_failed') or (moved and not transaction.get('dependencies_verified')) or (marker and marker.exists() and not transaction):
             if _writer_ledger(root, process_identity):
                 return {'ok': False, 'detail': 'Recorded dependency repair is waiting for the existing writer drain; no additional stop was sent.'}
@@ -833,9 +1028,10 @@ def _resume_worker(root, stopped=None, complete_revision=None):
                 if response.get('ok') is not True:
                     return {'ok': False, 'detail': 'Recorded dependency repair failed: ' + str(response.get('detail') or synced['detail'])}
                 recovery.state['sync_failed'] = False
-                if transaction:
-                    transaction['dependencies_verified'] = True
+                transaction = recovery.state.setdefault('transaction', {'revision': revision, 'homes': [str(runtime.hermes_home)]})
+                transaction['dependencies_verified'] = True
                 recovery.save(tree)
+                return _resume_current(root, custody, stopped, complete_revision)
             elif recovery.state.get('sync_failed'):
                 return {'ok': False, 'detail': 'The recorded dependency repair module is missing.'}
         whole, why = records.tree_is_whole(tree, root)
@@ -850,7 +1046,16 @@ def _resume_worker(root, stopped=None, complete_revision=None):
         if not Path(main_module.__file__).resolve().is_relative_to(root):
             raise RuntimeError("Gateway recovery loaded another Agent runtime.")
         records.recover(argv=[])
-        recovery.resume(_writer_ledger)
+        if recovery.state.get('update_operation'):
+            recovery.state['update_operation']['stage'] = 'gateway_restart'
+            recovery.save(tree)
+        try:
+            recovery.resume(_writer_ledger)
+        except services.GatewayDraining as exc:
+            return {'ok': False, 'draining': True, 'detail': str(exc)}
+        final_head = _command(custody.git_argv(['git'], ['rev-parse', 'HEAD']), root, 10, stopped, custody)
+        if not final_head['ok'] or final_head['detail'] != revision or not records.tree_is_whole(tree, root)[0]:
+            return {'ok': False, 'detail': 'Recovered source identity changed before readiness was verified; its evidence is retained.'}
         owed = records.record_path().exists() or bool(records._claims(records.record_path())) or bool(recovery.state['entries'])
         runtime_pending = bool((marker and marker.exists()) or (recovery.state.get('transaction') or {}).get('runtime_revision'))
         if not owed and runtime_pending:
@@ -861,11 +1066,16 @@ def _resume_worker(root, stopped=None, complete_revision=None):
                 transaction['runtime_revision'] = revision
                 recovery.save(tree)
         if not owed and not runtime_pending:
+            # Retain the transaction through durable marker removal, including a failed unlink or crash.
+            if marker:
+                marker.unlink(missing_ok=True)
+                if marker.parent.is_dir():
+                    recovery._sync_directory(marker.parent)
+            if recovery.state.get('update_operation'):
+                recovery.state['update_operation'].update(stage='agent_ready', recovered_revision=revision)
             recovery.state.pop('transaction', None)
             recovery.state['sync_failed'] = False
             recovery.save()
-            if marker:
-                marker.unlink(missing_ok=True)
         return {"ok": not owed, "revision": revision, "runtime_pending": runtime_pending, "detail": "Gateway recovery remains durably recorded." if owed else ""}
     finally:
         lock.release()
@@ -926,9 +1136,11 @@ def _command(argv, root, timeout, stopped, custody, *, cooperative=False):
 def main():
     for key in ("GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_INDEX_FILE"):
         os.environ.pop(key, None)
-    if len(sys.argv) > 2 and sys.argv[1] in {'--recover-current', '--resume', '--resume-leased'}:
+    if len(sys.argv) > 2 and sys.argv[1] in {'--recover-current', '--resume', '--resume-leased', '--select-resume'}:
         try:
             _native_source_repair(Path(sys.argv[2]).resolve())
+            if sys.argv[1] == '--select-resume':
+                _select_resume(Path(sys.argv[2]).resolve(), sys.argv[3], sys.argv[4])
         except BaseException as exc:
             print(json.dumps({'ok': False, 'detail': str(exc) if str(exc) != '1' else 'Native recorded source repair could not complete; its receipt remains owed.'}), flush=True)
             return
@@ -962,11 +1174,13 @@ def main():
             return
         if sys.argv[1] in {"--resume", "--resume-leased"}:
             with contextlib.redirect_stdout(sys.stderr):
+                if len(sys.argv) > 4 and sys.argv[4]:
+                    _verify_recovery_environment(Path(sys.argv[2]).resolve(), sys.argv[4])
                 reply = _resume_worker(Path(sys.argv[2]).resolve(), stopped if sys.argv[1] == "--resume-leased" else None, sys.argv[3] if len(sys.argv) > 3 and sys.argv[3] else None)
             send(reply)
             return
         with contextlib.redirect_stdout(sys.stderr):
-            _worker(Path(sys.argv[1]).resolve(), sys.argv[2], {Path(h).resolve() for h in json.loads(sys.argv[3])}, requests, stopped, send, sys.argv[4] if len(sys.argv) > 4 else None)
+            _worker(Path(sys.argv[1]).resolve(), sys.argv[2], {Path(h).resolve() for h in json.loads(sys.argv[3])}, requests, stopped, send, sys.argv[4] if len(sys.argv) > 4 else None, json.loads(sys.argv[5]) if len(sys.argv) > 5 and sys.argv[5] else None)
     except BaseException as exc:
         send({"ok": False, "detail": str(exc)})