@topolo/cli 0.13.17 → 0.13.21

package/agent-packs/src/topolo_agent_pack/claude_runner.py

@@ -0,0 +1,207 @@
+"""Single-use supported Claude Code worker, without a terminal or saved history.
+
+The Desktop front doors remain separate. This adapter retires a process, not a
+Desktop chat, and never represents a CLI process exit as native chat archival.
+"""
+import asyncio
+import json
+import os
+import pathlib
+import shlex
+import signal
+import sys
+import uuid
+
+from .claude import find_binary
+from .storage import atomic_json, read_json, PackError
+from .work import require
+
+
+def public_progress(text):
+    if not text.strip() or '```' in text:
+        return False
+    try:
+        json.loads(text)
+    except ValueError:
+        return True
+    return False
+
+
+def hook(directory, event):
+    directory = pathlib.Path(directory)
+    gate = read_json(directory / 'gate.json')
+    require(event.get('session_id') == gate['sessionId'], 'Worker hook session differs')
+    kind = event.get('hook_event_name')
+    if kind == 'PreToolUse':
+        allowed = gate['phase'] == 'assigned' and gate.get('allowTools') is True and event.get('permission_mode') == 'bypassPermissions'
+        allowed = allowed and event.get('effort', {}).get('level') == gate['effort']
+        allowed = allowed and event.get('tool_name') not in {'Agent', 'Task', 'Skill', 'EnterWorktree', 'ExitWorktree'}
+        return {'hookSpecificOutput': {'hookEventName': kind,
+                'permissionDecision': 'allow' if allowed else 'deny',
+                'permissionDecisionReason': 'Topolo bounded worker phase and native effort gate'}}
+    require(kind in {'UserPromptSubmit', 'Stop'}, 'Unsupported worker hook')
+    with (directory / 'native-settings.jsonl').open('a') as stream:
+        stream.write(json.dumps({k: event.get(k) for k in
+                    ['session_id', 'prompt_id', 'hook_event_name', 'permission_mode', 'effort']}) + '\n')
+    return {}
+
+
+def hook_main(directory):
+    try:
+        raw = sys.stdin.read(100001)
+        require(len(raw) <= 100000, 'Worker hook input exceeds its boundary')
+        print(json.dumps(hook(directory, json.loads(raw))))
+        return 0
+    except Exception as exc:
+        print('Topolo worker gate refused: ' + str(exc), file=sys.stderr)
+        return 2
+
+
+class Session:
+    def __init__(self, cwd, worker_id, model, effort, progress=None):
+        require(str(uuid.UUID(worker_id)) == worker_id, 'Exact worker UUID required')
+        self.cwd = pathlib.Path(cwd)
+        self.id = worker_id
+        self.model = model
+        self.effort = effort
+        self.progress = progress
+        self.directory = self.cwd / '.topolo-worker'
+        self.directory.mkdir(mode=0o700)
+        self.process = None
+        self.pending = None
+        self.results = {}
+        self.init = None
+        self.closed = False
+        self.assigned = False
+        self.allow_tools = True
+        self.expected_email = None
+        self.auth_config_directory = None
+        self.tool_path = None
+
+    async def start(self):
+        binary = find_binary()
+        require(binary is not None, 'Signed-in Claude Code runtime is required')
+        gate = {'sessionId': self.id, 'model': self.model, 'effort': self.effort, 'phase': 'readiness'}
+        atomic_json(self.directory / 'gate.json', gate)
+        adapter = pathlib.Path(__file__).resolve().parents[2] / 'topolo-agent-pack'
+        require(adapter.is_file(), 'Installed bundled worker-hook entrypoint is unavailable')
+        command = shlex.join([sys.executable, str(adapter), 'work', 'claude-worker-hook',
+                             '--harness', 'claude', '--input', str(self.directory)]) + ' || exit 2'
+        settings = {'autoMemoryEnabled': False, 'hooks': {
+            event: [{'hooks': [{'type': 'command', 'command': command, 'timeout': 15}]}]
+            for event in ['UserPromptSubmit', 'Stop', 'PreToolUse']}}
+        atomic_json(self.directory / 'settings.json', settings)
+        env = dict(os.environ)
+        # Use the explicitly bound native profile's supported subscription login;
+        # never copy a token or silently select default-profile/API-key billing.
+        require(not any(env.get(k) for k in ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN',
+                    'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_BASE_URL']),
+                'Explicit provider or credential overrides are outside this subscription worker binding')
+        require(self.auth_config_directory is not None, 'An explicitly bound Claude authentication profile is required')
+        env['CLAUDE_CONFIG_DIR'] = self.auth_config_directory
+        env.pop('CLAUDECODE', None)
+        env['PYTHONPATH'] = str(pathlib.Path(__file__).resolve().parent.parent)
+        if self.tool_path is not None:
+            env['PATH'] = self.tool_path
+        auth = await asyncio.create_subprocess_exec(binary, 'auth', 'status', '--json', env=env,
+                stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL)
+        try:
+            stdout, _ = await asyncio.wait_for(auth.communicate(), 15)
+        finally:
+            if auth.returncode is None:
+                auth.kill()
+                await auth.wait()
+        account = json.loads(stdout)
+        require(auth.returncode == 0 and account.get('loggedIn') is True and account.get('authMethod') == 'claude.ai'
+                and self.expected_email is not None and account.get('email') == self.expected_email,
+                'The signed-in Claude subscription account differs from the installation')
+        stderr = (self.directory / 'stderr.log').open('wb')
+        try:
+            self.process = await asyncio.create_subprocess_exec(binary, '--print',
+                '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+                '--replay-user-messages', '--session-id', self.id, '--no-session-persistence',
+                '--model', self.model, '--effort', self.effort, '--permission-mode', 'bypassPermissions',
+                '--setting-sources', '', '--settings', str(self.directory / 'settings.json'),
+                '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}',
+                '--append-system-prompt-file', str(self.cwd / 'CLAUDE.md'), cwd=self.cwd, env=env,
+                stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, stderr=stderr,
+                limit=2 * 1024 * 1024, start_new_session=True)
+        finally:
+            stderr.close()
+        ready = 'TOPOLO_WORKER_READY:' + self.id
+        result = await self.exchange(self.id, 'Readiness only. Do not use tools or perform work. Reply exactly ' + ready)
+        require(result['output'].strip() == ready and result['toolItems'] == 0,
+                'The exact tool-free readiness probe did not complete')
+        proofs = [json.loads(line) for line in (self.directory / 'native-settings.jsonl').read_text().splitlines()]
+        require(any(p['hook_event_name'] == 'UserPromptSubmit' and p['permission_mode'] == 'bypassPermissions' for p in proofs)
+                and any(p['hook_event_name'] == 'Stop' and isinstance(p['effort'], dict)
+                        and p['effort'].get('level') == self.effort for p in proofs),
+                'Actual native permission and effort acknowledgement is unavailable')
+        return {'model': self.model, 'effort': self.effort, 'sessionId': self.id,
+                'processId': self.process.pid, 'boundary': 'native init, readiness result and Stop hook'}
+
+    async def assign(self, message_id, prompt):
+        require(not self.assigned and self.pending is None, 'This worker already has an assignment; reconcile without resend')
+        self.assigned = True
+        atomic_json(self.directory / 'gate.json', {'sessionId': self.id, 'model': self.model,
+                    'effort': self.effort, 'phase': 'assigned', 'allowTools': self.allow_tools})
+        return await self.exchange(message_id, prompt)
+
+    async def exchange(self, message_id, prompt):
+        require(self.process is not None and not self.closed and self.pending is None,
+                'Native worker is not ready for one exact input')
+        self.pending = message_id
+        # A create-only marker precedes stdin delivery. Lost acknowledgements
+        # retain the UUID; neither startup nor exchange retries it.
+        with (self.directory / (message_id + '.send.json')).open('x') as stream:
+            json.dump({'sessionId': self.id, 'messageId': message_id}, stream)
+            stream.flush()
+            os.fsync(stream.fileno())
+        value = {'type': 'user', 'session_id': self.id, 'uuid': message_id,
+                 'message': {'role': 'user', 'content': prompt}}
+        self.process.stdin.write((json.dumps(value) + '\n').encode())
+        await self.process.stdin.drain()
+        echoed = False
+        tools = 0
+        async with asyncio.timeout(1800):
+            while line := await self.process.stdout.readline():
+                row = json.loads(line)
+                require(row.get('session_id', self.id) == self.id, 'Native event belongs to another session')
+                if row.get('type') == 'system' and row.get('subtype') == 'init':
+                    require(self.init is None and row.get('model') == self.model
+                            and row.get('permissionMode') == 'bypassPermissions', 'Native worker startup tuple differs')
+                    self.init = row
+                if row.get('type') == 'user' and row.get('uuid') == message_id:
+                    require(not echoed, 'Native input acknowledgement is duplicated')
+                    echoed = True
+                if row.get('type') == 'assistant':
+                    content = row.get('message', {}).get('content', [])
+                    tools += sum(item.get('type') == 'tool_use' for item in content)
+                    if self.assigned and self.progress:
+                        text = '\n'.join(item['text'] for item in content if item.get('type') == 'text')
+                        if public_progress(text):
+                            await self.progress(row['uuid'], text[:1600])
+                if row.get('type') == 'result':
+                    require(self.init is not None and echoed and row.get('is_error') is False
+                            and row.get('subtype') == 'success' and row.get('terminal_reason') == 'completed'
+                            and row.get('stop_reason') == 'end_turn' and not row.get('permission_denials')
+                            and set(row.get('modelUsage', {})) == {self.model}
+                            and row.get('queued_turn_count', 0) == 0 and isinstance(row.get('result'), str),
+                            'Native worker did not prove a successful selected-model turn: ' + str(row.get('result', ''))[:300])
+                    receipt = {'id': message_id, 'status': 'completed', 'output': row['result'],
+                               'toolItems': tools, 'nativeSessionId': self.id, 'nativeResultId': row['uuid']}
+                    self.results[message_id] = receipt
+                    self.pending = None
+                    return receipt
+        raise PackError('Native worker ended without its exact terminal receipt; no resend')
+
+    async def close(self):
+        if self.process is not None and self.process.returncode is None:
+            self.process.stdin.close()
+            try:
+                await asyncio.wait_for(self.process.wait(), 8)
+            except TimeoutError:
+                os.killpg(self.process.pid, signal.SIGTERM)
+                await asyncio.wait_for(self.process.wait(), 8)
+        self.closed = True
+        return {'state': 'process-retired', 'sessionId': self.id, 'desktopChatArchived': False}

package/agent-packs/src/topolo_agent_pack/claude_service.py

@@ -0,0 +1,397 @@
+"""Owning Claude cloud-dispatch connection, using the existing GUI protocol."""
+import asyncio
+import fcntl
+import hashlib
+import json
+import os
+import pathlib
+import secrets
+import shlex
+import subprocess
+import sys
+import time
+
+from .claude_dispatch import ClaudeBroker
+from .live import request, socket_path
+from .storage import Library, PackError, atomic_json, canonical, read_json
+from .work import require
+
+
+def verify_retired_binding(lib, previous, connection):
+    """A new app process never inherits unresolved native worker custody."""
+    old = previous.get('nativeConnection', {})
+    require(isinstance(old, dict) and set(old) == {'pid', 'runtime', 'identity', 'socket', 'secretPath'}
+            and type(old['pid']) is int and old['pid'] > 1 and old['pid'] == previous.get('desktopPid')
+            and old['pid'] != connection['pid'] and old['runtime'] == connection['runtime']
+            and old['runtime'] == str(lib.root / 'claude/task-runtime'),
+            'Native Desktop connection changed; previous owner identity is unverified')
+    secret = pathlib.Path(old['secretPath'])
+    require(secret.is_relative_to(lib.root / 'claude/journals') and secret.resolve() == secret
+            and not any(parent.is_symlink() for parent in secret.parents) and not secret.is_symlink()
+            and secret.is_file() and secret.stat().st_uid == os.getuid()
+            and not secret.stat().st_mode & 0o077,
+            'Previous native connection secret is not privately owned')
+    try:
+        os.kill(old['pid'], 0)
+    except ProcessLookupError:
+        pass
+    except OSError as exc:
+        raise PackError('Previous Desktop process absence is unverified') from exc
+    else:
+        raise PackError('Previous Desktop process is alive; preserve its worker custody')
+    from .cloud_work import open_store
+    from .work_artifacts import read_checkpoint
+    store = open_store(lib.root)
+    require(getattr(store, 'cloud', False), 'Restart binding requires activated cloud task authority')
+    snapshot = store.snapshot()
+    tasks = {row['id']: row for row in snapshot['tasks']}
+    for worker in snapshot['workers']:
+        task = tasks.get(worker['taskId'])
+        cwd = worker.get('nativePlan', {}).get('cwd', '')
+        if isinstance(cwd, str) and cwd.startswith(old['runtime'] + os.sep):
+            require(os.path.normpath(cwd) == cwd, 'Previous native worker runtime path is ambiguous')
+        owned = isinstance(cwd, str) and pathlib.Path(cwd).is_absolute() and pathlib.Path(cwd).is_relative_to(old['runtime']) and cwd != old['runtime']
+        if not owned:
+            if task and task.get('ownerInstallationId') == store.binding['installationId']:
+                require((worker['state'] == 'archived' and worker.get('nativeArchived') is True)
+                        or (worker['state'] == 'failed' and not worker.get('turnId')
+                            and (not worker.get('nativeId') or worker.get('nativeArchived') is True)),
+                        'Previous historical worker remains active or UNKNOWN; preserve its custody')
+            continue
+        if worker['state']=='failed' and not worker.get('turnId') and (not worker.get('nativeId') or worker.get('nativeArchived') is True):
+            continue
+        require(worker['state'] == 'archived' and worker.get('nativeArchived') is True
+                and worker.get('checkpoint') and worker.get('turnId'),
+                'Previous native worker remains active or UNKNOWN; checkpoint adoption is required')
+        payload = read_checkpoint(store.root, worker['checkpoint'], worker['taskId'], worker['id'])
+        receipt = payload['nativeReceipt']
+        require(payload.get('resolution', {}).get('harness') == 'claude'
+                and payload['phase'] == worker['phase'] and receipt['threadId'] == worker['nativeId']
+                and receipt['turnId'] == worker['turnId'] and receipt['status'] in {'completed', 'failed', 'cancelled'},
+                'Previous native worker terminal checkpoint differs')
+
+
+def verified_predecessor_hook(lib, previous, rows, existing):
+    """Migrate only the exact bound, content-addressed private hook runtime."""
+    require(previous.get('format') == 'topolo-claude-frontdoors-v1'
+            and previous.get('roles') == [
+                {'sessionId': row['sessionId'], 'cwd': row['cwd'],
+                 'channel': {'engineering': 'engineering', 'operator-01': 'operations', 'cicd': 'cicd'}[row['key'].split('/')[-1]]}
+                for row in rows], 'Existing coordinator hook has another owner; preserve it')
+    require(isinstance(existing, list) and len(existing) == 1 and set(existing[0]) == {'hooks'}
+            and isinstance(existing[0]['hooks'], list) and len(existing[0]['hooks']) == 1,
+            'Existing coordinator hook has another owner; preserve it')
+    hook = existing[0]['hooks'][0]
+    require(isinstance(hook, dict) and set(hook) == {'type', 'command', 'timeout'}
+            and hook['type'] == 'command' and hook['timeout'] == 240,
+            'Existing coordinator hook has another owner; preserve it')
+    try:
+        args = shlex.split(hook['command'])
+    except (ValueError, TypeError) as exc:
+        raise PackError('Predecessor hook command is malformed') from exc
+    require(len(args) == 11 and args[0] == sys.executable
+            and args[2:] == ['--store', str(lib.root), 'work', 'claude-hook', '--harness', 'claude', '||', 'exit', '2'],
+            'Predecessor hook command differs from the owned adapter')
+    adapter = pathlib.Path(args[1])
+    runtime = adapter.parent
+    require(adapter.name == 'topolo-agent-pack' and runtime.parent == lib.root / 'claude/hook-runtimes'
+            and len(runtime.name) == 64 and all(c in '0123456789abcdef' for c in runtime.name),
+            'Predecessor hook runtime is outside the owned content-addressed namespace')
+    hashes = {}
+    for path in [runtime, *sorted(runtime.rglob('*'))]:
+        stat = path.lstat()
+        require(not path.is_symlink() and path.resolve() == path and stat.st_uid == os.getuid()
+                and not stat.st_mode & (0o077 if path == runtime else 0o022) and (path.is_dir() or path.is_file()),
+                'Predecessor hook runtime is not privately owned')
+    # The materializer uses localeCompare: underscore sorts before the extension dot.
+    files = [adapter, *sorted((runtime / 'src/topolo_agent_pack').rglob('*.py'),
+                             key=lambda p: str(p.relative_to(runtime)).replace('_', '\x00').replace('.', '\x01'))]
+    caches = {p for p in runtime.rglob('*.pyc') if p.parent.name == '__pycache__'
+              and p.parent.parent == runtime / 'src/topolo_agent_pack'
+              and any(p.name.startswith(source.stem + '.cpython-') for source in files[1:])}
+    require(adapter.is_file() and len(files) > 1
+            and {p for p in runtime.rglob('*') if p.is_file()} == set(files) | caches,
+            'Predecessor hook runtime source closure differs')
+    for path in files:
+        hashes[str(path.relative_to(runtime))] = hashlib.sha256(path.read_bytes()).hexdigest()
+    digest = hashlib.sha256(json.dumps(hashes, separators=(',', ':'), ensure_ascii=False).encode()).hexdigest()
+    require(digest == runtime.name, 'Predecessor hook runtime content digest differs')
+    require(hook['command'] == shlex.join(args[:-3]) + ' || exit 2',
+            'Predecessor hook command encoding differs')
+    return existing
+
+
+def install(root, value):
+    lib = Library(root)
+    require(isinstance(value, dict) and set(value) == {'desktopPid', 'roles', 'nativeConnection'}
+            and type(value['desktopPid']) is int and value['desktopPid'] > 1,
+            'Verified native Desktop process and coordinator sessions required')
+    config = read_json(lib.root / 'work/config.json')
+    require(config.get('format') == 'topolo-task-dispatch-v2' and config.get('requireCloudAuthority') is True,
+            'Install source-independent cloud task authority before Claude dispatch')
+    channels = {'engineering': 'engineering', 'operator-01': 'operations', 'cicd': 'cicd'}
+    rows = value['roles']
+    require(isinstance(rows, list) and len(rows) == 3 and
+            {r.get('key') for r in rows} == {config['pack'] + '/intakes/' + k for k in channels},
+            'Exactly the three installed coordinator roles are required')
+    require(len({r.get('sessionId') for r in rows}) == 3, 'Coordinator SDK session identities must differ')
+    adapter = pathlib.Path(__file__).resolve().parents[2] / 'topolo-agent-pack'
+    require(adapter.is_file(), 'Installed bundled pack entrypoint is unavailable')
+    command = shlex.join([sys.executable, str(adapter), '--store', str(lib.root),
+                         'work', 'claude-hook', '--harness', 'claude']) + ' || exit 2'
+    previous = read_json(lib.root / 'work/claude-frontdoors.json', {})
+    bindings = []
+    for row in rows:
+        require(set(row) == {'key', 'sessionId', 'cwd'} and isinstance(row['sessionId'], str)
+                and row['sessionId'] and pathlib.Path(row['cwd']).is_absolute(), 'Invalid native coordinator binding')
+        cwd = pathlib.Path(row['cwd'])
+        require(cwd.is_relative_to(lib.root / 'claude/workspaces') and cwd.is_dir()
+                and not cwd.is_symlink() and not any(p.is_symlink() for p in cwd.parents),
+                'Front-door hooks require an owned regular Claude workspace')
+        directory = cwd / '.claude'
+        require(not directory.is_symlink(), 'Claude settings directory cannot be a symlink')
+        path = directory / 'settings.json'
+        require(not path.is_symlink(), 'Claude settings cannot be a symlink')
+        settings = read_json(path, {})
+        hooks = settings.get('hooks', {})
+        for event in ['UserPromptSubmit', 'PreToolUse']:
+            existing = hooks.get(event, [])
+            expected = [{'hooks': [{'type': 'command', 'command': command, 'timeout': 240}]}]
+            if existing and existing != expected:
+                verified_predecessor_hook(lib, previous, rows, existing)
+        bindings.append({'sessionId': row['sessionId'], 'cwd': str(cwd),
+                         'channel': channels[row['key'].split('/')[-1]]})
+    from .claude_desktop import call
+    connection = value['nativeConnection']
+    require(isinstance(connection, dict) and set(connection) == {'pid', 'runtime', 'identity', 'socket', 'secretPath'}
+            and connection['pid'] == value['desktopPid']
+            and connection['runtime'] == str(lib.root / 'claude/task-runtime'), 'Exact native Desktop connection required')
+    native = call(connection, {'kind': 'status'})
+    require(native.get('harness') == 'claude-desktop' and native.get('pid') == value['desktopPid']
+            and native.get('identity') == connection['identity'] and native.get('models'),
+            'Signed-in Desktop authentication and model catalog are unavailable')
+    if previous and previous.get('nativeConnection') != connection:
+        verify_retired_binding(lib, previous, connection)
+    process = subprocess.run(['/bin/ps', '-ww', '-p', str(value['desktopPid']), '-o', 'comm='],
+                             capture_output=True, text=True, timeout=5)
+    executable = process.stdout.strip()
+    require(process.returncode == 0 and pathlib.Path(executable).is_absolute()
+            and pathlib.Path(executable).name == 'Claude', 'Verified Claude Desktop executable is unavailable')
+    # Refresh selected cloud role/domain context before exposing any front door.
+    from .role_context import materialize
+    for row in rows:
+        materialize(lib.root / 'work', row['key'], row['cwd'], harness='claude')
+    # Check every destination before changing any hook. The binding is published
+    # first, so a newly observed hook can only dispatch through the selected owner.
+    atomic_json(lib.root / 'work/claude-frontdoors.json',
+                {'format': 'topolo-claude-frontdoors-v1', 'desktopPid': value['desktopPid'],
+                 'nativeConnection': connection,
+                 'desktopExecutable': executable, 'roles': bindings})
+    for row in rows:
+        path = pathlib.Path(row['cwd']) / '.claude/settings.json'
+        settings = read_json(path, {})
+        hooks = settings.setdefault('hooks', {})
+        for event in ['UserPromptSubmit', 'PreToolUse']:
+            hooks[event] = [{'hooks': [{'type': 'command', 'command': command, 'timeout': 240}]}]
+        atomic_json(path, settings)
+        require(read_json(path) == settings, 'Coordinator hook readback differs')
+    return {'state': 'claude-frontdoors-prepared', 'coordinators': 3,
+            'historyRead': False, 'cloudDispatchVerified': False, 'nativePinsChanged': False}
+
+
+class Service:
+    def __init__(self, lib):
+        self.lib = lib
+        self.broker = ClaudeBroker(lib)
+        self.token = secrets.token_hex(32)
+        self.path = socket_path(lib)
+        self.server = None
+        self.desktop_pid = None
+        self.clients = set()
+
+    async def control(self, reader, writer):
+        self.clients.add(writer)
+        try:
+            value = json.loads(await asyncio.wait_for(reader.readline(), 5))
+            require(secrets.compare_digest(value.get('token', ''), self.token), 'Dispatch connection authentication failed')
+            op, params = value.get('operation'), value.get('params') or {}
+            if op == 'status' and not params:
+                result = {'harness': 'claude', 'cloudDispatchReady': True, 'runtime': self.broker.owner.runtime,
+                          'desktopPid': self.desktop_pid,
+                          'activeTurns': [k for k, s in self.broker.sessions.items() if s.assigned and not s.closed],
+                          'workStartupError': None}
+            elif op == 'work-submit': result = await self.broker.submit(params)
+            elif op == 'work-respond': result = await self.broker.respond(params)
+            elif op == 'work-re-review': result = await self.broker.re_review(params)
+            elif op == 'work-list' and not params: result = await self.broker.snapshot()
+            elif op == 'work-read' and set(params) == {'taskId'}: result = await self.broker.read(params['taskId'])
+            elif op == 'work-retained': result = await self.broker.state_call('retained_page', params)
+            elif op == 'work-watch' and not params:
+                await self.broker.watch(reader, writer)
+                return
+            else: raise PackError('Unsupported Claude dispatch operation')
+            writer.write(canonical(result) + b'\n')
+        except Exception as exc:
+            writer.write(canonical({'error': str(exc)}) + b'\n')
+        finally:
+            try:
+                await writer.drain()
+            except (ConnectionError, OSError):
+                pass
+            writer.close()
+            self.clients.discard(writer)
+
+    async def run(self):
+        with (self.lib.root / 'work/claude-service-owner.lock').open('a') as lock:
+            try: fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError as exc: raise PackError('Claude dispatcher already has an owning process') from exc
+            await self.run_owned()
+
+    async def run_owned(self):
+        require(not (self.lib.root / 'work/claude-shutdown-uncertain.json').exists(),
+                'Prior Claude shutdown needs cloud checkpoint reconciliation before startup')
+        await self.broker.initialize()
+        binding = read_json(self.lib.root / 'work/claude-frontdoors.json')
+        pid = binding['desktopPid']
+        self.desktop_pid = pid
+        os.kill(pid, 0)
+        record = self.lib.root / 'live-bridge.json'
+        old = read_json(record, {})
+        if old:
+            try:
+                request(self.lib, 'status', {})
+            except (PackError, OSError):
+                pass
+            else:
+                raise PackError('An owning connection is already live; no competing dispatcher was started')
+        if self.path.exists():
+            require(not self.path.is_symlink() and self.path.stat().st_uid == os.getuid(), 'Unowned dispatch socket')
+            self.path.unlink()
+        self.server = await asyncio.start_unix_server(self.control, path=self.path, limit=1024 * 1024)
+        self.path.chmod(0o600)
+        atomic_json(record, {'socket': str(self.path), 'token': self.token, 'harness': 'claude', 'pid': os.getpid()})
+        self.broker.launch(self.broker.pump())
+        try:
+            while True:
+                await asyncio.sleep(2)
+                try: os.kill(pid, 0)
+                except ProcessLookupError: break
+        finally:
+            self.server.close()
+            # Python 3.13+ waits for accepted clients too. Watch streams must
+            # close before waiting, otherwise a dead Desktop retains custody
+            # forever while an idle GUI is connected.
+            for writer in tuple(self.clients): writer.close()
+            await self.server.wait_closed()
+            for job in list(self.broker.jobs): job.cancel()
+            await asyncio.gather(*self.broker.jobs, return_exceptions=True)
+            closed = await asyncio.gather(*(self.shutdown_session(wid, session)
+                         for wid, session in self.broker.sessions.items()), return_exceptions=True)
+            if read_json(record, {}).get('token') == self.token:
+                record.unlink()
+                self.path.unlink(missing_ok=True)
+            if any(isinstance(result, BaseException) for result in closed):
+                atomic_json(self.lib.root / 'work/claude-shutdown-uncertain.json',
+                            {'state': 'cloud-shutdown-checkpoint-unconfirmed',
+                             'workerIds': list(self.broker.sessions), 'replayAuthorized': False})
+                raise PackError('Claude processes closed; cloud shutdown checkpoint is unconfirmed. Reconcile without replay.')
+
+    async def shutdown_session(self, wid, session):
+        try:
+            if session.assigned and not session.closed:
+                worker = await self.broker.state_call('worker', wid)
+                if worker['state'] != 'archived':
+                    await self.broker.state_call('worker_update', wid,
+                            {'state': 'unknown', 'error': 'Owning Desktop service ended before verified closure.'})
+                    task = await self.broker.state_call('get', worker['taskId'])
+                    await self.broker.state_call('update', task['id'], task['revision'],
+                            {'state': 'unknown', 'summary': 'Owning Desktop service ended; reconcile the existing worker before resuming.'},
+                            'recovery-required')
+        finally:
+            await session.close()
+
+
+def ensure_running(lib):
+    expected_pid = read_json(lib.root / 'work/claude-frontdoors.json').get('desktopPid')
+    require(type(expected_pid) is int and expected_pid > 1, 'Current native Desktop owner binding is required')
+    try:
+        status = request(lib, 'status', {})
+    except (PackError, OSError):
+        status = None
+    if status is not None:
+        require(status.get('harness') == 'claude' and status.get('cloudDispatchReady') is True
+                and status.get('desktopPid') == expected_pid,
+                'Another native owner holds this installation; do not start a competing dispatcher')
+        return
+    lock_path = lib.root / 'work/claude-service-start.lock'
+    with lock_path.open('a') as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        try:
+            status = request(lib, 'status', {})
+        except (PackError, OSError):
+            status = None
+        if status is not None:
+            require(status.get('harness') == 'claude' and status.get('cloudDispatchReady') is True
+                    and status.get('desktopPid') == expected_pid,
+                    'Another native owner holds this installation')
+            return
+        # Verify cloud activation before spawning a persistent process. There is
+        # no SQLite fallback and an unchanged refusal does not start a retry loop.
+        from .cloud_work import open_store
+        store = open_store(lib.root)
+        require(getattr(store, 'cloud', False), 'Claude requires activated cloud task authority')
+        store.load()
+        env = dict(os.environ)
+        env['PYTHONPATH'] = str(pathlib.Path(__file__).resolve().parent.parent)
+        adapter = pathlib.Path(__file__).resolve().parents[2] / 'topolo-agent-pack'
+        require(adapter.is_file(), 'Installed bundled service entrypoint is unavailable')
+        log = (lib.root / 'work/claude-service.log').open('ab')
+        try:
+            child = subprocess.Popen([sys.executable, str(adapter), '--store', str(lib.root),
+                                      'work', 'serve-claude', '--harness', 'claude'],
+                                     stdin=subprocess.DEVNULL, stdout=log, stderr=log, env=env, start_new_session=True)
+        finally:
+            log.close()
+        deadline = time.monotonic() + 120
+        while child.poll() is None and time.monotonic() < deadline:
+            try:
+                status = request(lib, 'status', {})
+                require(status.get('harness') == 'claude' and status.get('cloudDispatchReady') is True
+                        and status.get('desktopPid') == expected_pid,
+                        'Unexpected owning dispatch connection')
+                return
+            except (PackError, OSError):
+                time.sleep(.1)
+        if child.poll() is None:
+            child.terminate()
+            child.wait(timeout=10)
+        raise PackError('Claude dispatcher did not activate; inspect its owning startup log. No request was submitted.')
+
+
+def refresh_desktop_owner(lib):
+    """Resolve this native hook's Desktop ancestor after an ordinary app restart.
+
+    Uses the executable observed at setup, not a PID cache, version allowlist,
+    browser automation, debugger or local conversation history.
+    """
+    path = lib.root / 'work/claude-frontdoors.json'
+    binding = read_json(path)
+    expected = binding.get('desktopExecutable')
+    require(isinstance(expected, str) and pathlib.Path(expected).is_absolute(),
+            'Verified Desktop executable binding is missing')
+    pid = os.getppid()
+    seen = set()
+    for _ in range(16):
+        require(pid > 1 and pid not in seen, 'This hook has no bound Claude Desktop ancestor')
+        seen.add(pid)
+        observed = subprocess.run(['/bin/ps', '-ww', '-p', str(pid), '-o', 'ppid=', '-o', 'comm='],
+                                  capture_output=True, text=True, timeout=5)
+        fields = observed.stdout.strip().split(None, 1)
+        require(observed.returncode == 0 and len(fields) == 2, 'Native Desktop ancestry is unavailable')
+        if fields[1] == expected:
+            require(binding['desktopPid']==pid and binding.get('nativeConnection',{}).get('pid')==pid,
+                    'Restarted Desktop requires the qualified pack launcher; prior worker custody is preserved')
+            return pid
+        require(fields[0].isdigit(), 'Native parent process identity is invalid')
+        pid = int(fields[0])
+    raise PackError('Native Desktop ancestry exceeds its bounded setup contract')