@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/remote-broker/worker.py

@@ -0,0 +1,1007 @@
+
+import contextlib, ctypes, errno, fcntl, hashlib, json, math, os, re, stat, sys, tempfile, time, uuid
+from typing import Any, Dict, List, Optional
+
+admitted = False
+
+def sync_directory(path: str) -> None:
+    descriptor = os.open(path, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try: os.fsync(descriptor)
+    finally: os.close(descriptor)
+
+def rename_without_replacement(source_directory: int, source: str, target_directory: int, target: str) -> None:
+    # The kernel must refuse an occupied destination. A stat/rename fallback
+    # would introduce another replacement race, including for directories.
+    library = ctypes.CDLL(None, use_errno=True)
+    if sys.platform == 'linux':
+        function, flag = library.renameat2, 1
+    elif sys.platform == 'darwin':
+        function, flag = library.renameatx_np, 4
+    else:
+        raise OSError(errno.ENOTSUP, 'Deletion requires atomic no-replace rename support')
+    function.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
+    function.restype = ctypes.c_int
+    if function(source_directory, os.fsencode(source), target_directory, os.fsencode(target), flag) != 0:
+        error = ctypes.get_errno()
+        raise OSError(error, os.strerror(error))
+
+def decode_owner_presence(data: bytes) -> Dict[str, float]:
+    if len(data) > 16 * 1024 * 1024:
+        raise ValueError('Owner presence registry exceeds its bounded read size')
+    document = json.loads(data)
+    if not isinstance(document, dict) or len(document) > 4096:
+        raise ValueError('Invalid resource owner presence registry')
+    result: Dict[str, float] = {}
+    for name, seen in document.items():
+        if not isinstance(name, str) or not name or len(name) > 200 or type(seen) not in [int, float]:
+            raise ValueError('Invalid resource owner presence entry')
+        try: timestamp = float(seen)
+        except (ValueError, OverflowError) as error:
+            raise ValueError('Invalid resource owner presence timestamp') from error
+        if not math.isfinite(timestamp):
+            raise ValueError('Invalid resource owner presence timestamp')
+        result[name] = timestamp
+    return result
+
+def register_owner_presence(control: str, owner: str, now: float) -> Dict[str, Any]:
+    # Recent presence is an advisory transfer prerequisite, never lease authority.
+    # A malformed cache is retained once and rebuilt solely from this request's
+    # immutable ID. Every other pane must register itself again before transfer.
+    owners_path = os.path.join(control, 'owners.json')
+    damaged_path = os.path.join(control, 'owners.json.damaged')
+    owners: Dict[str, float] = {}
+    recovered = False
+    try:
+        descriptor = os.open(owners_path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    except FileNotFoundError: descriptor = None
+    if descriptor is not None:
+        with os.fdopen(descriptor, 'rb') as stream:
+            opened = os.fstat(stream.fileno())
+            if not stat.S_ISREG(opened.st_mode):
+                raise ValueError('Owner presence registry must be a regular file; operator recovery required')
+            data = stream.read(16 * 1024 * 1024 + 1)
+            try: owners = decode_owner_presence(data)
+            except (ValueError, UnicodeDecodeError):
+                current = os.stat(owners_path, follow_symlinks=False)
+                if (opened.st_dev, opened.st_ino, opened.st_mtime_ns, opened.st_size) != (current.st_dev, current.st_ino, current.st_mtime_ns, current.st_size):
+                    raise ValueError('Owner presence registry changed; inspect and retry registration')
+                os.fsync(stream.fileno())
+                directory = os.open(control, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+                try:
+                    try: rename_without_replacement(directory, 'owners.json', directory, 'owners.json.damaged')
+                    except FileExistsError as error:
+                        raise ValueError('A retained damaged owner registry already exists; operator recovery required') from error
+                    os.fsync(directory)
+                finally: os.close(directory)
+                recovered = True
+    owners = {name: seen for name, seen in owners.items() if seen > now - 3600}
+    if owner not in owners and len(owners) >= 4096:
+        raise ValueError('Resource owner registry is full')
+    owners[owner] = now
+    fd, temporary = tempfile.mkstemp(dir=control)
+    published = False
+    try:
+        with os.fdopen(fd, 'w') as stream:
+            json.dump(owners, stream); stream.flush(); os.fsync(stream.fileno())
+        os.replace(temporary, owners_path)
+        published = True
+        sync_directory(control)
+    except OSError as error:
+        if published:
+            raise RuntimeError('Owner presence publication outcome is unresolved; inspect status after storage recovers before retrying: ' + str(error)) from error
+        raise
+    finally:
+        with contextlib.suppress(FileNotFoundError): os.unlink(temporary)
+    return {'registered_owner_id': owner, 'recovered_in_this_request': recovered,
+        'retained_copy_entry_present': os.path.lexists(damaged_path), 'retained_copy_name': 'owners.json.damaged',
+        'recent_owners': owners}
+
+def read_archive_bytes(path: str, limit: int) -> bytes:
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    with os.fdopen(descriptor, 'rb') as stream:
+        info = os.fstat(stream.fileno())
+        if not stat.S_ISREG(info.st_mode) or info.st_size > limit:
+            raise ValueError('Replay index or archived evidence exceeds its regular-file bound')
+        data = stream.read(limit + 1)
+        if len(data) > limit: raise ValueError('Replay index or archived evidence exceeds its byte bound')
+        return data
+
+def replay_manifest(directory: str, required: bool = False) -> Optional[Dict[str, Any]]:
+    if not required and not os.path.lexists(directory): return None
+    try:
+        if not stat.S_ISDIR(os.lstat(directory).st_mode): raise ValueError('Replay index must be a real directory')
+        value = json.loads(read_archive_bytes(os.path.join(directory, 'manifest.json'), 1048576))
+        if (not isinstance(value, dict) or set(value) != {'version', 'total', 'buckets'}
+            or type(value['version']) is not int or value['version'] != 1
+            or type(value['total']) is not int or not 0 <= value['total'] <= 1000000
+            or not isinstance(value['buckets'], dict) or len(value['buckets']) > 4096):
+            raise ValueError('Invalid bounded replay index manifest')
+        count = 0
+        for prefix, bucket in value['buckets'].items():
+            if (not isinstance(prefix, str) or re.fullmatch(r'[a-f0-9]{3}', prefix) is None
+                or not isinstance(bucket, dict) or set(bucket) != {'sha256', 'count'}
+                or not isinstance(bucket['sha256'], str) or re.fullmatch(r'[a-f0-9]{64}', bucket['sha256']) is None
+                or type(bucket['count']) is not int or not 1 <= bucket['count'] <= 4096):
+                raise ValueError('Invalid replay index manifest bucket')
+            count += bucket['count']
+        if count != value['total']: raise ValueError('Replay index manifest count changed')
+        return dict(value)
+    except (ValueError, OSError, UnicodeDecodeError) as error:
+        raise ValueError('Required replay index manifest is unavailable or invalid') from error
+
+def replay_key(parts: List[Any]) -> str:
+    return hashlib.sha256(json.dumps(parts, ensure_ascii=False, separators=(',', ':')).encode('utf-8', errors='backslashreplace')).hexdigest()
+
+def replay_bucket(directory: str, prefix: str, bucket: Dict[str, Any]) -> Dict[str, Any]:
+    try:
+        objects = os.path.join(directory, 'objects')
+        if not stat.S_ISDIR(os.lstat(objects).st_mode): raise ValueError('Replay objects must be a real directory')
+        data = read_archive_bytes(os.path.join(objects, bucket['sha256'] + '.json'), 2097152)
+        if hashlib.sha256(data).hexdigest() != bucket['sha256']: raise ValueError('Replay bucket checksum changed')
+        value = json.loads(data)
+        if (not isinstance(value, dict) or set(value) != {'version', 'entries'} or type(value['version']) is not int
+            or value['version'] != 1 or not isinstance(value['entries'], dict) or len(value['entries']) != bucket['count']):
+            raise ValueError('Invalid replay index bucket')
+        for key, pointer in value['entries'].items():
+            if (not isinstance(key, str) or re.fullmatch(r'[a-f0-9]{64}', key) is None or not key.startswith(prefix)
+                or not isinstance(pointer, dict) or set(pointer) != {'id', 'archive', 'sha256', 'kind'}
+                or not isinstance(pointer['id'], str) or str(uuid.UUID(pointer['id'])) != pointer['id']
+                or not isinstance(pointer['archive'], str) or re.fullmatch(r'[a-f0-9]{64}', pointer['archive']) is None
+                or not isinstance(pointer['sha256'], str) or re.fullmatch(r'[a-f0-9]{64}', pointer['sha256']) is None
+                or pointer['kind'] not in ['client', 'receipt']):
+                raise ValueError('Invalid replay index pointer')
+        return dict(value['entries'])
+    except (ValueError, OSError, UnicodeDecodeError) as error:
+        raise ValueError('Required replay index bucket is unavailable or invalid') from error
+
+def replay_lookup(directory: str, parts: List[Any], required: bool = False) -> Optional[Dict[str, Any]]:
+    header = replay_manifest(directory, required)
+    if header is None: return None
+    key = replay_key(parts)
+    bucket = header['buckets'].get(key[:3])
+    if bucket is None: return None
+    pointer = replay_bucket(directory, key[:3], bucket).get(key)
+    return dict(pointer) if pointer is not None else None
+
+def archived_receipt(control: str, pointer: Dict[str, Any]) -> Dict[str, Any]:
+    if pointer['kind'] != 'receipt': raise ValueError('Operation archived without a remote receipt; inspect its original client export')
+    directory = os.path.join(control, 'receipt-archives')
+    for path in [directory, os.path.join(directory, pointer['archive']), os.path.join(directory, pointer['archive'], 'receipts')]:
+        if not stat.S_ISDIR(os.lstat(path).st_mode): raise ValueError('Archived receipt directory changed')
+    data = read_archive_bytes(os.path.join(directory, pointer['archive'], 'receipts', pointer['id'] + '.json'), 1048576)
+    if hashlib.sha256(data).hexdigest() != pointer['sha256']: raise ValueError('Archived receipt checksum changed')
+    value = json.loads(data)
+    if not isinstance(value, dict) or value.get('id') != pointer['id'] or value.get('version') != 1:
+        raise ValueError('Invalid archived receipt identity')
+    return dict(value)
+
+def runtime_private_directory(path: str) -> None:
+    os.makedirs(path, mode=0o700, exist_ok=True)
+    info = os.lstat(path)
+    if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.geteuid() or info.st_mode & 0o077:
+        raise ValueError('Runtime archive requires a private real directory')
+    sync_directory(os.path.dirname(path))
+
+def publish_runtime_file(path: str, data: bytes, replace: bool = False) -> None:
+    if not replace and os.path.lexists(path):
+        if read_archive_bytes(path, 2097152) != data: raise ValueError('Immutable runtime archive changed')
+        return
+    fd, temporary = tempfile.mkstemp(dir=os.path.dirname(path))
+    try:
+        with os.fdopen(fd, 'wb') as stream:
+            stream.write(data); stream.flush(); os.fsync(stream.fileno())
+        if replace: os.replace(temporary, path)
+        else: os.link(temporary, path)
+        sync_directory(os.path.dirname(path))
+    finally:
+        with contextlib.suppress(FileNotFoundError): os.unlink(temporary)
+
+def retain_terminal_receipts(control: str, selected: List[Dict[str, Any]]) -> None:
+    # The caller holds the lease lock and selects only acknowledged terminal
+    # records without retained staging. Never discard full historical evidence.
+    if not selected: return
+    receipts = os.path.join(control, 'receipts')
+    originals = []
+    byte_count = 0
+    for receipt in selected:
+        data = read_archive_bytes(os.path.join(receipts, receipt['id'] + '.json'), 1048576)
+        byte_count += len(data)
+        if byte_count > 128 * 1048576: raise ValueError('Runtime archive exceeds its bounded batch byte budget')
+        originals.append((receipt, data, hashlib.sha256(data).hexdigest()))
+    encoded = lambda value: json.dumps(value, ensure_ascii=False, separators=(',', ':')).encode('utf-8')
+    batch = hashlib.sha256(encoded([[receipt['id'], checksum] for receipt, data, checksum in originals])).hexdigest()
+    directory = os.path.join(control, 'replay-index')
+    header = replay_manifest(directory) or {'version': 1, 'total': 0, 'buckets': {}}
+    runtime_private_directory(directory)
+    runtime_private_directory(os.path.join(directory, 'objects'))
+    manifest_path = os.path.join(directory, 'manifest.json')
+    if not os.path.lexists(manifest_path): publish_runtime_file(manifest_path, encoded(header))
+    archive_root = os.path.join(control, 'receipt-archives')
+    archive = os.path.join(archive_root, batch, 'receipts')
+    for path in [archive_root, os.path.dirname(archive), archive]: runtime_private_directory(path)
+    additions: Dict[str, Dict[str, Any]] = {}
+    for receipt, data, checksum in originals:
+        publish_runtime_file(os.path.join(archive, receipt['id'] + '.json'), data)
+        pointer = {'id': receipt['id'], 'archive': batch, 'sha256': checksum, 'kind': 'receipt'}
+        keys: List[List[Any]] = [['operation', receipt['id']]]
+        if receipt.get('tool_call_id') is not None:
+            endpoint = receipt['endpoint']
+            keys.append(['call', endpoint['host'], endpoint['user'], endpoint['port'], receipt['owner_id'], receipt['tool_call_id']])
+        for parts in keys:
+            key = replay_key(parts)
+            prefix = key[:3]
+            if prefix not in additions:
+                additions[prefix] = replay_bucket(directory, prefix, header['buckets'][prefix]) if prefix in header['buckets'] else {}
+            previous = additions[prefix].get(key)
+            if previous is not None and (previous['id'] != pointer['id'] or previous['sha256'] != checksum or previous['kind'] != 'receipt'):
+                raise ValueError('Conflicting original runtime archive linkage; preserve active receipts')
+            if previous is None: additions[prefix][key] = pointer
+    for prefix, entries in additions.items():
+        data = encoded({'version': 1, 'entries': entries})
+        if len(entries) > 4096 or len(data) > 2097152:
+            raise ValueError('Replay bucket is full; existing protection cannot be discarded')
+        header['total'] += len(entries) - header['buckets'].get(prefix, {}).get('count', 0)
+        checksum = hashlib.sha256(data).hexdigest()
+        publish_runtime_file(os.path.join(directory, 'objects', checksum + '.json'), data)
+        header['buckets'][prefix] = {'sha256': checksum, 'count': len(entries)}
+    data = encoded(header)
+    if header['total'] > 1000000 or len(data) > 1048576:
+        raise ValueError('Runtime replay index exceeds its bounded key budget')
+    publish_runtime_file(manifest_path, data, replace=True)
+    for receipt, data, checksum in originals:
+        path = os.path.join(receipts, receipt['id'] + '.json')
+        if read_archive_bytes(path, 1048576) != data: raise ValueError('Active runtime receipt changed before retirement')
+        os.unlink(path)
+    sync_directory(receipts)
+
+def main(q: Dict[str, Any]) -> Dict[str, Any]:
+    global admitted
+    root = os.path.realpath(q['root'])
+    if not os.path.isabs(q['root']) or not os.path.isdir(root):
+        raise ValueError('Resource root must be an existing absolute directory')
+    owner = q['owner_id']
+    if not isinstance(owner, str) or not owner or len(owner) > 200:
+        raise ValueError('Invalid immutable owner ID')
+    control = os.path.realpath(os.path.expanduser('~/.ztc/resource-leases'))
+    os.makedirs(control, mode=0o700, exist_ok=True)
+    state_path = os.path.join(control, 'leases.json')
+    client_journal = q.get('client_journal')
+    if client_journal is not None and (not isinstance(client_journal, str) or not os.path.isabs(client_journal)):
+        raise ValueError('Invalid host-bound client journal')
+    staging = q.get('host_delete_staging', os.path.join(control, 'deletion-staging'))
+    if not isinstance(staging, str) or not os.path.isabs(staging) or os.path.normpath(staging) != staging:
+        raise ValueError('Invalid host-bound deletion staging directory')
+    write_staging = q.get('host_write_staging', staging)
+    if not isinstance(write_staging, str) or not os.path.isabs(write_staging) or os.path.normpath(write_staging) != write_staging:
+        raise ValueError('Invalid host-bound write staging directory')
+    staging_bindings: Dict[str, Any] = {staging: q.get('host_delete_staging_identity')}
+    host_staging_bindings = q.get('host_write_staging_directories')
+    if host_staging_bindings is not None:
+        if not isinstance(host_staging_bindings, dict) or len(host_staging_bindings) > 201:
+            raise ValueError('Invalid host-bound write staging inventory')
+        for stage_path, stage_identity in host_staging_bindings.items():
+            if (not isinstance(stage_path, str) or not os.path.isabs(stage_path) or os.path.normpath(stage_path) != stage_path
+                or not isinstance(stage_identity, list) or len(stage_identity) != 2
+                or any(type(item) is not int or item < 0 for item in stage_identity)):
+                raise ValueError('Invalid host-bound write staging identity')
+        if (staging not in host_staging_bindings or write_staging not in host_staging_bindings
+            or host_staging_bindings[staging] != q.get('host_delete_staging_identity')
+            or host_staging_bindings[write_staging] != q.get('host_write_staging_identity')):
+            raise ValueError('Host write staging selection lacks its pinned identity')
+        staging_bindings.update(host_staging_bindings)
+    elif write_staging != staging:
+        raise ValueError('Configured write staging requires a pinned host inventory')
+    protected = [control, *staging_bindings] + ([os.path.realpath(client_journal + suffix)
+        for suffix in ['', '.archives', '.replay', '.replay-required.json', '.admission-lock', '.maintenance.json']] if client_journal else [])
+    def protected_target(target: str) -> bool:
+        return any(os.path.commonpath([path, target]) in [path, target] for path in protected)
+    key = hashlib.sha256(root.encode()).hexdigest()
+    def identity(path: str) -> List[int]:
+        s = os.stat(path)
+        return [s.st_dev, s.st_ino]
+    def ancestors(path: str) -> List[List[int]]:
+        result = []
+        while True:
+            result.append(identity(path))
+            parent = os.path.dirname(path)
+            if parent == path: return result
+            path = parent
+    root_id, root_ancestors = identity(root), ancestors(root)
+    if q.get('host_root_identity') is not None and q['host_root_identity'] != root_id:
+        raise ValueError('Host broker resource identity changed')
+    host_region: Optional[Dict[str, Any]] = q.get('host_filesystem_region')
+    mountinfo_sha256 = q.get('host_mountinfo_sha256')
+    def valid_region(value: Any) -> bool:
+        return (isinstance(value, dict) and set(value) == {'version', 'device', 'path'}
+            and type(value['version']) is int and value['version'] == 1
+            and isinstance(value['device'], str) and re.fullmatch(r'[0-9]+:[0-9]+', value['device']) is not None
+            and isinstance(value['path'], str) and len(value['path']) <= 4096 and '\x00' not in value['path']
+            and os.path.isabs(value['path']) and os.path.normpath(value['path']) == value['path'])
+    def proven_region(record: Dict[str, Any]) -> bool:
+        return (record.get('mountinfo_sha256') == mountinfo_sha256
+            and valid_region(record.get('filesystem_region')))
+    def overlaps(record: Dict[str, Any]) -> bool:
+        if host_region is not None:
+            # Missing or stale evidence cannot establish that two roots are disjoint.
+            if not proven_region(record): return True
+            other = record['filesystem_region']
+            if (other['device'] == host_region['device']
+                and os.path.commonpath([other['path'], host_region['path']]) in [other['path'], host_region['path']]):
+                return True
+        return record['identity'] in root_ancestors or root_id in record['ancestors']
+    with open(os.path.join(control, 'lock'), 'a') as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        # Operator cutover leaves the old authority frozen across restarts.
+        # Any entry (including damaged evidence) requires explicit recovery;
+        # a request cannot supply an override or silently clear this fence.
+        if os.path.lexists(os.path.join(control, 'cutover-fence.json')):
+            raise ValueError('Resource cutover authority is frozen for operator review')
+        if os.path.lexists(os.path.join(control, 'journal-maintenance.json')):
+            raise ValueError('Resource journal maintenance is frozen; inspect and resume the confirmed archive')
+        replay_directory = os.path.join(control, 'replay-index')
+        replay_required = q.get('host_receipt_archive_index') is True or os.path.lexists(os.path.join(control, 'receipt-archives'))
+        if q['operation'] in ['claim', 'transfer', 'stop', 'write', 'delete', 'ack', 'resolve']:
+            replay_manifest(replay_directory, replay_required)
+        if q['operation'] in ['write', 'delete']:
+            retired_id = q.get('operation_id')
+            pointer = replay_lookup(replay_directory, ['operation', retired_id], replay_required)
+            call = q.get('tool_call_id')
+            if pointer is None and q['operation'] in ['write', 'delete'] and call is not None:
+                endpoint = q['endpoint']
+                pointer = replay_lookup(replay_directory, ['call', endpoint['host'], endpoint['user'], endpoint['port'], owner, call], replay_required)
+            if pointer is not None:
+                raise ValueError('Operation archived as ' + pointer['id'] + '; inspect original evidence instead of replaying')
+        # Settle an earlier unacknowledged rename before using its lease. Sync
+        # every actual ancestor so newly created control paths (including a
+        # previous interrupted initialization) survive directory-entry loss.
+        control_ancestor = control
+        while True:
+            sync_directory(control_ancestor)
+            parent_directory = os.path.dirname(control_ancestor)
+            if parent_directory == control_ancestor: break
+            control_ancestor = parent_directory
+        if host_region is not None or mountinfo_sha256 is not None:
+            if (not valid_region(host_region) or not isinstance(mountinfo_sha256, str)
+                or re.fullmatch(r'[a-f0-9]{64}', mountinfo_sha256) is None):
+                raise ValueError('Invalid host mount evidence')
+            host_roots = q.get('host_resource_roots')
+            if not isinstance(host_roots, dict) or q['root'] not in host_roots:
+                raise ValueError('Invalid host resource root evidence')
+            if root != q['root'] or root_id != host_roots[q['root']]:
+                raise ValueError('Host broker resource canonical path or identity changed before locking')
+            # Check every configured root: moving another owner's root can
+            # change overlap even when the requested root itself is unchanged.
+            for configured_root, configured_identity in host_roots.items():
+                if (not isinstance(configured_root, str) or not os.path.isabs(configured_root)
+                    or os.path.realpath(configured_root) != configured_root
+                    or not os.path.isdir(configured_root) or identity(configured_root) != configured_identity):
+                    raise ValueError('Host broker resource canonical path or identity changed')
+            with open('/proc/self/mountinfo', 'rb') as mount_stream:
+                mount_snapshot = mount_stream.read(8 * 1024 * 1024 + 1)
+            if (len(mount_snapshot) > 8 * 1024 * 1024
+                or hashlib.sha256(mount_snapshot).hexdigest() != mountinfo_sha256):
+                raise ValueError('Host mount topology changed before lease admission')
+        records: Dict[str, Dict[str, Any]]
+        record: Optional[Dict[str, Any]]
+        try:
+            with open(state_path) as lease_stream: records = json.load(lease_stream)
+        except FileNotFoundError: records = {}
+        if not isinstance(records, dict): raise ValueError('Invalid resource lease registry')
+        for record in records.values():
+            if (not isinstance(record, dict) or not isinstance(record.get('generation'), int)
+                or not isinstance(record.get('expires_at'), (int, float))
+                or not math.isfinite(record['expires_at']) or not isinstance(record.get('root'), str)
+                or not isinstance(record.get('identity'), list) or not isinstance(record.get('ancestors'), list)
+                or record.get('owner_id') is not None and not isinstance(record['owner_id'], str)):
+                raise ValueError('Invalid resource lease registry')
+        now = time.time()
+        presence = register_owner_presence(control, owner, now)
+        owners = presence.pop('recent_owners')
+        record = records.get(key)
+        if record is not None and record['identity'] != root_id:
+            raise ValueError('Resource identity changed; configure and confirm the replacement resource')
+        op = q['operation']
+        def active(record: Dict[str, Any]) -> bool:
+            return bool(record['owner_id'] is not None and record['expires_at'] > now)
+        conflicts = [r for r in records.values() if overlaps(r) and active(r) and r['owner_id'] != owner]
+        status = {'root': root, 'owner_id': record['owner_id'] if record and active(record) else None,
+            'generation': record['generation'] if record else 0,
+            'expires_at': record['expires_at'] if record else None,
+            'authorized': bool(record and active(record) and record['owner_id'] == owner and not conflicts),
+            'conflicts': [{'root': r['root'], 'owner_id': r['owner_id']} for r in conflicts],
+            'owner_presence': presence}
+        receipts = os.path.join(control, 'receipts')
+        def persist_receipt(receipt: Dict[str, Any]) -> None:
+            os.makedirs(receipts, mode=0o700, exist_ok=True)
+            directory = os.open(control, os.O_RDONLY | os.O_DIRECTORY)
+            try: os.fsync(directory)
+            finally: os.close(directory)
+            fd, temporary = tempfile.mkstemp(dir=receipts)
+            try:
+                with os.fdopen(fd, 'w') as f:
+                    json.dump(receipt, f); f.flush(); os.fsync(f.fileno())
+                os.replace(temporary, os.path.join(receipts, receipt['id'] + '.json'))
+                directory = os.open(receipts, os.O_RDONLY | os.O_DIRECTORY)
+                try: os.fsync(directory)
+                finally: os.close(directory)
+            finally:
+                with contextlib.suppress(FileNotFoundError): os.unlink(temporary)
+        def journal() -> List[Dict[str, Any]]:
+            try: names = os.listdir(receipts)
+            except FileNotFoundError: return []
+            if len(names) > 10000: raise ValueError('Receipt journal is full; confirmed maintenance is required')
+            result = []
+            for name in names:
+                if not name.endswith('.json') or str(uuid.UUID(name[:-5])) != name[:-5]:
+                    raise ValueError('Invalid receipt journal entry; recovery is required')
+                with open(os.path.join(receipts, name)) as f: receipt = json.load(f)
+                if (receipt.get('version') != 1 or receipt.get('id') + '.json' != name
+                    or receipt.get('operation') not in ['delete', 'write']
+                    or not isinstance(receipt.get('target'), dict) or not isinstance(receipt['target'].get('path'), str)
+                    or not os.path.isabs(receipt['target']['path'])
+                    or receipt.get('status') not in ['pending', 'verified', 'failed', 'unverified', 'dry_run', 'cancelled']
+                    or 'admission_resolved' in receipt and not isinstance(receipt['admission_resolved'], bool)):
+                    raise ValueError('Invalid receipt journal record; recovery is required')
+                result.append(receipt)
+            return result
+        def inspect_staging(receipt: Dict[str, Any], sample: bool = False,
+            operation: str = 'deletion', leaf: str = 'target') -> Optional[Dict[str, Any]]:
+            stage = receipt.get(operation + '_staging')
+            if stage is None: return None
+            receipt_id = receipt['id']
+            path_key = 'payload_path' if leaf == 'payload' else 'path'
+            if not isinstance(stage, dict) or not isinstance(stage.get('directory_identity'), list):
+                raise ValueError('Invalid ' + operation + ' staging receipt; operator recovery is required')
+            stage_choices = [path for path in (staging_bindings if operation == 'write' else [staging])
+                if stage.get(path_key) == os.path.join(path, receipt_id, leaf)]
+            if len(stage_choices) != 1:
+                raise ValueError('Invalid ' + operation + ' staging receipt; operator recovery is required')
+            receipt_staging = stage_choices[0]
+            expected_staging_identity = staging_bindings[receipt_staging]
+            retained: Dict[str, Any] = {'path': stage[path_key], 'recorded_state': stage['state'], 'exists': False}
+            with contextlib.ExitStack() as stage_handles:
+                stage_root = os.open(receipt_staging, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+                stage_handles.callback(os.close, stage_root)
+                private = os.fstat(stage_root)
+                if (private.st_uid != os.geteuid() or private.st_mode & 0o077
+                    or expected_staging_identity is not None
+                    and expected_staging_identity != [private.st_dev, private.st_ino]):
+                    raise ValueError('Host ' + operation + ' staging changed during reconciliation')
+                try:
+                    stage_directory = os.open(receipt_id, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=stage_root)
+                    stage_handles.callback(os.close, stage_directory)
+                    private_operation = os.fstat(stage_directory)
+                    if ([private_operation.st_dev, private_operation.st_ino] != stage['directory_identity']
+                        or private_operation.st_uid != os.geteuid() or private_operation.st_mode & 0o077):
+                        raise ValueError(operation.capitalize() + ' staging operation identity changed')
+                    info = os.stat(leaf, dir_fd=stage_directory, follow_symlinks=False)
+                    retained.update(exists=True, device=info.st_dev, inode=info.st_ino,
+                        mode=info.st_mode, size=info.st_size, mtime_ns=info.st_mtime_ns, ctime_ns=info.st_ctime_ns)
+                    if sample and stat.S_ISREG(info.st_mode):
+                        fd = os.open(leaf, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=stage_directory)
+                        with os.fdopen(fd, 'rb') as retained_stream:
+                            opened = os.fstat(retained_stream.fileno())
+                            if [opened.st_dev, opened.st_ino] != [info.st_dev, info.st_ino]:
+                                raise ValueError('Retained ' + operation + ' target changed during reconciliation')
+                            retained['sample_sha256'] = hashlib.sha256(retained_stream.read(1048576)).hexdigest()
+                    elif stat.S_ISLNK(info.st_mode):
+                        retained['link_target'] = os.readlink(leaf, dir_fd=stage_directory)
+                except FileNotFoundError: pass
+            return retained
+        def retain_receipts(entries: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+            if len(entries) < 512: return entries
+            selected = []
+            for receipt in sorted(entries, key=lambda value: (value.get('completed_at') or 0, value['id'])):
+                if len(selected) >= 64: break
+                if receipt.get('admission_resolved') is not True or receipt['status'] not in ['verified', 'failed', 'dry_run', 'cancelled']:
+                    continue
+                verification = receipt.get('verification')
+                if receipt['status'] == 'verified' and (not isinstance(verification, dict)
+                    or verification.get('target_matches') is not True and verification.get('target_absent') is not True):
+                    continue
+                resolution = receipt.get('resolution')
+                if receipt['status'] == 'cancelled' and (not isinstance(resolution, dict) or resolution.get('decision') != 'accept_current_state'):
+                    continue
+                if any(retained is not None and retained['exists'] for retained in [
+                    inspect_staging(receipt), inspect_staging(receipt, operation='write'),
+                    inspect_staging(receipt, operation='write', leaf='payload')]):
+                    continue
+                selected.append(receipt)
+            retain_terminal_receipts(control, selected)
+            selected_ids = {receipt['id'] for receipt in selected}
+            return [receipt for receipt in entries if receipt['id'] not in selected_ids]
+        if op == 'status':
+            try:
+                pending = [r for r in journal() if not r.get('admission_resolved', r['status'] in ['verified', 'failed', 'dry_run'])
+                    and (r['target']['path'] == root or r['target']['path'].startswith(root + os.sep) or root.startswith(r['target']['path'] + os.sep))]
+                status['unresolved_operations'] = [{'id': r['id'], 'operation': r['operation'], 'status': r['status'],
+                    'target': r['target']['path'], 'owner_id': r['owner_id']} for r in pending[:100]]
+                status['unresolved_operation_count'] = len(pending)
+            except (ValueError, OSError, TypeError, KeyError) as error:
+                status['mutation_journal_error'] = str(error)[:2000]
+            return status
+        def save() -> None:
+            global admitted
+            fd, path = tempfile.mkstemp(dir=control)
+            try:
+                with os.fdopen(fd, 'w') as f:
+                    json.dump(records, f); f.flush(); os.fsync(f.fileno())
+                # Replacement can take effect even when its response is lost.
+                # Never describe a post-dispatch publication error as refusal.
+                admitted = True
+                os.replace(path, state_path)
+                sync_directory(control)
+            except OSError as error:
+                if admitted:
+                    raise RuntimeError('Lease publication outcome is unresolved; inspect current owner and generation before retrying: ' + str(error)) from error
+                raise
+            finally:
+                with contextlib.suppress(FileNotFoundError): os.unlink(path)
+        if op in ['claim', 'transfer', 'stop']:
+            expected = q['expected_generation']
+            if not isinstance(expected, int) or isinstance(expected, bool) or expected != status['generation']:
+                raise ValueError('Lease changed; inspect current owner and retry the confirmed action')
+            own_active_record = bool(record and active(record) and record['owner_id'] == owner)
+            if (op == 'stop' and not own_active_record) or (op == 'transfer' and not status['authorized']):
+                raise ValueError('Only the recorded current owner may stop or transfer this lease')
+            if op == 'claim' and conflicts:
+                if host_region is not None and any(not proven_region(other) for other in conflicts):
+                    raise ValueError('Resource overlap requires recovery: confirmed owners must stop or renew unproven leases')
+                raise ValueError('Resource is owned by another agent: ' + json.dumps(status['conflicts']))
+            ttl = q.get('ttl_seconds', 900)
+            if not isinstance(ttl, int) or isinstance(ttl, bool) or ttl < 1 or ttl > 3600:
+                raise ValueError('Lease duration must be 1 to 3600 seconds')
+            target = q.get('target_owner_id') if op == 'transfer' else owner
+            if op == 'transfer' and (not isinstance(target, str) or not target or len(target) > 200 or target == owner):
+                raise ValueError('Transfer requires a different host-assigned owner label')
+            if op == 'transfer' and target not in owners:
+                raise ValueError('Target owner must be registered by its own recent host broker request; inspect status in the target pane')
+            if op == 'transfer' and any(other is not record and active(other) and overlaps(other) and other['owner_id'] != target for other in records.values()):
+                raise ValueError('Stop overlapping leases before transferring this resource')
+            records[key] = {'root': root, 'identity': root_id, 'ancestors': root_ancestors,
+                'owner_id': None if op == 'stop' else target, 'expires_at': 0 if op == 'stop' else now + ttl,
+                'generation': status['generation'] + 1,
+                'filesystem_region': host_region, 'mountinfo_sha256': mountinfo_sha256}
+            save()
+            return records[key]
+        if record is None or not status['authorized']:
+            raise ValueError('Resource lease required; current owner: ' + str(status['owner_id']) + '; conflicts: ' + json.dumps(status['conflicts']))
+        if op in ['receipt', 'ack', 'reconcile', 'resolve']:
+            receipt_id = q.get('receipt_id')
+            if not isinstance(receipt_id, str): raise ValueError('Receipt ID must be a canonical operation UUID')
+            try: parsed_id = str(uuid.UUID(receipt_id))
+            except ValueError: raise ValueError('Receipt ID must be a canonical operation UUID')
+            if parsed_id != receipt_id: raise ValueError('Receipt ID must be a canonical operation UUID')
+            receipt_archive: Optional[Dict[str, Any]] = None
+            try:
+                with open(os.path.join(receipts, receipt_id + '.json')) as receipt_stream: receipt = json.load(receipt_stream)
+            except FileNotFoundError:
+                pointer = replay_lookup(replay_directory, ['operation', receipt_id], replay_required)
+                if pointer is not None:
+                    receipt = archived_receipt(control, pointer)
+                    if receipt.get('admission_resolved') is not True:
+                        raise ValueError('Archived operation lacks its resolved admission; operator recovery required')
+                    receipt_archive = {'historical': True, 'digest': pointer['archive'], 'record_sha256': pointer['sha256']}
+                else:
+                    if op not in ['reconcile', 'resolve']: raise
+                    receipt = None
+            if receipt is not None and receipt['root_identity'] != root_id:
+                raise ValueError('Receipt does not belong to this physical resource')
+            if op in ['receipt', 'ack']:
+                if receipt['owner_id'] != owner or receipt['resource_id'] != q['resource_id']:
+                    raise ValueError('Receipt does not belong to this owner and resource')
+                if op == 'ack':
+                    if receipt['status'] not in ['verified', 'failed', 'dry_run']:
+                        raise ValueError('Unresolved outcome requires confirmed reconciliation')
+                    if receipt_archive is None:
+                        receipt['admission_resolved'] = True
+                        persist_receipt(receipt)
+                return {'receipt': receipt, **({'archive': receipt_archive} if receipt_archive is not None else {})}
+            path = receipt['requested_path'] if receipt else q.get('path')
+            if not isinstance(path, str) or not path or os.path.isabs(path) or '\x00' in path:
+                raise ValueError('Reconciliation requires the original relative target path')
+            target = os.path.normpath(os.path.join(root, path))
+            if target == root or os.path.commonpath([root, target]) != root or protected_target(target):
+                raise ValueError('Reconciliation target escapes the resource or its protected boundary')
+            # Inspect held, no-follow descriptors. Never probe through a substituted parent.
+            with contextlib.ExitStack() as handles:
+                parent = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+                handles.callback(os.close, parent)
+                parts = os.path.relpath(target, root).split(os.sep)
+                if [os.fstat(parent).st_dev, os.fstat(parent).st_ino] != root_id:
+                    raise ValueError('Resource identity changed during reconciliation')
+                try:
+                    for part in parts[:-1]:
+                        parent = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent)
+                        handles.callback(os.close, parent)
+                    info = os.stat(parts[-1], dir_fd=parent, follow_symlinks=False)
+                    current: Dict[str, Any] = {'exists': True, 'device': info.st_dev, 'inode': info.st_ino,
+                        'mode': info.st_mode, 'size': info.st_size, 'mtime_ns': info.st_mtime_ns, 'ctime_ns': info.st_ctime_ns}
+                    if stat.S_ISREG(info.st_mode):
+                        fd = os.open(parts[-1], os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent)
+                        with os.fdopen(fd, 'rb') as reconciliation_stream:
+                            observed = os.fstat(reconciliation_stream.fileno())
+                            if [observed.st_dev, observed.st_ino] != [info.st_dev, info.st_ino]:
+                                raise ValueError('Target changed during reconciliation')
+                            current['sample_sha256'] = hashlib.sha256(reconciliation_stream.read(1048576)).hexdigest()
+                except FileNotFoundError: current = {'exists': False}
+            observation = {'receipt_id': receipt_id, 'receipt_status': receipt['status'] if receipt else 'not_recorded',
+                'admission_resolved': receipt.get('admission_resolved', False) if receipt else False,
+                'root_identity': root_id, 'target': target, 'current_target': current, 'generation': record['generation']}
+            retained = inspect_staging(receipt, sample=True) if receipt is not None else None
+            if retained is not None: observation['current_staging'] = retained
+            if receipt is not None and 'write_staging' in receipt:
+                observation['current_write_staging'] = {
+                    name: inspect_staging(receipt, sample=True, operation='write', leaf=name)
+                    for name in ['target', 'payload']}
+            token = hashlib.sha256(json.dumps(observation, sort_keys=True).encode()).hexdigest()
+            if op == 'resolve':
+                if q.get('observation_token') != token:
+                    raise ValueError('Reconciliation changed; inspect the current receipt and target before confirming')
+                if receipt_archive is not None:
+                    return {'receipt': receipt, 'archive': receipt_archive, 'observation': observation,
+                        'observation_token': token, 'decision_required': False, 'decision': 'accept_current_state'}
+                if receipt is None:
+                    if len(journal()) >= 10000: raise ValueError('Receipt journal is full; confirmed maintenance is required')
+                    original_operation = q.get('original_operation')
+                    if original_operation not in ['delete', 'write']: raise ValueError('Original mutation is required for cancellation')
+                    original_owner = q.get('original_owner_id', owner)
+                    original_call = q.get('original_tool_call_id')
+                    if not isinstance(original_owner, str) or not original_owner or len(original_owner) > 200:
+                        raise ValueError('Invalid original mutation owner')
+                    if original_call is not None and (not isinstance(original_call, str) or not original_call or len(original_call) > 200):
+                        raise ValueError('Invalid original mutation call')
+                    # A durable tombstone denies a delayed request with this ID, even if it never arrived before inspection.
+                    receipt = {'version': 1, 'id': receipt_id, 'status': 'cancelled', 'operation': original_operation,
+                        'owner_id': original_owner, 'tool_call_id': original_call, 'resource_id': q['resource_id'], 'root_identity': root_id,
+                        'configured_root': q['root'], 'root': root, 'requested_path': path,
+                        'target': {'path': target}, 'endpoint': q['endpoint']}
+                receipt['admission_resolved'] = True
+                receipt['resolution'] = {'decision': 'accept_current_state', 'confirmed_by': owner,
+                    'confirmed_at': time.time(), 'observation': observation, 'observation_token': token}
+                persist_receipt(receipt)
+            return {'receipt': receipt, 'observation': observation, 'observation_token': token,
+                'decision_required': op == 'reconcile', 'decision': 'accept_current_state' if op == 'resolve' else None}
+        if op not in ['read', 'list', 'stat', 'write', 'delete']:
+            raise ValueError('Unsupported managed resource operation')
+        path = q.get('path', '.')
+        if not isinstance(path, str) or not path or os.path.isabs(path) or '\x00' in path:
+            raise ValueError('Resource path must be relative to the configured root')
+        target = os.path.realpath(os.path.join(root, path))
+        if os.path.commonpath([root, target]) != root:
+            raise ValueError('Resource path escapes the configured root')
+        if protected_target(target):
+            raise ValueError('Resource lease control files are protected')
+        if op in ['write', 'delete'] and target == root:
+            raise ValueError('Cannot mutate the resource root itself')
+        dry = q.get('dry_run', False)
+        if not isinstance(dry, bool): raise ValueError('dry_run must be a boolean')
+        if dry and op != 'delete': return dict(status, path=target, operation=op, dry_run=True)
+        # The lease lock spans verification and the complete filesystem action.
+        # Transfers and overlapping operations cannot cross this boundary.
+        # Walk held directory descriptors without following links. A path swap
+        # after validation cannot redirect the filesystem operation outside its
+        # verified root, even if another process renames a parent directory.
+        with contextlib.ExitStack() as handles:
+            def held(fd: int) -> int:
+                handles.callback(os.close, fd)
+                return fd
+            flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+            parent = held(os.open(root, flags))
+            s = os.fstat(parent)
+            if [s.st_dev, s.st_ino] != root_id: raise ValueError('Resource identity changed during execution')
+            parts = os.path.relpath(target, root).split(os.sep)
+            namespaces = []
+            directory_ids = [root_id]
+            for part in parts[:-1]:
+                info = os.fstat(parent)
+                namespaces.append({'parent': [info.st_dev, info.st_ino], 'leaf': part})
+                parent = held(os.open(part, flags, dir_fd=parent))
+                info = os.fstat(parent)
+                directory_ids.append([info.st_dev, info.st_ino])
+            leaf = parts[-1]
+            info = os.fstat(parent)
+            namespace = {'parent': [info.st_dev, info.st_ino], 'leaf': leaf}
+            namespaces.append(namespace)
+            if op == 'list':
+                directory = held(os.open(leaf, flags, dir_fd=parent))
+                return {'path': target, 'entries': sorted(os.listdir(directory))[:1000]}
+            if op == 'stat':
+                s = os.stat(leaf, dir_fd=parent, follow_symlinks=False)
+                if stat.S_ISLNK(s.st_mode): raise ValueError('Resource target changed to a symbolic link')
+                return {'path': target, 'size': s.st_size, 'directory': stat.S_ISDIR(s.st_mode)}
+            if op == 'read':
+                with os.fdopen(os.open(leaf, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent), 'rb') as read_stream:
+                    if not stat.S_ISREG(os.fstat(read_stream.fileno()).st_mode): raise ValueError('Read requires a regular file')
+                    data = read_stream.read(1048577)
+                if len(data) > 1048576: raise ValueError('Read exceeds 1 MiB; narrow the resource file')
+                return {'path': target, 'content': data.decode('utf-8')}
+            # The shared lease lock admits a durable operation before any effect.
+            entries = retain_receipts(journal())
+            unresolved_physical: Dict[tuple[int, int], str] = {}
+            if not dry:
+                for previous in entries:
+                    resolved = previous.get('admission_resolved', previous['status'] in ['verified', 'failed', 'dry_run'])
+                    affected = previous['target']['path']
+                    physical = previous['target']
+                    try:
+                        info = os.stat(leaf, dir_fd=parent, follow_symlinks=False)
+                        current_identity = [info.st_dev, info.st_ino]
+                    except FileNotFoundError: current_identity = None
+                    same_physical = current_identity == [physical.get('device'), physical.get('inode')]
+                    same_captured = False
+                    captured_directory = False
+                    if not resolved:
+                        physical_ids = [[physical.get('device'), physical.get('inode')]]
+                        for operation in ['deletion', 'write']:
+                            captured_record = previous.get(operation + '_staging', {})
+                            physical_ids.extend([captured_record.get('intended_identity'), captured_record.get('captured_identity')])
+                            captured_directory = captured_directory or (captured_record.get('captured_identity') in directory_ids
+                                and stat.S_ISDIR(captured_record.get('captured_mode', 0)))
+                            for name in (['target', 'payload'] if operation == 'write' else ['target']):
+                                retained = inspect_staging(previous, operation=operation, leaf=name)
+                                if retained is not None and retained['exists']:
+                                    retained_identity = [retained['device'], retained['inode']]
+                                    physical_ids.append(retained_identity)
+                                    captured_directory = captured_directory or (retained_identity in directory_ids and stat.S_ISDIR(retained['mode']))
+                        same_captured = current_identity is not None and current_identity in physical_ids
+                        for physical_id in physical_ids:
+                            if (isinstance(physical_id, list) and len(physical_id) == 2
+                                and all(isinstance(value, int) and not isinstance(value, bool) for value in physical_id)):
+                                unresolved_physical[(physical_id[0], physical_id[1])] = previous['id']
+                    same_namespace = physical.get('namespace') in namespaces
+                    within_directory = physical.get('kind') == 'directory' and [physical.get('device'), physical.get('inode')] in directory_ids
+                    # Older receipts still identify a relative pathname under the same physical root.
+                    relative_alias = False
+                    if previous['root_identity'] == root_id:
+                        prior_relative = os.path.relpath(affected, previous['root'])
+                        current_relative = os.path.relpath(target, root)
+                        relative_alias = (current_relative == prior_relative or current_relative.startswith(prior_relative + os.sep)
+                            or prior_relative.startswith(current_relative + os.sep))
+                    if not resolved and (same_physical or same_captured or captured_directory or same_namespace or within_directory or relative_alias
+                        or target == affected or target.startswith(affected + os.sep) or affected.startswith(target + os.sep)):
+                        raise ValueError('Remote mutation fenced by unresolved operation ' + previous['id'] + '; reconcile through /resources')
+            content = q.get('content')
+            if op == 'write':
+                if not isinstance(content, str) or len(content.encode('utf-8')) > 1048576:
+                    raise ValueError('Write requires UTF-8 content of at most 1 MiB')
+                write_content = content
+            operation_id = q.get('operation_id')
+            if not isinstance(operation_id, str) or str(uuid.UUID(operation_id)) != operation_id:
+                raise ValueError('Mutation requires a host-generated operation UUID')
+            call_id = q.get('tool_call_id')
+            if call_id is not None and (not isinstance(call_id, str) or not call_id or len(call_id) > 200):
+                raise ValueError('Invalid originating tool call ID')
+            retired = replay_lookup(replay_directory, ['operation', operation_id], replay_required)
+            if retired is None and call_id is not None:
+                endpoint = q['endpoint']
+                retired = replay_lookup(replay_directory, ['call', endpoint['host'], endpoint['user'], endpoint['port'], owner, call_id], replay_required)
+            if retired is not None:
+                raise ValueError('Operation archived as ' + retired['id'] + '; inspect original evidence instead of replaying')
+            if any(previous['id'] == operation_id for previous in entries):
+                raise ValueError('Operation already recorded; inspect its receipt instead of replaying')
+            if call_id is not None and any(previous['owner_id'] == owner and previous.get('tool_call_id') == call_id for previous in entries):
+                raise ValueError('Tool call already recorded; inspect its receipt instead of replaying')
+            if len(entries) >= 10000: raise ValueError('Receipt journal is full; archive verified receipts before admitting new mutations')
+            intended_identity = None
+            if op == 'write':
+                try: existing = os.stat(leaf, dir_fd=parent, follow_symlinks=False)
+                except FileNotFoundError: existing = None
+                if existing is not None:
+                    if not stat.S_ISREG(existing.st_mode): raise ValueError('Write requires an absent target or a regular file')
+                    intended = held(os.open(leaf, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent))
+                    pinned = os.fstat(intended)
+                    intended_identity = [pinned.st_dev, pinned.st_ino]
+                    if intended_identity != [existing.st_dev, existing.st_ino]: raise ValueError('Write target changed during inspection')
+                    pending_id = unresolved_physical.get((pinned.st_dev, pinned.st_ino))
+                    if pending_id is not None:
+                        raise ValueError('Remote mutation fenced by unresolved operation ' + pending_id + '; reconcile through /resources')
+            receipt = {'version': 1, 'id': operation_id, 'status': 'pending', 'operation': op,
+                'admission_resolved': dry, 'tool_call_id': call_id, 'resource_id': q['resource_id'], 'owner_id': owner,
+                'generation': record['generation'], 'root': root, 'root_identity': root_id,
+                'configured_root': q['root'], 'requested_path': path, 'endpoint': q['endpoint'],
+                'target': {'path': target, 'device': None, 'inode': None, 'kind': None, 'namespace': namespace},
+                'removed_bytes': 0, 'started_at': time.time(), 'completed_at': None,
+                'verification': {'target_absent': None, 'checked_at': None},
+                'space': {'reclaimed_bytes': None, 'attribution': 'unknown', 'source': 'not measured', 'interval': None}}
+            persist_receipt(receipt)
+            admitted = True
+            if op == 'write':
+                write_parent: Optional[int] = None
+                write_directory: Optional[int] = None
+                stage_name = operation_id
+                try:
+                    os.makedirs(write_staging, mode=0o700, exist_ok=True)
+                    write_parent = held(os.open(write_staging, flags))
+                    private = os.fstat(write_parent)
+                    if (private.st_uid != os.geteuid() or private.st_mode & 0o077
+                        or private.st_dev != os.fstat(parent).st_dev
+                        or staging_bindings[write_staging] is not None
+                        and staging_bindings[write_staging] != [private.st_dev, private.st_ino]):
+                        raise ValueError('Write requires a private same-filesystem host staging directory')
+                    os.mkdir(stage_name, mode=0o700, dir_fd=write_parent)
+                    os.fsync(write_parent)
+                    write_directory = held(os.open(stage_name, flags, dir_fd=write_parent))
+                    private_operation = os.fstat(write_directory)
+                    receipt['write_staging'] = {'path': os.path.join(write_staging, stage_name, 'target'),
+                        'payload_path': os.path.join(write_staging, stage_name, 'payload'),
+                        'directory_identity': [private_operation.st_dev, private_operation.st_ino],
+                        'intended_identity': intended_identity, 'state': 'prepared'}
+                    # Persist both private names before creating or moving data.
+                    # A reconnect can inspect them even if a syscall never returns.
+                    persist_receipt(receipt)
+                    fd = held(os.open('payload', os.O_RDWR | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=write_directory))
+                    with os.fdopen(os.dup(fd), 'w') as write_stream:
+                        write_stream.write(write_content); write_stream.flush(); os.fsync(write_stream.fileno())
+                    info = os.fstat(fd)
+                    os.fsync(write_directory)
+                    receipt['target'].update(device=info.st_dev, inode=info.st_ino, kind='file')
+                    receipt['write_staging']['state'] = 'payload_ready'
+                    persist_receipt(receipt)
+                    if intended_identity is not None:
+                        rename_without_replacement(parent, leaf, write_directory, 'target')
+                        os.fsync(parent); os.fsync(write_directory)
+                        moved = os.stat('target', dir_fd=write_directory, follow_symlinks=False)
+                        receipt['write_staging'].update(state='captured', captured_identity=[moved.st_dev, moved.st_ino], captured_mode=moved.st_mode)
+                        persist_receipt(receipt)
+                        if [moved.st_dev, moved.st_ino] != intended_identity or not stat.S_ISREG(moved.st_mode):
+                            raise ValueError('Write target replaced before capture; replacement data preserved')
+                    # Both names are protected: a private source cannot be replaced
+                    # by managed writes, and the kernel refuses any public newcomer.
+                    try: rename_without_replacement(write_directory, 'payload', parent, leaf)
+                    except FileExistsError as error:
+                        raise ValueError('Write target changed before publication; replacement data preserved') from error
+                    os.fsync(parent); os.fsync(write_directory)
+                    receipt['write_staging']['state'] = 'published'
+                    persist_receipt(receipt)
+                    visible = os.stat(leaf, dir_fd=parent, follow_symlinks=False)
+                    same_parent = identity(os.path.dirname(target)) == [os.fstat(parent).st_dev, os.fstat(parent).st_ino]
+                    verified = (identity(root) == root_id and same_parent and stat.S_ISREG(visible.st_mode)
+                        and [visible.st_dev, visible.st_ino] == [info.st_dev, info.st_ino])
+                    if verified:
+                        if intended_identity is not None: os.unlink('target', dir_fd=write_directory)
+                        os.fsync(write_directory)
+                        receipt['write_staging']['state'] = 'completed'
+                    receipt['status'] = 'verified' if verified else 'unverified'
+                    receipt['written_bytes'] = len(write_content.encode('utf-8'))
+                    receipt['content_sha256'] = hashlib.sha256(write_content.encode('utf-8')).hexdigest()
+                    receipt['verification'] = {'target_matches': verified, 'checked_at': time.time()}
+                    receipt['completed_at'] = time.time()
+                    persist_receipt(receipt)
+                except Exception as error:
+                    if write_directory is not None and 'write_staging' in receipt:
+                        # Inspect the private name, not a post-syscall flag: the
+                        # capture or publication might have applied before raising.
+                        try:
+                            moved = os.stat('target', dir_fd=write_directory, follow_symlinks=False)
+                        except FileNotFoundError: pass
+                        else:
+                            receipt['write_staging'].update(captured_identity=[moved.st_dev, moved.st_ino], captured_mode=moved.st_mode)
+                            try:
+                                rename_without_replacement(write_directory, 'target', parent, leaf)
+                                os.fsync(parent); os.fsync(write_directory)
+                                receipt['write_staging']['state'] = 'restored'
+                            except Exception as restoration:
+                                receipt['write_staging']['restoration_error'] = str(restoration)[:2000]
+                    receipt['status'] = 'unverified' if 'write_staging' in receipt else 'failed'
+                    receipt['error'] = str(error)[:2000]
+                    receipt['completed_at'] = time.time()
+                    persist_receipt(receipt)
+                    raise
+                finally:
+                    if write_parent is not None and write_directory is not None:
+                        # Never purge retained data, including an unpublished payload.
+                        with contextlib.suppress(OSError):
+                            os.rmdir(stage_name, dir_fd=write_parent); os.fsync(write_parent)
+                return {'path': target, 'operation': 'write', 'written_bytes': receipt['written_bytes'],
+                    'generation': record['generation'], 'receipt': receipt}
+            removed = False
+            captured = False
+            deletion_parent: Optional[int] = None
+            deletion_directory: Optional[int] = None
+            stage_name = operation_id
+            def restore_captured() -> None:
+                # Even a replacement captured during the race is data: never
+                # discard it or overwrite a newer entry in the public directory.
+                if deletion_directory is None: raise RuntimeError('Missing private deletion capture')
+                rename_without_replacement(deletion_directory, 'target', parent, leaf)
+                os.fsync(parent); os.fsync(deletion_directory)
+                receipt['deletion_staging']['state'] = 'restored'
+            try:
+                s = os.stat(leaf, dir_fd=parent, follow_symlinks=False)
+                if stat.S_ISLNK(s.st_mode): raise ValueError('Deletion target changed to a symbolic link')
+                pending_id = unresolved_physical.get((s.st_dev, s.st_ino))
+                if not dry and pending_id is not None:
+                    raise ValueError('Remote mutation fenced by unresolved operation ' + pending_id + '; reconcile through /resources')
+                if not stat.S_ISDIR(s.st_mode) and not stat.S_ISREG(s.st_mode):
+                    raise ValueError('Deletion requires a regular file or empty directory')
+                # Keep the intended inode alive so its number cannot be reused
+                # while the public name is being captured.
+                intended = held(os.open(leaf, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent))
+                observed = os.fstat(intended)
+                if [observed.st_dev, observed.st_ino] != [s.st_dev, s.st_ino]:
+                    raise ValueError('Deletion target changed during inspection')
+                kind = 'directory' if stat.S_ISDIR(s.st_mode) else 'file'
+                receipt['target'].update(device=s.st_dev, inode=s.st_ino, kind=kind)
+                persist_receipt(receipt)
+                if not dry and kind == 'directory' and os.listdir(intended):
+                    raise OSError(errno.ENOTEMPTY, 'Deletion requires an empty directory')
+                if dry:
+                    receipt['status'] = 'dry_run'
+                else:
+                    os.makedirs(staging, mode=0o700, exist_ok=True)
+                    deletion_parent = held(os.open(staging, flags))
+                    private = os.fstat(deletion_parent)
+                    if (private.st_uid != os.geteuid() or private.st_mode & 0o077
+                        or private.st_dev != s.st_dev
+                        or q.get('host_delete_staging_identity') is not None
+                        and q['host_delete_staging_identity'] != [private.st_dev, private.st_ino]):
+                        raise ValueError('Deletion requires a private same-filesystem host staging directory')
+                    os.mkdir(stage_name, mode=0o700, dir_fd=deletion_parent)
+                    os.fsync(deletion_parent)
+                    deletion_directory = held(os.open(stage_name, flags, dir_fd=deletion_parent))
+                    private_operation = os.fstat(deletion_directory)
+                    receipt['deletion_staging'] = {'path': os.path.join(staging, stage_name, 'target'),
+                        'directory_identity': [private_operation.st_dev, private_operation.st_ino], 'state': 'prepared'}
+                    persist_receipt(receipt)
+                    rename_without_replacement(parent, leaf, deletion_directory, 'target')
+                    captured = True
+                    receipt['deletion_staging']['state'] = 'captured'
+                    os.fsync(parent); os.fsync(deletion_directory)
+                    moved = os.stat('target', dir_fd=deletion_directory, follow_symlinks=False)
+                    receipt['deletion_staging']['captured_identity'] = [moved.st_dev, moved.st_ino]
+                    receipt['deletion_staging']['captured_mode'] = moved.st_mode
+                    persist_receipt(receipt)
+                    if [moved.st_dev, moved.st_ino] != [s.st_dev, s.st_ino] or stat.S_IFMT(moved.st_mode) != stat.S_IFMT(s.st_mode):
+                        raise ValueError('Deletion target replaced before capture; replacement data preserved')
+                    if stat.S_ISDIR(moved.st_mode): os.rmdir('target', dir_fd=deletion_directory)
+                    else: os.unlink('target', dir_fd=deletion_directory)
+                    removed = True
+                    receipt['deletion_staging']['state'] = 'removed'
+                    receipt['removed_bytes'] = 0 if kind == 'directory' else moved.st_size
+                    os.fsync(deletion_directory)
+                    try:
+                        os.stat(leaf, dir_fd=parent, follow_symlinks=False)
+                        absent = False
+                    except FileNotFoundError: absent = True
+                    # A held descriptor prevents escaping the root. Completion
+                    # also requires that the named path still maps to that same
+                    # parent/root, and that no other process recreated the target.
+                    same_parent = identity(os.path.dirname(target)) == [os.fstat(parent).st_dev, os.fstat(parent).st_ino]
+                    same_root = identity(root) == root_id
+                    visible_absent = not os.path.lexists(target)
+                    verified = absent and same_parent and same_root and visible_absent
+                    receipt['verification'] = {'target_absent': verified, 'checked_at': time.time()}
+                    receipt['status'] = 'verified' if verified else 'unverified'
+                receipt['completed_at'] = time.time()
+                persist_receipt(receipt)
+            except Exception as error:
+                if captured and not removed:
+                    try: restore_captured()
+                    except Exception as restoration:
+                        receipt['deletion_staging']['restoration_error'] = str(restoration)[:2000]
+                receipt['status'] = 'unverified' if captured else 'failed'
+                receipt['error'] = str(error)[:2000]
+                receipt['completed_at'] = time.time()
+                # Failure to save after a mutation leaves the durable pending
+                # record. It never acknowledges deletion as verified.
+                persist_receipt(receipt)
+                raise
+            finally:
+                if deletion_parent is not None and deletion_directory is not None:
+                    # Only an empty operation directory is removable. Retained
+                    # data survives restart and is never automatically purged.
+                    with contextlib.suppress(OSError):
+                        os.rmdir(stage_name, dir_fd=deletion_parent); os.fsync(deletion_parent)
+            return {'path': target, 'operation': 'delete', 'removed_bytes': receipt['removed_bytes'],
+                'generation': record['generation'], 'dry_run': dry, 'receipt': receipt}
+
+
+if __name__ == '__main__':
+    try:
+        request = json.load(sys.stdin)
+        result = main(request)
+        print(json.dumps({'ok': True, 'result': result}))
+    except Exception as e:
+        print(json.dumps({'ok': False, 'error': str(e), 'admitted': admitted, 'operation_id': request.get('operation_id') if 'request' in globals() else None}))
+        sys.exit(1)