@topolo/cli 0.13.19 → 0.13.22

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

@@ -0,0 +1,216 @@
+"""Recover one already delivered Desktop completion, without resending any input.
+
+The legacy native guard requires the original inventory during read/archive.
+Only explicitly reviewed added outputs may be moved, reversibly, beneath its
+excluded recovery directory. Original context is always checked by its digest.
+"""
+import hashlib
+import os
+from pathlib import Path
+import stat
+import uuid
+
+from .storage import atomic_json, canonical, read_json
+from .work import require
+
+
+def _file(path):
+    meta = path.lstat()
+    require(stat.S_ISREG(meta.st_mode) and meta.st_uid == os.getuid()
+            and not meta.st_mode & 0o022 and path.resolve() == path,
+            'Recovery requires an owned regular non-writable-by-others file')
+    require(0 < meta.st_size <= 100 * 1024 * 1024, 'Recovery file exceeds boundary')
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+class OutputCustody:
+    def __init__(self, worker, outputs):
+        self.cwd = Path(worker['cwd'])
+        require(self.cwd.is_absolute() and self.cwd.resolve() == self.cwd,
+                'Recovery workspace identity differs')
+        require(isinstance(outputs, list) and 0 < len(outputs) <= 16,
+                'Explicit selected output manifest required')
+        self.outputs = []
+        for row in outputs:
+            require(isinstance(row, dict) and set(row) == {'path', 'sha256'},
+                    'Closed recovery output manifest required')
+            path = Path(row['path'])
+            require(path.is_relative_to(self.cwd) and path != self.cwd
+                    and not path.is_relative_to(self.cwd / '.topolo-worker')
+                    and path not in [p for p, _ in self.outputs], 'Recovery output path differs')
+            require(_file(path) == row['sha256'], 'Selected output digest differs')
+            self.outputs.append((path, row['sha256']))
+        self.initial = {}
+        for path in sorted(self.cwd.rglob('*')):
+            if path.is_relative_to(self.cwd / '.topolo-worker'):
+                continue
+            require(not path.is_symlink(), 'Recovery workspace contains a link')
+            if path.is_file() and path not in [p for p, _ in self.outputs]:
+                self.initial[str(path)] = _file(path)
+        require(hashlib.sha256(canonical(self.initial)).hexdigest()
+                == worker['nativePlan']['contextDigest'], 'Original selected context differs')
+        for directory in [self.cwd, self.cwd / '.topolo-worker', self.cwd / '.topolo-worker' / 'recovery']:
+            if directory.exists():
+                meta = directory.lstat()
+                require(stat.S_ISDIR(meta.st_mode) and meta.st_uid == os.getuid()
+                        and not meta.st_mode & 0o022 and directory.resolve() == directory,
+                        'Recovery directory ownership differs')
+        self.directory = self.cwd / '.topolo-worker' / 'recovery' / worker['id']
+        self.journal = self.directory / 'journal.json'
+        require(not self.directory.exists(), 'Recovery already exists; reconcile its exact journal')
+        self.moved = []
+
+    def begin(self):
+        self.directory.mkdir(parents=True, mode=0o700)
+        self.record('prepared')
+
+    def record(self, state):
+        atomic_json(self.journal, {'format': 'topolo-native-completion-recovery-v1',
+                    'state': state, 'inputs': self.initial,
+                    'outputs': [{'path': str(p), 'sha256': h} for p, h in self.outputs]})
+
+    def quarantine(self):
+        require(not self.moved, 'Output quarantine already active')
+        for path, digest in self.outputs:
+            require(_file(path) == digest, 'Output changed before quarantine')
+            target = self.directory / ('output-' + str(len(self.moved)))
+            require(not target.exists(), 'Quarantine target exists')
+            os.rename(path, target)
+            self.moved.append((path, target, digest))
+        actual = {str(p): _file(p) for p in sorted(self.cwd.rglob('*'))
+                  if p.is_file() and not p.is_relative_to(self.cwd / '.topolo-worker')}
+        require(actual == self.initial, 'Original context changed during quarantine')
+        self.record('quarantined')
+
+    def restore(self):
+        for path, target, digest in reversed(self.moved):
+            require(not path.exists() and _file(target) == digest,
+                    'Output restoration collision or digest differs; custody retained')
+            os.rename(target, path)
+        self.moved = []
+        self.record('outputs-restored')
+
+
+def _terminal(result, worker):
+    plan = worker['nativePlan']
+    require(result.get('state') == 'native-task-completed'
+            and result.get('nativeId') == worker['nativeId']
+            and result.get('messageId') == worker['turnId']
+            and result.get('model') == plan['model'] and result.get('effort') == plan['effort']
+            and isinstance(result.get('result'), str)
+            and type(result.get('toolItems')) is int and result['toolItems'] >= 0,
+            'Exact existing native terminal result required')
+    for key in ['resultUuid', 'cliSessionId']:
+        require(str(uuid.UUID(result[key])) == result[key], 'Native producer identity is unqualified')
+    return {'id': worker['turnId'], 'status': 'completed', 'output': result['result'],
+            'toolItems': result['toolItems'], 'nativeSessionId': result['cliSessionId'],
+            'nativeResultId': result['resultUuid']}
+
+
+def _alive(pid):
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    return True
+
+
+def recover_completed(lib, request, store=None, native_call=None, alive=None, checkpoint=None):
+    """Recover after the exact old Python service stops; Desktop remains alive.
+
+    No dispatcher is started or pumped. The caller must separately qualify the
+    corrected native guard before starting the independent review continuation.
+    """
+    import fcntl
+    from .cloud_work import CloudStore
+    from .claude_desktop import call
+    from .work_artifacts import checkpoint as publish_checkpoint
+    require(set(request) == {'taskId', 'workerId', 'revision', 'attempt', 'turnId',
+                            'outputs', 'expectedServicePid', 'expectedNative'},
+            'Closed native completion recovery request required')
+    checkpoint = checkpoint or publish_checkpoint
+    native_call = native_call or call
+    alive = alive or _alive
+    with lib.lock(), (lib.root / 'work/claude-service-start.lock').open('a') as start_lock:
+        try:
+            fcntl.flock(start_lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            require(False, 'Another Claude startup owns this installation')
+        previous = read_json(lib.root / 'live-bridge.json')
+        require(type(request['expectedServicePid']) is int and request['expectedServicePid'] > 1
+                and previous.get('harness') == 'claude'
+                and previous.get('pid') == request['expectedServicePid']
+                and not alive(request['expectedServicePid']),
+                'Exact previous Python owner must be stopped before recovery')
+        connection = read_json(lib.root / 'work/claude-frontdoors.json')['nativeConnection']
+        require(alive(connection['pid']) and connection['pid'] == request['expectedNative']['pid']
+                and connection['identity'] == request['expectedNative']['identity'],
+                'Original Desktop native owner differs')
+        require(native_call(connection, {'kind': 'status'}) == request['expectedNative']
+                and request['expectedNative'].get('qualified') is True
+                and request['expectedNative'].get('workers') == 1,
+                'Exact sole native worker connection required')
+        store = store or CloudStore(lib.root)
+        task = store.get(request['taskId'])
+        worker = store.worker(request['workerId'])
+        require(task['state'] == 'unknown' and task['revision'] == request['revision']
+                and task['attempt'] == request['attempt'] and worker['state'] == 'unknown'
+                and worker['taskId'] == task['id'] and worker['phase'] == 'execute'
+                and worker['attempt'] == task['attempt'] and worker['turnId'] == request['turnId']
+                and worker['id'] in task['workerIds'] and not worker.get('checkpoint')
+                and task.get('ownerInstallationId') == store.binding['installationId'],
+                'Exact owned UNKNOWN execution checkpoint required')
+        plan = worker['nativePlan']
+        require(all(plan.get(key) == worker.get(key) for key in ['taskId', 'nativeId', 'cwd'])
+                and plan.get('workerId') == worker['id'], 'Cloud native plan identity differs')
+        for other in store.workers():
+            require(other['id'] == worker['id'] or
+                    other['state'] == 'archived' and other.get('nativeArchived') is True or
+                    other['state'] == 'failed' and not other.get('turnId') and
+                    (not other.get('nativeId') or other.get('nativeArchived') is True),
+                    'Another unresolved cloud worker prevents standalone recovery')
+        custody = OutputCustody(worker, request['outputs'])
+        custody.begin()
+        try:
+            custody.quarantine()
+            native = native_call(connection, {'kind': 'read', 'workerId': worker['id'],
+                                              'messageId': worker['turnId']})
+            receipt = _terminal(native, worker)
+        finally:
+            custody.restore()
+        actual = {'id': receipt['id'], 'status': receipt['status'],
+                  'items': [{'type': 'agentMessage', 'text': receipt['output']}] +
+                           [{'type': 'toolUse'} for _ in range(receipt['toolItems'])],
+                  'nativeProof': {'harness': 'claude-desktop', 'sessionId': receipt['nativeSessionId'],
+                                  'resultId': receipt['nativeResultId']}}
+        proof, payload, normalized = checkpoint(store.root, task, worker, actual)
+        require(payload.get('outputError') is None and normalized is not None,
+                'Native output contract is not checkpoint-ready')
+        require(store.get(task['id']) == task and store.worker(worker['id']) == worker,
+                'Task or worker changed before recovered checkpoint publication')
+        store.worker_update(worker['id'], {'state': 'archiving', 'checkpoint': proof})
+        task = store.update(task['id'], task['revision'],
+                {'checkpoints': task['checkpoints'] + [proof]}, 'checkpoint-saved')
+        custody.record('checkpoint-saved')
+        try:
+            custody.quarantine()
+            retired = native_call(connection, {'kind': 'archive', 'workerId': worker['id'],
+                                               'messageId': worker['turnId']})
+            require(retired.get('state') == 'native-worker-archived'
+                    and retired.get('nativeId') == worker['nativeId'],
+                    'Existing native worker archival was not acknowledged')
+        finally:
+            custody.restore()
+        require(native_call(connection, {'kind': 'status'}) == {**request['expectedNative'], 'workers': 0},
+                'Native archival readback differs')
+        store.worker_update(worker['id'], {'state': 'archived', 'nativeArchived': True,
+                            'nativeRetirement': {'kind': 'native-desktop-session',
+                                                 'desktopChatArchived': True, **retired}})
+        task = store.update(task['id'], task['revision'],
+                {'state': 'reviewing', 'phase': 'review',
+                 'result': {**normalized, 'checkpoint': proof, 'workerId': worker['id']},
+                 'summary': 'Existing native completion recovered without resend; independent review pending.'},
+                'worker-released')
+        custody.record('archived')
+        return {'taskId': task['id'], 'workerId': worker['id'], 'attempt': task['attempt'],
+                'state': task['state'], 'nativeId': worker['nativeId'], 'turnId': worker['turnId']}

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

@@ -0,0 +1,181 @@
+"""Task workers in the already authenticated Claude Desktop process.
+
+The closed native endpoint survives closing the temporary setup inspector.
+It exposes task lifecycle operations only, never vendor credentials or eval.
+"""
+import asyncio
+import hashlib
+import json
+import os
+import pathlib
+import shlex
+import socket
+import stat
+import sys
+
+from .claude_runner import public_progress
+from .storage import read_json, canonical, atomic_json
+from .work import require
+
+
+def call(connection, operation):
+    info = pathlib.Path(connection['secretPath'])
+    metadata = info.lstat()
+    require(stat.S_ISREG(metadata.st_mode) and metadata.st_uid == os.getuid()
+            and metadata.st_mode & 0o077 == 0, 'Unowned native task connection secret')
+    target = pathlib.Path(connection['socket']).lstat()
+    require(stat.S_ISSOCK(target.st_mode) and target.st_uid == os.getuid(), 'Unowned native task socket')
+    secret = read_json(info)
+    payload = {'pid': connection['pid'], 'identity': connection['identity'],
+               'token': secret['token'], 'operation': operation}
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as channel:
+        channel.settimeout(65)
+        channel.connect(connection['socket'])
+        channel.sendall(canonical(payload) + b'\n')
+        with channel.makefile('rb') as stream:
+            raw = stream.readline(1048577)
+    require(raw.endswith(b'\n') and len(raw) <= 1048576, 'Native task response is missing or exceeds its boundary')
+    result = json.loads(raw)
+    require(set(result) == {'result'}, 'Native task operation refused: ' + str(result.get('error', 'invalid response')))
+    return result['result']
+
+
+def authorize(root, operation):
+    """Independent cloud read before a native creation, send or archive."""
+    from .cloud_work import CloudStore
+    from .work_artifacts import read_checkpoint
+    plan = operation['plan']
+    store = CloudStore(root)
+    worker = store.worker(plan['workerId'])
+    task = store.get(worker['taskId'])
+    require(task.get('ownerInstallationId') == store.binding['installationId']
+            and worker.get('nativePlan') == plan and worker['taskId'] == plan['taskId']
+            and worker['nativeId'] == plan['nativeId'], 'Native worker cloud ownership differs')
+    if operation['kind'] == 'create':
+        require(set(operation) == {'kind', 'plan', 'files'} and worker['state'] == 'creating'
+                and hashlib.sha256(canonical(operation['files'])).hexdigest() == plan['contextDigest'],
+                'Native creation has no exact cloud reservation')
+    elif operation['kind'] == 'send':
+        require(set(operation) == {'kind', 'plan', 'workerId', 'assignment'}
+                and worker['state'] == 'running' and worker['turnId'] == operation['assignment']['messageId']
+                and worker['resolution']['nativeACK'] == {'model': plan['model'], 'effort': plan['effort']},
+                'Native assignment has no acknowledged cloud delivery reservation')
+    else:
+        require(operation['kind'] == 'archive' and
+                set(operation) == {'kind', 'plan', 'workerId', 'messageId', 'terminal'}
+                and worker['state'] == 'archiving', 'Native archival has no checkpointed worker')
+        payload = read_checkpoint(store.root, worker['checkpoint'], task['id'], worker['id'])
+        receipt = payload['nativeReceipt']
+        terminal = operation['terminal']
+        require(receipt['status'] == 'completed' and receipt['threadId'] == plan['nativeId']
+                and receipt['turnId'] == operation['messageId'] == terminal['messageId']
+                and receipt['producer']['resultId'] == terminal['resultUuid'],
+                'Native archival differs from the verified cloud checkpoint')
+    return {'authorized': True}
+
+
+def main():
+    try:
+        raw = sys.stdin.read(262145)
+        require(len(raw) <= 262144 and len(sys.argv) == 2, 'Bounded native authority request required')
+        print(json.dumps(authorize(sys.argv[1], json.loads(raw))))
+        return 0
+    except Exception as exc:
+        print('Native cloud authority refused: ' + str(exc), file=sys.stderr)
+        return 2
+
+
+class Session:
+    def __init__(self, cwd, worker_id, model, effort, progress=None):
+        self.cwd = pathlib.Path(cwd)
+        self.id = worker_id
+        self.model = model
+        self.effort = effort
+        self.progress = progress
+        self.plan = None
+        self.connection = None
+        self.results = {}
+        self.pending = None
+        self.assigned = False
+        self.closed = False
+        self.archived = False
+        self.allow_tools = True
+        self.directory = self.cwd / '.topolo-worker'
+        self.directory.mkdir(mode=0o700)
+        atomic_json(self.directory / 'gate.json', {'sessionId': None, 'model': model,
+                    'effort': effort, 'phase': 'readiness'})
+        adapter = pathlib.Path(__file__).resolve().parents[2] / 'topolo-agent-pack'
+        command = shlex.join([sys.executable, str(adapter), 'work', 'claude-worker-hook',
+                             '--harness', 'claude', '--input', str(self.directory)]) + ' || exit 2'
+        atomic_json(self.cwd / '.claude/settings.json', {'autoMemoryEnabled': False,
+                    'hooks': {'PreToolUse': [{'hooks': [{'type': 'command', 'command': command, 'timeout': 15}]}]}})
+
+    async def operation(self, value):
+        require(self.connection is not None, 'The signed-in Desktop task connection is unavailable')
+        return await asyncio.to_thread(call, self.connection, value)
+
+    async def start(self):
+        require(self.plan is not None, 'Exact cloud-reserved native plan required')
+        files = {str(p): hashlib.sha256(p.read_bytes()).hexdigest()
+                 for p in sorted(self.cwd.rglob('*')) if p.is_file() and not p.is_relative_to(self.directory)}
+        require(hashlib.sha256(canonical(files)).hexdigest() == self.plan['contextDigest'],
+                'Selected native context changed before creation')
+        await self.operation({'kind': 'create', 'plan': self.plan, 'files': files})
+        result = await self.wait(self.id)
+        require(result['output'].strip() == 'TOPOLO_WORKER_READY:' + self.id and result['toolItems'] == 0,
+                'Exact tool-free native readiness did not complete')
+        self.sdk_session = result['nativeSessionId']
+        return {'sessionId': self.plan['nativeId'], 'processId': self.connection['pid'],
+                'model': self.model, 'effort': self.effort, 'boundary': 'signed-in Desktop native terminal producer'}
+
+    async def assign(self, message_id, prompt):
+        require(not self.assigned and not self.closed and self.pending is None,
+                'This native worker already has an assignment; reconcile without resend')
+        self.assigned = True
+        self.pending = message_id
+        atomic_json(self.directory / 'gate.json', {'sessionId': self.sdk_session, 'model': self.model,
+                    'effort': self.effort, 'phase': 'assigned', 'allowTools': self.allow_tools})
+        await self.operation({'kind': 'send', 'workerId': self.id,
+                              'assignment': {'messageId': message_id, 'prompt': prompt}})
+        return await self.wait(message_id)
+
+    async def wait(self, message_id):
+        seen = set()
+        async with asyncio.timeout(1800):
+            while True:
+                result = await self.operation({'kind': 'read', 'workerId': self.id, 'messageId': message_id})
+                if self.assigned and self.progress:
+                    for row in result['messages']:
+                        if row['id'] not in seen and public_progress(row['text']):
+                            await self.progress(row['id'], row['text'][:1600])
+                            seen.add(row['id'])
+                if result['state'] == 'native-task-completed':
+                    require(result['nativeId'] == self.plan['nativeId'] and result['messageId'] == message_id
+                            and result['model'] == self.model and result['effort'] == self.effort,
+                            'Native terminal identity or settings differ')
+                    receipt = {'id': message_id, 'status': 'completed', 'output': result['result'],
+                               'toolItems': result['toolItems'], 'nativeSessionId': result['cliSessionId'],
+                               'nativeResultId': result['resultUuid']}
+                    self.results[message_id] = receipt
+                    self.pending = None
+                    return receipt
+                require(result['state'] == 'native-task-pending', 'Native task state is unqualified')
+                await asyncio.sleep(1)
+
+    async def archive(self, message_id):
+        result = await self.operation({'kind': 'archive', 'workerId': self.id, 'messageId': message_id})
+        require(result['state'] == 'native-worker-archived' and result['nativeId'] == self.plan['nativeId'],
+                'Native Desktop worker archival was not acknowledged')
+        self.closed = True
+        self.archived = True
+        return {'kind': 'native-desktop-session', 'desktopChatArchived': True, **result}
+
+    async def close(self):
+        # An uncertain task stays visible and owned. Closing an adapter is never
+        # represented as archival, and never cancels or deletes native work.
+        self.closed = True
+        return {'state': 'native-session-preserved', 'desktopChatArchived': self.archived}
+
+
+if __name__ == '__main__':
+    sys.exit(main())

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

@@ -0,0 +1,240 @@
+"""Claude subscription workers behind Desktop's three permanent front doors.
+
+Uses the same cloud state, checkpoints, review phases and Activity events as the
+Codex broker. It does not launch a competing local task ledger or import history.
+"""
+import asyncio
+import hashlib
+import copy
+import pathlib
+import sys
+import types
+import uuid
+
+from . import task_models
+from .claude_desktop import Session
+from .cicd import RELEASE_RISK_TYPES
+from .role_catalog import digest
+from .storage import atomic_json, read_json, component_key, canonical
+from .work import require
+from .work_native import Broker
+
+
+class ClaudeBroker(Broker):
+    def __init__(self, lib, session_factory=Session):
+        owner = types.SimpleNamespace(lib=lib, runtime=str(lib.root / 'claude/task-runtime'),
+                    execution=types.SimpleNamespace(roles={}, verified=set()))
+        super().__init__(owner)
+        require(getattr(self.store, 'cloud', False), 'Claude dispatch requires cloud authority; no local fallback')
+        self.factory = session_factory
+        self.sessions = {}
+
+    async def initialize(self):
+        await self.state_call('snapshot')
+        self.config()
+        for channel in ['engineering', 'operations', 'cicd']:
+            config, _, _ = self.config(channel)
+            await asyncio.to_thread(self.qualify, config)
+        workers = await self.state_call('workers')
+        for task in await self.state_call('list'):
+            if task.get('ownerInstallationId') == self.store.binding['installationId'] or task.get('resumeAfterCheckpoint') is not True:
+                continue
+            if task['state'] not in {'queued', 'executing', 'reviewing'}:
+                continue
+            owned = [w for w in workers if w['taskId'] == task['id']]
+            phase = {'queued': 'route', 'executing': 'execute', 'reviewing': 'review'}[task['state']]
+            if any(w['phase'] == phase and w.get('attempt', 1) == task.get('attempt', 1)
+                   and (phase != 'review' or w.get('reviewGeneration', 0) == task.get('reviewGeneration', 0)) for w in owned):
+                continue
+            if not all(w['state'] == 'archived' and w.get('nativeArchived') is True or
+                       w['state'] == 'failed' and not w.get('turnId') and
+                       (not w.get('nativeId') or w.get('nativeArchived') is True) for w in owned):
+                continue
+            await self.state_call('adopt_ready', task['id'], task['revision'])
+
+    def config(self, channel='engineering'):
+        root = self.store.root
+        saved = read_json(root / 'config.json')
+        catalog = read_json(root / 'role-catalog.json')
+        require(saved.get('format') == 'topolo-task-dispatch-v2'
+                and saved.get('requireCloudAuthority') is True and saved.get('frontdoorDispatch') is True,
+                'Claude requires the source-independent cloud dispatcher')
+        require(catalog.get('format') == 'topolo-task-role-catalog-v1'
+                and catalog.get('pack') == saved['pack'] and digest(catalog) == saved['catalogDigest'],
+                'Reviewed specialization catalog changed')
+        native, revision = self.owner.lib.load(saved['pack'])
+        require(revision == catalog['nativePackRevision'] and len(native['agents']) == 3,
+                'The three-coordinator installation changed')
+        require(channel in catalog['channels'] and type(saved['maxWorkers']) is int
+                and 1 <= saved['maxWorkers'] <= 8, 'Unknown channel or invalid worker capacity')
+        registry = read_json(root / 'role-bindings.json')
+        require(registry.get('organizationId') == 'org_topolo_platform'
+                and registry.get('roles') == catalog['bindings'], 'Agent definition references differ')
+        selected = catalog['channels'][channel]
+        manifest = {'packId': saved['pack'], 'sourceIndependent': True,
+                    'agents': [r for r in catalog['roles'] if component_key(r) in selected['roleKeys']]}
+        return {**selected, 'pack': saved['pack'], 'catalogOnly': True,
+                'maxWorkers': saved['maxWorkers']}, manifest, {
+                'configuration': catalog['configuration'], 'constraints': catalog['constraints']}
+
+    def qualify(self, config):
+        from .permissions import load
+        from .topolo import Client, organization_execution_policy
+        native, _ = self.owner.lib.load(config['pack'])
+        consent = load(self.owner.lib, config['pack'], native['agents'])
+        require(consent is not None and consent['profile'] == 'full-access',
+                'Explicit organization-bound full-access installation consent is required')
+        key = config['pack'] + '/intakes/' + config['intakeRole']
+        require(consent.get('overrides', {}).get(key, consent['profile']) == 'full-access',
+                'Selected channel does not have full-access installation consent')
+        client = Client('production', 'org:org_topolo_platform')
+        policy, proof = organization_execution_policy(client, consent, native['agents'],
+                                                       consent.get('agentWorkspaceId'))
+        require(policy.get('scopePolicyMode') == 'unrestricted' and policy.get('fullAccessEnabled') is True
+                and proof['profileCeilingVerified'],
+                'This worker cannot enforce an organization tool/action allowlist; execution remains blocked')
+        self.tool_path = client.env['PATH']
+
+    async def start(self, task, phase, config, manifest, models):
+        await asyncio.to_thread(self.qualify, config)
+        if phase == 'route':
+            role_id = config['intakeRole']
+            model_task = {'type': 'route-request', 'complexity': 'routine', 'risk': 'normal'}
+        elif phase == 'execute':
+            role_id, model_task = task['route']['role'], task['route']['task']
+        else:
+            role_id = config['reviewRole']
+            model_task = {**task['route']['task'], 'type': 'verify-task',
+                          'complexity': 'complex' if task['route']['task']['risk'] == 'security-critical'
+                          or task['channel'] == 'cicd' and task['route']['task']['type'] in RELEASE_RISK_TYPES else 'standard'}
+        roles = [r for r in manifest['agents'] if r['id'] == role_id]
+        require(len(roles) == 1, 'Selected specialization is ambiguous')
+        key = component_key(roles[0])
+        constraints = task_models.role_constraints(models['constraints'], key)
+        selected = task_models._selection(models['configuration'], model_task, 'claude', constraints)
+        require(task['channel'] != 'cicd' or model_task['type'] not in RELEASE_RISK_TYPES
+                or selected['rule']['profile'] == 'deep', 'Release-risk tasks require a deep profile')
+        effort = next(e for e in selected['preferences'] if e in selected['allowedEfforts'])
+        pending = {'harness': 'claude', 'resolved': {'model': selected['model'], 'effort': effort},
+                   'nativeACK': None, 'state': 'intent-only-awaiting-native-readiness'}
+        worker = await self.state_call('reserve', task['id'], phase, key, pending, config['maxWorkers'])
+        wid = worker['id']
+        cwd = pathlib.Path(self.owner.runtime) / 'task-workspaces' / wid
+        cwd.mkdir(parents=True, mode=0o700)
+        from .work_context import ensure, materialize
+        context = await asyncio.to_thread(ensure, self.store.root, task)
+        if task.get('contextRef') != context:
+            current = await self.state_call('get', task['id'])
+            task = await self.state_call('update', task['id'], current['revision'],
+                    {'contextRef': context, 'summary': 'Selected cloud task context is verified.'}, 'task-context-bound')
+        from .role_context import materialize as materialize_role
+        role = await asyncio.to_thread(materialize_role, self.store.root, key, cwd, harness='claude')
+        atomic_json(cwd / 'TASK.json', task)
+        await asyncio.to_thread(materialize, self.store.root, task, cwd)
+        if phase in {'execute', 'review'}:
+            from .linked_task_context import materialize as materialize_linked
+            await materialize_linked(self.store, task, cwd, lambda tid: self.state_call('get', tid))
+        atomic_json(cwd / 'context/retained-read-input.json', {'cursor': 0, 'limit': 50})
+        atomic_json(cwd / 'context/dispatch-connection.json', {
+            'format': 'topolo-dispatch-transport-v1',
+            'cloudReference': {k: self.store.binding[k] for k in ['organizationId', 'workspaceId', 'documentId', 'datasetId']},
+            'retainedReadCommand': [sys.executable, str(pathlib.Path(__file__).resolve().parents[2] / 'topolo-agent-pack'), '--store', str(self.owner.lib.root),
+                                    'work', 'retained', '--harness', 'claude', '--input', str(cwd / 'context/retained-read-input.json')],
+            'pageInput': {'cursor': 0, 'limit': 50},
+            'boundary': 'Read relevant retained context in pages; preserve original owners. Do not load the whole state document, portfolio export or old chats.'})
+        if phase == 'review':
+            from .work_artifacts import materialize_result
+            await asyncio.to_thread(materialize_result, self.store.root, task, cwd)
+            from .review_context import materialize as materialize_review
+            await asyncio.to_thread(materialize_review, self.store, task, cwd)
+        async def progress(identity, text):
+            await self.state_call('progress', wid, identity, text)
+            await self.notify()
+        session = self.factory(cwd, wid, selected['model'], effort, progress if phase == 'execute' else None)
+        session.allow_tools = phase != 'route'
+        settings_path = cwd / '.claude/settings.json'
+        settings = read_json(settings_path, {})
+        settings['env'] = {'PATH': self.tool_path}
+        atomic_json(settings_path, settings)
+        files = {str(p): hashlib.sha256(p.read_bytes()).hexdigest() for p in sorted(cwd.rglob('*'))
+                 if p.is_file() and not p.is_relative_to(cwd / '.topolo-worker')}
+        native_plan = {'taskId': task['id'], 'workerId': wid, 'nativeId': 'local_' + wid, 'cwd': str(cwd),
+                       'title': (phase.title() + ' · ' + task['objective'])[:256],
+                       'model': selected['model'], 'effort': effort, 'permissionMode': 'bypassPermissions',
+                       'contextDigest': hashlib.sha256(canonical(files)).hexdigest()}
+        await self.state_call('worker_update', wid, {'state': 'creating', 'cwd': str(cwd),
+                              'nativeId': native_plan['nativeId'], 'roleSource': role, 'nativePlan': native_plan})
+        session.plan = native_plan
+        session.connection = read_json(self.store.root / 'claude-frontdoors.json')['nativeConnection']
+        self.sessions[wid] = session
+        try:
+            ack = await session.start()
+            catalog = {'harness': 'claude', 'source': 'native-account-model-ids',
+                       'connectionGeneration': str(ack['processId']) + ':' + ack['sessionId'],
+                       'models': [ack['model']]}
+            resolution = task_models.resolve_intent(models['configuration'], model_task, 'claude', catalog, constraints)
+            resolution = task_models.acknowledge(resolution, {'model': ack['model'], 'effort': ack['effort']},
+                            configuration=models['configuration'], catalog=catalog, constraints=constraints)
+            message_id = str(uuid.uuid4())
+            # Cloud commit and readback precede stdin. An uncertain commit or
+            # delivery retains this exact worker/input; no replacement is sent.
+            await self.state_call('worker_update', wid, {'state': 'running', 'resolution': resolution, 'turnId': message_id})
+            current = await self.state_call('get', task['id'])
+            await self.state_call('update', task['id'], current['revision'],
+                    {'state': {'route': 'routing', 'execute': 'executing', 'review': 'reviewing'}[phase],
+                     'phase': phase, 'workerIds': current['workerIds'] + [wid],
+                     'summary': 'A fresh Claude ' + phase + ' specialist is running.'}, 'native-resume-verified')
+            check = await self.state_call('worker', wid)
+            require(check['turnId'] == message_id and check['resolution'] == resolution,
+                    'Canonical delivery reservation was not acknowledged')
+            await self.notify()
+            self.launch(self.execute(worker, session, message_id, self.prompt(task, phase, manifest, cwd)))
+        except Exception:
+            # Task input is sent only by execute(), after this startup block.
+            await session.close()
+            await self.state_call('worker_update', wid, {'state': 'failed', 'nativeArchived': False,
+                'nativeRetirement': {'kind': 'native-desktop-session', 'desktopChatArchived': False}})
+            raise
+
+    def prompt(self, task, phase, manifest, cwd):
+        prompt = super().prompt(task, phase, manifest, cwd).replace('Read AGENTS.md', 'Read CLAUDE.md')
+        if phase in {'execute', 'review'}:
+            prompt += '\nFor relevant existing-work inventory only, context/dispatch-connection.json supplies the current installation transport and paged read command. It grants no takeover or replay authority.'
+        if phase == 'review':
+            prompt += '\nRead context/dispatch-connection.json and context/workflow-evidence.json, including its evidenceContract, before declaring authority or lifecycle evidence missing. Save any read-only command output you cite in this reviewer workspace; never cite /tmp, /private/tmp or another worker directory. The transport supplies the pinned adapter command and bounded pageInput; run that read-only command to independently verify relevant retained evidence. A role such as queue-recovery is the selected specialization; status-read is its classified task type, not a separate specialist name. Workflow evidence records this attempt only. Inspect prior worker archival and native model acknowledgements there. The coordinator separately verifies this reviewer archives after its checkpoint and that Activity reaches the live GUI; never fabricate those post-review observations or perform work again.'
+        return prompt
+
+    async def execute(self, worker, session, message_id, prompt):
+        try:
+            result = await session.assign(message_id, prompt)
+            await self.finish(worker['id'], result)
+            saved = await self.state_call('worker', worker['id'])
+            if saved['state'] != 'archived':
+                await session.close()
+        except Exception as exc:
+            await self.state_call('worker_update', worker['id'], {'state': 'unknown', 'error': str(exc)})
+            task = await self.state_call('get', worker['taskId'])
+            await self.state_call('update', task['id'], task['revision'],
+                    {'state': 'unknown', 'summary': 'Claude task outcome is unresolved; no retry was sent.'}, 'delivery-unknown')
+            await session.close()
+            await self.notify()
+
+    async def read_turn(self, worker, turn):
+        receipt = self.sessions[worker['id']].results.get(turn['id'])
+        require(receipt is not None and receipt == turn, 'Exact native Claude completion is unavailable')
+        return {'id': turn['id'], 'status': 'completed',
+                'items': [{'type': 'agentMessage', 'text': turn['output']}] +
+                         [{'type': 'toolUse'} for _ in range(turn['toolItems'])],
+                'nativeProof': {'harness': 'claude-desktop', 'sessionId': receipt['nativeSessionId'],
+                                'resultId': receipt['nativeResultId']}}
+
+    async def archive_worker(self, worker):
+        session = self.sessions[worker['id']]
+        result = await session.archive(worker['turnId'])
+        require(session.closed and session.archived, 'Native Desktop worker remains unarchived')
+        return {'nativeRetirement': result}
+
+    def persist(self):
+        # The cloud store owns task/worker state. Never write a Codex execution
+        # policy for Claude or use a second local ledger as an execution fallback.
+        pass