@topolo/cli 0.13.17 → 0.13.21

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

@@ -0,0 +1,101 @@
+"""Native Claude task-profile definitions, not persistent worker sessions."""
+import argparse
+import hashlib
+import json
+import pathlib
+from .storage import PackError, atomic_json
+from .task_models import default_configuration, _selection
+
+DISCIPLINES = {
+ 'queue-recovery': 'Reconcile existing intents, dependencies, queue age, leases and uncertain effects. Preserve ownership. Never clear holds or replay operations without verified reconciliation.',
+ 'runner-capacity': 'Diagnose runner eligibility, architecture, admission, locking, utilisation and accepted job evidence. Do not change capacities or restart services without the task authority.',
+ 'pipeline-engineering': 'Diagnose and repair assigned validation, caching, artifact, provenance or scheduler defects in an isolated dev worktree. Follow the normal review and release process.',
+ 'promotion-deployment': 'Advance explicitly eligible existing intents through DEV, STG and PROD using the owning release controller. Verify exact SHA and artifact custody. Never create duplicate handoffs or bypass a train.',
+ 'release-verification': 'Independently inspect exact release intent, deployment revision and actual environment proof. Do not implement source changes or perform deployment effects during verification.'}
+PROFILES = {'trivial': ('claude-haiku-5-5','low'), 'routine': ('claude-sonnet-5-5','low'), 'standard': ('claude-sonnet-5-5','medium'), 'deep': ('claude-opus-5-5','high')}
+RELEASE_RISK_TYPES = frozenset({'production-deployment','effect-reconciliation','signing-custody','concurrency-repair'})
+COMMON = '''Execute only the bounded assignment, then return its checkpoint and stop. Do not spawn other agents, resume old workers, create schedules or send peer messages. Topolo Agent contains reusable specialization only. Load current task context from the referenced Topolo Docs/Bytes packet, preserving canonical task, intent, owner and effect identities. An empty local workspace grants no permission to repeat work. Local task packets are disposable caches. Refuse missing context or unresolved effects; never silently invent completion. Record outcome, next action and evidence in the existing task/GUI through supported mechanisms. A missing cloud or feed capability is a blocker, not permission to substitute chat history. No production mutation is authorized by this definition alone.'''
+from .coordinator_context import CONTRACT as COORDINATOR
+
+def definitions():
+ result={}
+ for discipline,prompt in DISCIPLINES.items():
+  for profile,(model,effort) in PROFILES.items():
+   name='cicd-'+discipline+'-'+profile
+   result[name]={'description':discipline+'; '+profile+' task profile. Select using context/CICD-DISPATCH.md.', 'model':model,'effort':effort,'maxTurns':24,'permissionMode':'bypassPermissions','disallowedTools':['Agent'],'prompt':prompt+'\n\n'+COMMON}
+   if profile=='trivial':result[name]['tools']=['Read','Glob','Grep']
+ return result
+
+def select(discipline,task):
+ if discipline not in DISCIPLINES:
+     raise PackError('Unknown CI/CD discipline')
+ config=default_configuration();constraints={'allowedModels':sorted({v[0] for v in PROFILES.values()}),'allowedEfforts':['low','medium','high']}
+ selection=_selection(config,task,'claude',constraints)
+ if task['type'] in RELEASE_RISK_TYPES and selection['rule']['profile']!='deep':
+  raise PackError('Release-risk tasks require a deep profile')
+ return 'cicd-'+discipline+'-'+selection['rule']['profile']
+
+def install(workspace):
+ workspace=pathlib.Path(workspace).expanduser().resolve()
+ if not (workspace/'CLAUDE.md').is_file():
+     raise PackError('Existing coordinator CLAUDE.md required')
+ rows=definitions(); files={}
+ for name,row in rows.items():
+  header={k:v for k,v in row.items() if k!='prompt'};header={'name':name,**header}
+  # JSON values are valid YAML scalars and avoid implicit YAML conversions.
+  body='---\n'+'\n'.join(k+': '+json.dumps(v) for k,v in header.items())+'\n---\n\n'+row['prompt']+'\n'
+  files[workspace/'.claude/agents'/(name+'.md')]=body
+ guide='''# CI/CD dispatch contract
+
+Use one fresh native Agent invocation per bounded task. Never resume a completed worker. These files are reusable templates, not sidebar sessions. Select the discipline and task profile before dispatch; pass task identity, canonical Docs/Bytes references, current owner, exact release intent, scope, acceptance and effect authority in the invocation. If an existing owner holds the task, reconcile rather than replace them.
+
+Task profiles: trivial = Haiku 5.5 low, only low-risk format/extract-fields/reference-lookup/status-read; routine = Sonnet 5.5 low; standard = Sonnet 5.5 medium; complex or security-critical = Opus 5.5 high. Ordinary implementation is never trivial. Production effects, uncertain recovery, signing/custody and concurrency require deep. Choose the matching cicd-<discipline>-<profile> subagent_type; do not override its model or inherit the coordinator effort. Native model rejection is a visible blocker, never a silent fallback.
+
+Disciplines: queue-recovery, runner-capacity, pipeline-engineering, promotion-deployment, release-verification. For simple read-only status extraction use queue-recovery-trivial. Before mutations read the current owning controller records, current signed authority and unresolved operations. Do not duplicate existing intents. Independent release verification uses a fresh release-verification worker. Completed model turns do not prove delivery.
+
+Dispatch may run independent bounded tasks concurrently subject to current admitted capacity and disjoint ownership. Coordinator remains available for human input. Publish each meaningful checkpoint once to the existing canonical task and GUI; missing platform persistence or dispatch must be reported explicitly. Do not claim cross-machine duplicate protection from a local lock.
+'''
+ files[workspace/'context/CICD-DISPATCH.md']=guide
+ # Reject unowned conflicting files before any write.
+ receipt_path=workspace/'.claude/cicd-installation.json'
+ prior=json.loads(receipt_path.read_text()) if receipt_path.exists() else {'files':{}}
+ for path,body in files.items():
+  if path.is_symlink():
+      raise PackError('Symlinked CI/CD definition')
+  if path.exists() and path.read_text()!=body and hashlib.sha256(path.read_bytes()).hexdigest()!=prior['files'].get(str(path.relative_to(workspace))):
+      raise PackError('Changed definition requires reconciliation: '+str(path))
+ for path,body in files.items():path.parent.mkdir(parents=True,exist_ok=True);path.write_text(body);path.chmod(0o600)
+ marker='\n\n## Native CI/CD specialist dispatch\nRead context/CICD-DISPATCH.md before assigning release work. Use the project cicd-* native subagents with explicit task profiles.\n'
+ charter=workspace/'CLAUDE.md'
+ # Older generated coordinators accidentally carried the worker-only contract.
+ # Replace only that exact known prefix; preserve the remaining role charter.
+ body=charter.read_text()
+ if body.startswith(COMMON):
+  charter.write_text(COORDINATOR+body[len(COMMON):])
+ if marker not in charter.read_text():
+  with charter.open('a') as stream:stream.write(marker)
+ receipt={'format':'topolo-cicd-specialists','schemaVersion':1,'profiles':PROFILES,'files':{str(p.relative_to(workspace)):hashlib.sha256(p.read_bytes()).hexdigest() for p in files},'workersCreated':0,'activationVerified':False}
+ atomic_json(receipt_path,receipt);return receipt
+
+def main():
+ parser=argparse.ArgumentParser();sub=parser.add_subparsers(dest='action',required=True)
+ p=sub.add_parser('install');p.add_argument('workspace')
+ p=sub.add_parser('select');p.add_argument('discipline',choices=DISCIPLINES);p.add_argument('--task',required=True)
+ args=parser.parse_args();print(json.dumps(install(args.workspace) if args.action=='install' else {'subagent':select(args.discipline,json.loads(args.task))},indent=2))
+
+
+def configure_profile(config):
+    """Set the pack-owned user scope; project scope cannot enable bypass."""
+    config=pathlib.Path(config).expanduser().resolve()
+    config.mkdir(parents=True,exist_ok=True,mode=0o700)
+    path=config/'settings.json'
+    if path.is_symlink():
+        raise PackError('Symlinked Claude user settings')
+    settings=json.loads(path.read_text()) if path.exists() else {}
+    settings.setdefault('permissions',{})['defaultMode']='bypassPermissions'
+    settings['model']='claude-sonnet-5-5'
+    settings.setdefault('modelSettings',{}).setdefault('claude-sonnet-5-5',{})['effortLevel']='low'
+    atomic_json(path,settings)
+    return {'path':str(path),'settingsReadback':json.loads(path.read_text()),'existingDesktopSessionsVerified':False}
+
+if __name__=='__main__':main()

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

@@ -10,6 +10,7 @@ import json
 import os
 import pathlib
 import pty
+import re
 import select as io_select
 import shutil
 import subprocess
@@ -28,19 +29,21 @@ def find_binary():
     return shutil.which('claude')
 
 
-def handoff(binary, directory, session_id):
+def handoff(binary, directory, session_id, env=None):
     """Native --desktop requires a TTY. No prompt, model call or shell is used."""
     if not binary:
         raise PackError('Claude Code 2.1.285+ is required; install Claude Desktop or Claude Code.')
     version = subprocess.run([binary, '--version'], capture_output=True, text=True, timeout=10)
-    if version.returncode or not version.stdout.startswith('2.1.289 '):
-        raise PackError('This native import adapter is qualified for Claude Code 2.1.289; selected binary: ' + version.stdout.strip())
+    release = re.match(r'^(\d+)\.(\d+)\.(\d+)\s+\(Claude Code\)', version.stdout)
+    if version.returncode or release is None or tuple(map(int, release.groups())) < (2, 1, 285):
+        raise PackError('Native import requires the Desktop handoff capability introduced in Claude Code 2.1.285; selected binary: ' + version.stdout.strip())
     master, slave = pty.openpty()
     process = None
     output = bytearray()
     try:
         process = subprocess.Popen([binary, '--desktop', '--resume', session_id],
-                                   cwd=directory, stdin=slave, stdout=slave, stderr=slave)
+                                   cwd=directory, stdin=slave, stdout=slave, stderr=slave,
+                                   **({'env':env} if env is not None else {}))
         os.close(slave)
         slave = None
         deadline = time.monotonic() + 20
@@ -105,6 +108,10 @@ def materialize(lib, name, selected, config):
             if record['sourceRevision'] != revision:
                 raise PackError('Existing Claude agent uses a different revision; build a new named pack to preserve its context.')
             if record['importState'] != 'preparing':
+                if agent['id'] == 'cicd':
+                    from .cicd import install, configure_profile
+                    install(record['workspace'])
+                    configure_profile(config)
                 records.append(record)
                 continue
         else:
@@ -139,12 +146,19 @@ def materialize(lib, name, selected, config):
             if relative.as_posix() == 'AGENTS.md':
                 relative = pathlib.Path('CLAUDE.md')
             write_new(workspace / relative, lib.object(resource['content']).read_bytes())
+        if agent['id'] == 'cicd':
+            from .cicd import install, configure_profile
+            install(workspace)
+            configure_profile(config)
         session_id = record['cliSessionId']
         transcript = pathlib.Path(record['transcript'])
         note = (agent['title'] + '. You are this Topolo Agent Pack role in Claude Desktop. '
                 'Read CLAUDE.md and relevant context/ files before work. '
                 'This is starting context only; no assignment, claim or prior conversation is inherited. '
-                'Await a new human request. Coordination requires human authorization.')
+                'Await a new human request. A human request authorizes the necessary bounded specialist dispatch '
+                'within its scope; do not ask for that authorization again. Preserve existing owners, holds '
+                'and action-specific approval requirements. Use the configured dispatch adapter and canonical '
+                'task records; do not substitute coordinator execution when dispatch is unavailable.')
         rows = [{'parentUuid': None, 'isSidechain': False, 'userType': 'external',
                  'cwd': str(workspace), 'sessionId': session_id, 'version': '2.1.289',
                  'type': 'user', 'message': {'role': 'user', 'content': note},
@@ -214,7 +228,8 @@ def main(argv):
             if args.command in {'status', 'doctor', 'recover', 'list'}:
                 proof = readback(state['agents'], app_data)
                 active_path = lib.root / 'claude/active.json'
-                pending_path = lib.root / 'claude/native-operation.json'
+                pending_path = lib.root / ('claude/startup-operation.json' if
+                    (lib.root / 'claude/startup-operation.json').exists() else 'claude/native-operation.json')
                 result = {**state, 'adoptionProof': proof, 'verifiedAgents': sum(p['verified'] for p in proof),
                           'fullPackSwitchSupported': False, 'sidebarGroupsAndPinsVerified': False,
                           'nativeRecordsRewritten': False, 'modelIdentityResponseVerified': False,
@@ -224,7 +239,7 @@ def main(argv):
                           'nativeRecoveryReplayed': False,
                           'verificationBoundary': 'read-only adoption records; use the explicit native connection for current settings or recovery'}
             else:
-                if (lib.root / 'claude/native-operation.json').exists():
+                if any((lib.root / ('claude/'+name)).exists() for name in ['native-operation.json','startup-operation.json','activation-operation.json','launch-operation.json']):
                     raise PackError('An unresolved native Claude operation blocks imports and preparation. Use topolo agent-packs recover with the explicit native connection; no effects are replayed.')
                 manifest, revision = lib.load(args.source)
                 chosen = select(manifest, args.sets, args.agents)

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

@@ -0,0 +1,157 @@
+"""Read-only cloud and service evidence for the exact installed Desktop roster."""
+import hashlib,json,os,time,fcntl
+from .storage import Library,read_json,PackError,canonical
+from .work import require
+from .cloud_work import CloudStore
+from .work_artifacts import read_checkpoint
+from .claude_service import ensure_running,verify_retired_binding
+from .live import request
+
+
+def observe(root,qualification_task=None,previous=None,connection=None,start_service=False,native_proof=False,wait_retired_service=False,require_native_idle=False,successor_connection=None,warm_connection=None):
+    lib=Library(root);store=CloudStore(root);version,state=store.load()
+    if warm_connection is not None:
+        require(previous is None and connection is None and not start_service and not wait_retired_service and not require_native_idle and not native_proof and qualification_task is None and successor_connection is None,'Warm restore cannot change lifecycle custody')
+        binding=read_json(lib.root/'work/claude-frontdoors.json')
+        require(isinstance(warm_connection,dict) and set(warm_connection)=={'pid','runtime','identity','socket','secretPath'} and binding.get('nativeConnection')==warm_connection and binding.get('desktopPid')==warm_connection['pid'] and warm_connection['runtime']==str(lib.root/'claude/task-runtime'),'Current warm binding differs')
+        ensure_running(lib)
+        service=request(lib,'status',{})
+        require(service.get('harness')=='claude' and service.get('cloudDispatchReady') is True and service.get('desktopPid')==warm_connection['pid'] and service.get('runtime')==warm_connection['runtime'] and isinstance(service.get('activeTurns'),list) and all(isinstance(w,str) for w in service['activeTurns']) and len(set(service['activeTurns']))==len(service['activeTurns']),'Authenticated warm service differs')
+        from .claude_desktop import call
+        status=call(warm_connection,{'kind':'status'})
+        require(status.get('harness')=='claude-desktop' and status.get('pid')==warm_connection['pid'] and status.get('identity')==warm_connection['identity'] and status.get('qualified') is True and type(status.get('workers')) is int and status['workers']>=0,'Qualified warm native control differs')
+        return {'warmOwner':True,'nativeInputsSent':False,'workerCustodyPreserved':True,'service':service,'binding':store.binding}
+    if successor_connection is not None:
+        require(previous is None and connection is None and not start_service and not wait_retired_service and not require_native_idle and not native_proof and qualification_task is None,'Exact successor observation cannot change lifecycle custody')
+        binding=read_json(lib.root/'work/claude-frontdoors.json')
+        require(isinstance(successor_connection,dict) and set(successor_connection)=={'pid','runtime','identity','socket','secretPath'} and binding.get('nativeConnection')==successor_connection and binding.get('desktopPid')==successor_connection['pid'] and successor_connection['runtime']==str(lib.root/'claude/task-runtime'),'Current successor binding differs')
+        try:service=request(lib,'status',{})
+        except (OSError,PackError):return {'existingSuccessor':False,'serviceStarted':False,'nativeInputsSent':False}
+        require(service.get('harness')=='claude' and service.get('cloudDispatchReady') is True and service.get('desktopPid')==successor_connection['pid'] and service.get('runtime')==successor_connection['runtime'] and isinstance(service.get('activeTurns'),list) and all(isinstance(w,str) for w in service['activeTurns']) and len(set(service['activeTurns']))==len(service['activeTurns']),'Authenticated successor service differs; preserve its ownership')
+        from .claude_desktop import call
+        status=call(successor_connection,{'kind':'status'})
+        require(status.get('harness')=='claude-desktop' and status.get('pid')==successor_connection['pid'] and status.get('identity')==successor_connection['identity'] and status.get('qualified') is True and type(status.get('workers')) is int and status['workers']>=0,'Qualified successor native control differs')
+        native=call(successor_connection,{'kind':'frontdoors'})
+        require(native.get('state')=='installed-frontdoors-verified' and native.get('nativeInputsSent') is False,'Native successor front doors differ')
+        return {'existingSuccessor':True,'serviceStarted':False,'workerCustodyPreserved':True,'nativeInputsSent':False,'native':native,'service':service,'binding':store.binding,'versionId':version,'generation':state['generation']}
+    if previous is not None:
+        if connection is not None:
+            verify_retired_binding(lib,previous,connection)
+        else:
+            old=previous['nativeConnection']
+            try:os.kill(old['pid'],0)
+            except ProcessLookupError:pass
+            else:raise ValueError('Previous native owner remains alive')
+            tasks={row[0]:json.loads(row[2]) for row in state['tables']['tasks']}
+            for row in state['tables']['workers']:
+                worker=json.loads(row[2]);cwd=worker.get('nativePlan',{}).get('cwd','')
+                if cwd==old['runtime'] or cwd.startswith(old['runtime']+os.sep):
+                    require(cwd!=old['runtime'] and os.path.normpath(cwd)==cwd,'Ambiguous previous native workspace path')
+                if not cwd.startswith(old['runtime']+os.sep):
+                    if tasks.get(worker['taskId'],{}).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),'Historical worker remains active or UNKNOWN')
+                    continue
+                require(worker.get('resolution',{}).get('harness')=='claude','Previous runtime worker harness custody differs')
+                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')
+                payload=read_checkpoint(store.root,worker['checkpoint'],worker['taskId'],worker['id'],client=store.client);receipt=payload['nativeReceipt']
+                require(payload['phase']==worker['phase'] and receipt['threadId']==worker['nativeId'] and receipt['turnId']==worker['turnId'] and receipt['status'] in {'completed','failed','cancelled'},'Previous terminal checkpoint differs')
+    if wait_retired_service:
+        require(previous is not None,'Exact retired service owner required')
+        for _ in range(50):
+            try:status=request(lib,'status',{})
+            except (OSError,PackError):
+                bridge=read_json(lib.root/'live-bridge.json',{})
+                if bridge:
+                    require(bridge.get('harness')=='claude' and type(bridge.get('pid')) is int and bridge['pid']>1,'Prior service process custody is unverified')
+                    try:os.kill(bridge['pid'],0)
+                    except ProcessLookupError:pass
+                    else:
+                        time.sleep(.1)
+                        continue
+                with (lib.root/'work/claude-service-owner.lock').open('a') as owner:
+                    try:fcntl.flock(owner,fcntl.LOCK_EX|fcntl.LOCK_NB)
+                    except BlockingIOError:pass
+                    else:break
+                time.sleep(.1)
+                continue
+            require(status.get('harness')=='claude' and status.get('desktopPid')==previous['nativeConnection']['pid'],'Another service owns this installation')
+            time.sleep(.1)
+        else:raise ValueError('Previous native service has not finished its owned shutdown')
+    task=None
+    if qualification_task is not None:
+        tasks=[json.loads(row[2]) for row in state['tables']['tasks'] if row[0]==qualification_task]
+        require(len(tasks)==1,'Qualification task is not in the current cloud authority')
+        task=tasks[0]
+        require(task['state']=='completed' and task.get('ownerInstallationId')==store.binding['installationId']
+                and task.get('verification',{}).get('verdict')=='completed','Independent cloud qualification is incomplete or belongs to another installation')
+        workers=[json.loads(row[2]) for row in state['tables']['workers'] if row[1]==qualification_task]
+        attempt=[w for w in workers if w.get('attempt',1)==task.get('attempt',1)]
+        generation=task.get('reviewGeneration',0);history=task.get('reviewHistory',[])
+        require(type(generation) is int and generation>=0 and isinstance(history,list) and len(history)==generation,'Authorized review generation history differs')
+        execution=[w for w in attempt if w['phase']!='review'];reviews=[w for w in attempt if w['phase']=='review']
+        require(len(execution)==2 and {w['phase'] for w in execution}=={'route','execute'} and len(reviews)==generation+1
+                and all(type(w.get('reviewGeneration',0)) is int for w in reviews)
+                and sorted(w.get('reviewGeneration',0) for w in reviews)==list(range(generation+1)),
+                'Original execution and unique authorized review generations are required')
+        latest=next(w for w in reviews if w.get('reviewGeneration',0)==generation)
+        current=execution+[latest];verification_by_worker={latest['id']:task['verification']}
+        require(all(w['state']=='archived' and w.get('nativeArchived') is True for w in attempt)
+                and task['verification'].get('nativeCheckpoint')==latest.get('checkpoint'),
+                'Current Claude qualification phase receipts are incomplete')
+        result=task.get('result',{});executed=next(w for w in execution if w['phase']=='execute')
+        require(result.get('workerId')==executed['id'] and result.get('checkpoint')==executed.get('checkpoint'),'Qualification must preserve the exact original execution result')
+        for index,entry in enumerate(history):
+            rejected=next(w for w in reviews if w.get('reviewGeneration',0)==index)
+            require(isinstance(entry,dict) and set(entry)=={'reviewWorkerId','generation','verification','continuation'}
+                    and type(entry['generation']) is int and entry['generation']==index and entry['reviewWorkerId']==rejected['id']
+                    and isinstance(entry['verification'],dict)
+                    and entry['verification'].get('verdict') in {'blocked','needs_input'}
+                    and entry['verification'].get('nativeCheckpoint')==rejected.get('checkpoint'),
+                    'Prior rejected review identity and checkpoint must remain preserved')
+            continuation=entry['continuation']
+            require(isinstance(continuation,dict) and set(continuation)=={'requestId','taskId','revision','reviewWorkerId','reviewCheckpoint','note'}
+                    and continuation['taskId']==task['id'] and continuation['reviewWorkerId']==rejected['id']
+                    and continuation['reviewCheckpoint']==rejected.get('checkpoint')
+                    and type(continuation['revision']) is int and continuation['revision']<task['revision']
+                    and isinstance(continuation['note'],str) and bool(continuation['note'])
+                    and [continuation['requestId'],hashlib.sha256(canonical(continuation)).hexdigest(),task['id']] in state['tables']['responses'],
+                    'Review continuation must have its exact canonical authorization receipt')
+            verification_by_worker[rejected['id']]=entry['verification']
+        for worker in workers:
+            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'),'Qualification worker closure is unresolved')
+            if worker not in current and worker.get('resolution',{}).get('harness')!='claude':continue
+            payload=read_checkpoint(store.root,worker['checkpoint'],qualification_task,worker['id'],client=store.client)
+            receipt=payload['nativeReceipt']
+            require(payload['phase']==worker['phase'] and receipt['threadId']==worker['nativeId'] and receipt['turnId']==worker['turnId'] and receipt['status'] in {'completed','failed','cancelled'},'Qualification checkpoint identity differs')
+            if worker['id'] in verification_by_worker:
+                expected=verification_by_worker[worker['id']]
+                require(payload.get('outputError') is None and json.loads(payload['output'])=={k:expected[k] for k in ['verdict','summary','evidence']},'Review verification differs from its immutable checkpoint')
+            if worker in current:
+                resolution=worker.get('resolution',{});role=worker.get('roleSource',{})
+                require(receipt['status']=='completed' and resolution.get('harness')=='claude'
+                        and isinstance(resolution.get('nativeACK'),dict) and resolution['nativeACK']==resolution.get('resolved')
+                        and bool(resolution['nativeACK'].get('model')) and bool(resolution['nativeACK'].get('effort'))
+                        and role.get('source')=='topolo-agent-definition' and role.get('rolesLoaded')==1
+                        and role.get('wholePackExportLoaded') is False and role.get('memoryLoaded') is False
+                        and bool(role.get('agentId')) and bool(role.get('instructionsSHA256'))
+                        and payload.get('resolution')==resolution and payload.get('roleSource')==role,
+                        'Current qualification must prove selected Claude Agent context and native settings ACK')
+    native=None
+    if native_proof:
+        from .claude_desktop import call
+        binding=read_json(lib.root/'work/claude-frontdoors.json')
+        if require_native_idle:
+            status=call(binding['nativeConnection'],{'kind':'status'})
+            require(status.get('harness')=='claude-desktop' and status.get('pid')==binding['desktopPid'] and status.get('identity')==binding['nativeConnection']['identity'] and status.get('workers')==0 and status.get('qualified') is True,'Exact idle native control is required')
+        native=call(binding['nativeConnection'],{'kind':'frontdoors'})
+        require(native.get('state')=='installed-frontdoors-verified' and native.get('nativeInputsSent') is False,'Native front doors are unverified')
+    if start_service:ensure_running(lib)
+    service=request(lib,'status',{}) if start_service or qualification_task is not None else None
+    if service is not None:
+        binding=read_json(lib.root/'work/claude-frontdoors.json')
+        require(service.get('harness')=='claude' and service.get('cloudDispatchReady') is True and service.get('desktopPid')==binding['desktopPid'],'Current Claude dispatcher is not ready')
+    return {'native':native,'format':'topolo-claude-cloud-activation-proof-v1','binding':store.binding,'versionId':version,
+            'generation':state['generation'],'qualificationTaskId':qualification_task,
+            'qualificationRevision':task['revision'] if task else None,'service':service,'activated':True}

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']}