@topolo/cli 0.13.10 → 0.13.12

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

@@ -606,6 +606,12 @@ class BackendProxy:
 
     async def qualify_organization(self,thread_id):
         role=self.execution.roles.get(thread_id) if self.execution else None
+        record=None
+        if role and role.get('dynamicLaneId'):
+            from . import lanes
+            record=lanes.Registry(self.lib.root,'codex').read(role['dynamicLaneId'])
+            if record['plan'].get('continuityTransport')=='native-cli':
+                lanes.native_cli_admission(record['plan']['continuity'])
         if role and not self.permission_configuration and (pathlib.Path(self.runtime)/'permissions-operation.json').exists():
             raise PackError('Unresolved native permission operation requires reconciliation before owned execution or grants')
         if not role or not role.get('installationConsent'):
@@ -635,8 +641,6 @@ class BackendProxy:
             raise PackError('Fresh organization policy prohibits the child-only manual verification profile')
         role['organizationPolicyProof']=proof
         if role.get('dynamicLaneId'):
-            from .lanes import Registry
-            record=Registry(self.lib.root,'codex').read(role['dynamicLaneId'])
             current=await self.dynamic_current(record['plan'])
             configuring=self._lane_configuration_record
             if configuring and configuring['nativeId']==thread_id and self.lane_busy:
@@ -1010,6 +1014,8 @@ class BackendProxy:
         self.lane_idle();store=lanes.Registry(self.lib.root,'codex');record=store.read(params['laneId'])
         if not record or record['state']!='loaded-context-ACK':
             raise PackError('Actual native settings and instruction-source ACK required before bootstrap')
+        if record['plan'].get('continuityTransport')=='native-cli':
+            lanes.native_cli_admission(record['plan']['continuity'])
         current=await self.dynamic_current(record['plan'])
         if current!={k:record['plan'][k] for k in ['role','intake','ceiling']}:
             raise PackError('Current bootstrap source or policy differs')
@@ -1086,6 +1092,8 @@ class BackendProxy:
         self.lane_idle();store=lanes.Registry(self.lib.root,'codex');record=store.read(params['laneId'])
         if not record or record['plan'].get('verificationProfile')!='manual':
             raise PackError('Actual routing proof requires the bound two-child manual verification plan')
+        if record['plan'].get('continuityTransport')=='native-cli':
+            lanes.native_cli_admission(record['plan']['continuity'])
         current=await self.dynamic_current(record['plan'])
         if current!={k:record['plan'][k] for k in ['role','intake','ceiling']}:
             raise PackError('Current source/intake/policy changed before own fixture verification')
@@ -1149,6 +1157,8 @@ class BackendProxy:
         self.lane_idle();store=lanes.Registry(self.lib.root,'codex');planned=store.read_plan(params['laneId'])
         if store.read(params['laneId']) is not None:
             raise PackError('This lane already has an actual native identity')
+        if planned.get('continuityTransport')=='native-cli':
+            lanes.native_cli_admission(planned['continuity'])
         current=await self.dynamic_current(planned)
         if current!={k:planned[k] for k in ['role','intake','ceiling']}:
             raise PackError('Source, intake or policy changed before native creation')
@@ -1202,6 +1212,9 @@ class BackendProxy:
 
     async def dynamic_lane(self, operation, params):
         from . import lanes,task_models,policy
+        requested=params.get('request',params.get('plan',{})) if isinstance(params,dict) else {}
+        if isinstance(requested,dict) and (requested.get('continuityTransport')=='native-cli' or requested.get('schemaVersion')==2 or 'continuity' in requested):
+            lanes.native_cli_admission(requested.get('continuity'))
         self.lane_idle()
         if self.lane_busy:
             raise PackError('An owned dynamic lane operation is already active')
@@ -1254,6 +1267,8 @@ class BackendProxy:
             record=store.read(params['laneId'])
             if not record:
                 raise PackError('No owned dynamic lane registration')
+            if record['plan'].get('continuityTransport')=='native-cli':
+                lanes.native_cli_admission(record['plan']['continuity'])
             current=await self.dynamic_current(record['plan'])
             if current!={k:record['plan'][k] for k in ['role','intake','ceiling']}:
                 raise PackError('Dynamic source, intake or policy drift; no native mutation')
@@ -1973,3 +1988,407 @@ def bind(lib,runtime):
             if backup.exists():raise PackError('Cannot preserve existing desktop-home file: '+name)
             dest.rename(backup)
         dest.symlink_to(expected)
+
+
+def adoption_require(value,message):
+    if not value:raise PackError('Runtime adoption refused: '+message)
+
+
+def adoption_keys(value,keys):
+    adoption_require(isinstance(value,dict) and set(value)==set(keys),'closed fields required: '+','.join(keys))
+
+
+def adoption_json(raw):
+    def unique(pairs):
+        adoption_require(len(pairs)==len({key for key,_ in pairs}),'duplicate JSON fields')
+        return dict(pairs)
+    return json.loads(raw,object_pairs_hook=unique)
+
+
+def adoption_snapshot(path,read=True,missing=False,profile=None):
+    """Single-file custody. Credential profiles use read=False exclusively."""
+    import stat
+    if read and profile is not None:adoption_read_guard(profile,[path])
+    path=pathlib.Path(path)
+    adoption_require(path.is_absolute() and path==path.resolve(),'absolute physical path required')
+    parents=[]
+    for parent in path.parents:
+        st=parent.lstat()
+        adoption_require(stat.S_ISDIR(st.st_mode) and st.st_uid in {0,os.getuid()},'unowned parent')
+        parents.append([str(parent),st.st_dev,st.st_ino])
+    try:st=path.lstat()
+    except FileNotFoundError:
+        adoption_require(missing,'required file absent')
+        return None,None
+    adoption_require(stat.S_ISREG(st.st_mode) and st.st_nlink==1 and st.st_uid==os.getuid(),'owned single regular file required')
+    value={'device':st.st_dev,'inode':st.st_ino,'uid':st.st_uid,'mode':st.st_mode&0o777,
+           'bytes':st.st_size,'mtimeNs':st.st_mtime_ns,'ctimeNs':st.st_ctime_ns,'parents':parents}
+    raw=None
+    if read:
+        adoption_require(st.st_size<=128*1024*1024,'file exceeds limit')
+        fd=os.open(path,os.O_RDONLY|os.O_NOFOLLOW)
+        with os.fdopen(fd,'rb') as stream:
+            opened=os.fstat(stream.fileno())
+            adoption_require((opened.st_dev,opened.st_ino,opened.st_uid,opened.st_mode,opened.st_nlink,opened.st_size,opened.st_mtime_ns,opened.st_ctime_ns)==
+                             (st.st_dev,st.st_ino,st.st_uid,st.st_mode,st.st_nlink,st.st_size,st.st_mtime_ns,st.st_ctime_ns),'file changed before content read')
+            raw=stream.read()
+        after=path.lstat()
+        adoption_require((after.st_dev,after.st_ino,after.st_size,after.st_mtime_ns,after.st_ctime_ns)==
+                         (st.st_dev,st.st_ino,st.st_size,st.st_mtime_ns,st.st_ctime_ns),'file changed while reading')
+        value['sha256']=hashlib.sha256(raw).hexdigest()
+    return value,raw
+
+
+def adoption_pin(value,profile=None):
+    adoption_keys(value,['path','sha256'])
+    snapshot,raw=adoption_snapshot(value['path'],profile=profile)
+    adoption_require(snapshot['sha256']==value['sha256'],'source or preservation pin changed')
+    return raw
+
+
+def adoption_profile(profile):
+    adoption_keys(profile,['path','publicPath','metadata','environment','contextKey','principalId'])
+    adoption_require(profile['environment'] in {'production','staging','development'} and
+                     isinstance(profile['contextKey'],str) and re.fullmatch(r'org:[A-Za-z0-9_-]+',profile['contextKey']) and
+                     isinstance(profile['principalId'],str) and re.fullmatch(r'[A-Za-z0-9_-]+',profile['principalId']), 'explicit private identity tuple required')
+    current,_=adoption_snapshot(profile['path'],read=False)
+    adoption_require(current==profile['metadata'] and current['mode']==0o600,'private profile metadata changed')
+    public,_=adoption_snapshot(profile['publicPath'],read=False,missing=True)
+    adoption_require(profile['path']!=profile['publicPath'] and (public is None or
+                     (public['device'],public['inode'])!=(current['device'],current['inode'])),'private/public profile alias')
+
+
+def adoption_read_guard(profile,paths):
+    """Classify every declared readable input before any non-manifest content read."""
+    adoption_profile(profile)
+    protected=[(str(pathlib.Path(profile[key]).resolve()),adoption_snapshot(profile[key],read=False,missing=True)[0])
+               for key in ['path','publicPath']]
+    for path in paths:
+        current,_=adoption_snapshot(path,read=False,missing=True)
+        adoption_require(all(str(pathlib.Path(path).resolve())!=name and
+                             (current is None or saved is None or (current['device'],current['inode'])!=(saved['device'],saved['inode']))
+                             for name,saved in protected),'readable input aliases protected profile; no contents read')
+
+
+def adoption_runtime_paths(runtime):
+    return [runtime[key]['path'] for key in ['node','cli','mcp']]+[pin['path'] for pin in runtime['cohort'].values()]+[pin['path'] for pin in runtime['adapterFiles']]
+
+
+def adoption_read_inputs(value):
+    paths=[value['ownerGeneration']['path'],*adoption_runtime_paths(value['runtime']),*[pin['path'] for pin in value['preserve']],
+           *[target['path'] for target in value.get('targets',[])]]
+    if 'launcher' in value:paths.append(value['launcher']['path'])
+    adoption_read_guard(value['profile'],paths)
+
+
+def adoption_runtime(runtime,profile):
+    adoption_keys(runtime,['node','cli','mcp','cohort','pythonSource','adapterFiles','osEnvironment'])
+    adoption_read_guard(profile,adoption_runtime_paths(runtime))
+    for key in ['node','cli','mcp']:adoption_pin(runtime[key],profile)
+    adoption_keys(runtime['cohort'],['cli','mcp','sdk'])
+    for key,name,version in [('cli','@topolo/cli','0.13.11'),('mcp','@topolo/mcp','0.14.26'),('sdk','@topolo/sdk','0.23.21')]:
+        package=json.loads(adoption_pin(runtime['cohort'][key],profile))
+        adoption_require(package.get('name')==name and package.get('version')==version,'immutable target cohort differs')
+        if key!='sdk':
+            adoption_require(runtime[key]['path']==str(pathlib.Path(runtime['cohort'][key]['path']).parent/'dist/index.js') and
+                             package.get('dependencies',{}).get('@topolo/sdk')=='0.23.21','entry/dependency cohort differs')
+    source=pathlib.Path(runtime['pythonSource'])
+    adoption_require(source.is_absolute() and source==source.resolve(),'physical adapter source required')
+    adoption_require(isinstance(runtime['adapterFiles'],list) and len(runtime['adapterFiles'])==3 and
+                     {p['path'] for p in runtime['adapterFiles']}=={str(source/'topolo_agent_pack'/n) for n in ['cli.py','live.py','topolo.py']},'exact successor adapter source pins required')
+    for value in runtime['adapterFiles']:adoption_pin(value,profile)
+    env=runtime['osEnvironment']
+    adoption_require(isinstance(env,dict) and {'HOME','PATH'}<=set(env)<=
+                     {'HOME','PATH','USER','LOGNAME','LANG','LC_ALL','TMPDIR'} and
+                     all(isinstance(v,str) and v and len(v)<=4096 and not any(ord(c)<32 for c in v) for v in env.values()),'closed nonsecret OS environment required')
+    env=dict(env)
+    env.update(TOPOLO_CONFIG_PATH=profile['path'],TOPOLO_ENV=profile['environment'],TOPOLO_CONTEXT=profile['contextKey'],
+               TOPOLO_API_KEY='',TOPOLO_ACCESS_TOKEN='')
+    prefix='TOPOLO_'+profile['environment'].upper()
+    env.update({prefix+'_API_KEY':'',prefix+'_ACCESS_TOKEN':''})
+    return env
+
+
+def adoption_alias(alias,target):
+    adoption_keys(alias,['path','linkTarget','metadata']);p=pathlib.Path(alias['path']);st=p.lstat()
+    value=[st.st_dev,st.st_ino,st.st_uid,st.st_mode,st.st_size,st.st_mtime_ns,st.st_ctime_ns]
+    adoption_require(p.is_symlink() and os.readlink(p)==alias['linkTarget'] and str(p.resolve())==target and
+                     st.st_uid==os.getuid() and value==alias['metadata'],'shared alias changed')
+
+
+def adoption_config(raw,target,mcp_launcher):
+    """Registration-only transform; never installs skills or rewrites context."""
+    import tomllib
+    adoption_require(target['format'] in {'json','toml'} and target['rootKey'] in {'mcp_servers','mcpServers'},'unsupported configuration format')
+    config=adoption_json(raw) if target['format']=='json' else tomllib.loads(raw.decode())
+    servers=config.get(target['rootKey'])
+    adoption_require(isinstance(servers,dict),'existing server map required')
+    names=[v['name'] for v in target['transports']]
+    adoption_require(isinstance(target['untouchedServers'],list) and all(isinstance(n,str) for n in target['untouchedServers']) and
+                     len(set(target['untouchedServers']))==len(target['untouchedServers']) and
+                     not set(names)&set(target['untouchedServers']) and set(servers)==set(names)|set(target['untouchedServers']), 'incomplete physical server map')
+    for transport in target['transports']:
+        name=transport['name']
+        adoption_require(isinstance(name,str) and re.fullmatch(r'[A-Za-z0-9_-]+',name) and isinstance(servers.get(name),dict),'unambiguous existing local transport required')
+        entry=servers[name]
+        adoption_require(isinstance(entry.get('command'),str) and 'url' not in entry and 'env_vars' not in entry,'local explicit transport required')
+        adoption_require(not entry.get('env',{}).get('TOPOLO_AGENT_INSTALLATION_ID'),'installation mode requires a separate explicit adoption')
+        agent=entry.get('env',{}).get('TOPOLO_AGENT_NAME','')
+        adoption_require(isinstance(agent,str) and (not agent or re.fullmatch(r'[A-Za-z0-9_-]+',agent)),'agent name differs')
+        entry['command']=mcp_launcher;entry['args']=[agent] if agent else [];entry['env']={'TOPOLO_AGENT_NAME':agent} if agent else {}
+    if target['format']=='json':return (json.dumps(config,indent=2)+'\n').encode()
+    text=raw.decode()
+    for transport in target['transports']:
+        name=transport['name'];entry=servers[name]
+        # Qualified simple tables only. Quoted/dotted/array-table variants refuse;
+        # they cannot silently coexist with a new duplicate registration.
+        section='[mcp_servers.'+name+']';environment='[mcp_servers.'+name+'.env]'
+        adoption_require(target['rootKey']=='mcp_servers' and text.splitlines().count(section)==1 and
+                         text.splitlines().count(environment)<=1,'unsupported TOML registration layout')
+        kept=[];skipping=False
+        for line in text.splitlines():
+            if line.strip() in {section,environment}:skipping=True
+            elif line.lstrip().startswith('['):
+                adoption_require(not line.strip().startswith('[mcp_servers.'+name+'.'),'unsupported nested transport table')
+                skipping=False
+            if not skipping:kept.append(line)
+        values=[]
+        for key,value in entry.items():
+            if key=='env':continue
+            adoption_require(re.fullmatch(r'[A-Za-z0-9_-]+',key) and
+                             (isinstance(value,(str,bool,int)) or isinstance(value,list) and all(isinstance(v,str) for v in value)), 'unsupported TOML transport value')
+            values.append(key+' = '+json.dumps(value))
+        text='\n'.join(kept).rstrip()+'\n\n'+section+'\n'+'\n'.join(values)+'\n\n'+environment+'\n'+\
+             '\n'.join(key+' = '+json.dumps(value) for key,value in entry['env'].items())+'\n'
+    adoption_require(tomllib.loads(text)==config,'TOML semantic preservation differs')
+    return text.encode()
+
+
+def adoption_bootstrap(source,descriptor,runtime):
+    """Check successor bytes before importing them, including the verifier itself."""
+    pins=[(p['path'],p['sha256']) for p in runtime['runtime']['adapterFiles']]
+    pins.append((str(descriptor),hashlib.sha256(canonical(runtime)+b'\n').hexdigest()))
+    return 'import hashlib,os,pathlib,stat,sys\nsys.dont_write_bytecode=True\nfor name,digest in '+repr(pins)+':\n'+\
+        ' p=pathlib.Path(name);s=p.lstat()\n'+\
+        ' if p!=p.resolve() or not stat.S_ISREG(s.st_mode) or s.st_uid!=os.getuid() or s.st_nlink!=1:raise SystemExit("Runtime source custody changed")\n'+\
+        ' with p.open("rb") as f: actual=hashlib.file_digest(f,"sha256").hexdigest()\n'+\
+        ' if actual!=digest:raise SystemExit("Runtime source changed before import")\n'+\
+        'sys.path.insert(0,'+repr(source)+')\n'
+
+
+def adoption_known_launcher(raw,root,profile=None):
+    import ast
+    lines=raw.decode().splitlines();tail=['from topolo_agent_pack.live import proxy_main','raise SystemExit(proxy_main())']
+    if len(lines)==5 and lines[1]=='import sys' and lines[2].startswith('sys.path.insert(0,'):
+        return lines[0].startswith('#!/') and lines[-2:]==tail
+    assignments=[line for line in lines if line.startswith('os.environ["TOPOLO_AGENT_PACK_RUNTIME"]=')]
+    if len(assignments)!=1:return False
+    descriptor=pathlib.Path(ast.literal_eval(assignments[0].split('=',1)[1]))
+    adoption_require(descriptor.parent==root/'launchers' and descriptor.name.startswith('private-runtime-'),'unknown managed launcher descriptor')
+    _,value=adoption_snapshot(descriptor,profile=profile);runtime=json.loads(value)
+    expected=lines[0]+'\n'+adoption_bootstrap(runtime['runtime']['pythonSource'],descriptor,runtime)+assignments[0]+'\n'+'\n'.join(tail)+'\n'
+    return raw==expected.encode()
+
+
+def adoption_preflight(store,manifest):
+    adoption_keys(manifest,['schemaVersion','operationId','library','ownerGeneration','consumers','profile','runtime','targets','launcher','preserve'])
+    root=pathlib.Path(store)
+    adoption_require(manifest['schemaVersion']==1 and type(manifest['schemaVersion']) is int and
+                     isinstance(manifest['operationId'],str) and re.fullmatch(r'[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}',manifest['operationId']) and
+                     root.is_absolute() and str(root)==manifest['library'] and root==root.resolve() and root.stat().st_uid==os.getuid(),'owned library/operation required')
+    def inside(path):
+        adoption_require(pathlib.Path(path).is_relative_to(root),'destination outside owned library')
+    adoption_read_inputs(manifest)
+    inside(manifest['ownerGeneration']['path']);adoption_pin(manifest['ownerGeneration'],manifest['profile'])
+    consumers=manifest['consumers']
+    adoption_require(isinstance(consumers,list) and 1<=len(consumers)<=256 and all(isinstance(c,str) and c for c in consumers) and len(set(consumers))==len(consumers),'closed unique consumer set required')
+    adoption_profile(manifest['profile']);adoption_runtime(manifest['runtime'],manifest['profile'])
+    descriptor=root/'launchers'/('private-runtime-'+manifest['operationId']+'.json')
+    mcp_launcher=root/'launchers'/('private-mcp-'+manifest['operationId'])
+    adoption_require(isinstance(manifest['preserve'],list) and 1<=len(manifest['preserve'])<=2048,'preservation pins required')
+    for value in manifest['preserve']:inside(value['path']);adoption_pin(value,manifest['profile'])
+    targets=manifest['targets'];adoption_require(isinstance(targets,list) and 1<=len(targets)<=256,'nonempty effective transport targets required')
+    writes=[];seen=set();pairs=set()
+    for target in targets:
+        adoption_keys(target,['path','before','aliases','format','rootKey','consumers','transports','untouchedServers'])
+        inside(target['path']);before,raw=adoption_snapshot(target['path'],profile=manifest['profile'])
+        adoption_require(before==target['before'] and target['path'] not in seen,'target preimage changed or duplicated')
+        seen.add(target['path'])
+        adoption_require(isinstance(target['consumers'],list) and target['consumers'] and set(target['consumers'])<=set(consumers),'out-of-scope shared consumer')
+        for alias in target['aliases']:
+            inside(alias['path']);adoption_alias(alias,target['path'])
+        adoption_require(isinstance(target['transports'],list) and target['transports'],'effective transport rows required')
+        for transport in target['transports']:
+            adoption_keys(transport,['name','origin','consumers'])
+            pair=(target['path'],transport['name'])
+            adoption_require(pair not in pairs and transport['origin']==target['path'] and isinstance(transport['consumers'],list) and
+                             transport['consumers'] and set(transport['consumers'])<=set(target['consumers']),'transport origin/consumer/precedence conflict')
+            pairs.add(pair)
+        writes.append((target['path'],before,adoption_config(raw,target,str(mcp_launcher))))
+    adoption_require(set(consumers)=={c for t in targets for v in t['transports'] for c in v['consumers']},'incomplete effective consumer manifest')
+    launcher=manifest['launcher'];adoption_keys(launcher,['path','before'])
+    adoption_require(launcher['path']==str(root/'launchers/topolo-agent-pack-backend') and launcher['path'] not in seen,'exact owned launcher required')
+    before,raw=adoption_snapshot(launcher['path'],profile=manifest['profile']);adoption_require(before==launcher['before'],'launcher preimage changed')
+    lines=raw.decode().splitlines()
+    adoption_require(adoption_known_launcher(raw,root,manifest['profile']),'unrecognized launcher source')
+    current,_=adoption_snapshot(descriptor,missing=True,profile=manifest['profile']);adoption_require(current is None,'runtime descriptor already exists; reconcile without replay')
+    current,_=adoption_snapshot(mcp_launcher,missing=True,profile=manifest['profile']);adoption_require(current is None,'MCP launcher already exists; reconcile without replay')
+    runtime={'schemaVersion':1,'library':str(root),'ownerGeneration':manifest['ownerGeneration'],'profile':manifest['profile'],
+             'runtime':manifest['runtime'],'preserve':manifest['preserve']}
+    writes.append((str(descriptor),None,canonical(runtime)+b'\n'))
+    source=manifest['runtime']['pythonSource']
+    adoption_require(' ' not in lines[0],'MCP wrapper requires an absolute Python shebang without flags')
+    mcp_code=lines[0]+' -I\n'+adoption_bootstrap(source,descriptor,runtime)+'from topolo_agent_pack.topolo import managed_mcp_main\nraise SystemExit(managed_mcp_main('+repr(str(descriptor))+',sys.argv[1:]))\n'
+    writes.append((str(mcp_launcher),None,mcp_code.encode()))
+    code=lines[0]+'\n'+adoption_bootstrap(source,descriptor,runtime)+'os.environ["TOPOLO_AGENT_PACK_RUNTIME"]='+repr(str(descriptor))+'\nfrom topolo_agent_pack.live import proxy_main\nraise SystemExit(proxy_main())\n'
+    writes.append((launcher['path'],before,code.encode()))
+    protected={manifest['profile']['path'],manifest['profile']['publicPath'],manifest['ownerGeneration']['path'],*[p['path'] for p in manifest['preserve']]}
+    protected.update(pin['path'] for pin in [manifest['runtime'][k] for k in ['node','cli','mcp']]+
+                     list(manifest['runtime']['cohort'].values())+manifest['runtime']['adapterFiles'])
+    adoption_require(not protected&{p for p,_,_ in writes},'destination overlaps protected profile/generation/context')
+    return writes
+
+
+def private_runtime_adoption(store,manifest_path,operation,plan_digest=None,confirm=False):
+    try:return _private_runtime_adoption(store,manifest_path,operation,plan_digest,confirm)
+    except (KeyError,TypeError,AttributeError,SyntaxError,UnicodeError) as error:
+        raise PackError('Runtime adoption refused: malformed typed manifest or owned launcher') from error
+
+
+def _private_runtime_adoption(store,manifest_path,operation,plan_digest=None,confirm=False):
+    """Owner-reviewed configuration transaction, NOT native/Auth admission.
+
+    The closed manifest is the owner's effect scope. It does not certify a native
+    inventory, current grants, health, startup or a successful tool result.
+    """
+    adoption_require(operation in {'plan','apply'} and (operation=='apply' and confirm is True and
+                     isinstance(plan_digest,str) and re.fullmatch(r'[a-f0-9]{64}',plan_digest) or
+                     operation=='plan' and plan_digest is None and confirm is False),'closed plan/confirmed apply required')
+    manifest_before,raw=adoption_snapshot(manifest_path);adoption_require(len(raw)<=2*1024*1024,'manifest exceeds limit')
+    manifest=adoption_json(raw);writes=adoption_preflight(store,manifest)
+    journal=pathlib.Path(store)/'launchers'/('adoption-'+manifest['operationId']+'.json')
+    adoption_read_guard(manifest['profile'],[journal,*[p+'.'+manifest['operationId']+'.tmp' for p,_,_ in writes]])
+    adoption_require(not journal.exists() and not journal.is_symlink(),'operation already reserved; reconcile without replay')
+    plan={'schemaVersion':1,'operationId':manifest['operationId'],'manifestDigest':hashlib.sha256(raw).hexdigest(),
+          'writes':[{'path':p,'before':before,'afterDigest':hashlib.sha256(value).hexdigest()} for p,before,value in writes],
+          'claim':'CONFIGURATION_ONLY_NO_NATIVE_IDENTITY_HEALTH_PERMISSION_OR_ADOPTION_ACK'}
+    digest=hashlib.sha256(canonical(plan)).hexdigest()
+    if operation=='plan':return {**plan,'planDigest':digest}
+    adoption_require(digest==plan_digest,'reviewed plan changed')
+    profile=manifest['profile']
+    adoption_require(adoption_snapshot(manifest_path,profile=profile)[0]==manifest_before,'manifest changed before reservation')
+    from contextlib import ExitStack
+    with ExitStack() as custody:
+        parent_fd=os.open(journal.parent,os.O_RDONLY|os.O_DIRECTORY|os.O_NOFOLLOW);custody.callback(os.close,parent_fd)
+        fd=os.open(journal.name,os.O_RDWR|os.O_CREAT|os.O_EXCL|os.O_NOFOLLOW,0o600,dir_fd=parent_fd);custody.callback(os.close,fd)
+        def generation(st):
+            return (st.st_dev,st.st_ino,st.st_uid,st.st_mode,st.st_nlink,st.st_size,st.st_mtime_ns,st.st_ctime_ns)
+        def parent_identity(st):
+            return (st.st_dev,st.st_ino,st.st_uid,st.st_mode)
+        parent_generation=parent_identity(os.fstat(parent_fd));journal_generation=generation(os.fstat(fd))
+        journal_parents=adoption_snapshot(journal,read=False)[0]['parents']
+        record={'operationId':manifest['operationId'],'planDigest':digest,'state':'may-have-config-effects','completed':[]}
+        def journal_guard():
+            try:
+                current=adoption_snapshot(journal,read=False)[0];held=generation(os.fstat(fd));named=generation(journal.lstat())
+                parent=parent_identity(os.fstat(parent_fd));named_parent=parent_identity(journal.parent.lstat())
+            except OSError as error:
+                raise PackError('Runtime adoption refused: journal custody changed; may have config effects; retain evidence') from error
+            adoption_require(held==named==journal_generation and held[4]==1 and current['mode']==0o600 and
+                             parent==named_parent==parent_generation and current['parents']==journal_parents,
+                             'journal custody changed; may have config effects; retain evidence')
+        def checkpoint():
+            nonlocal journal_generation
+            journal_guard();data=canonical(record)+b'\n'
+            os.lseek(fd,0,os.SEEK_SET);os.ftruncate(fd,0)
+            adoption_require(os.write(fd,data)==len(data),'journal checkpoint incomplete; retain evidence');os.fsync(fd)
+            os.lseek(fd,0,os.SEEK_SET)
+            adoption_require(os.read(fd,len(data)+1)==data,'journal checkpoint differs; retain evidence')
+            updated=generation(os.fstat(fd))
+            adoption_require(updated[:5]==journal_generation[:5],'journal descriptor generation changed; retain evidence')
+            journal_generation=updated;journal_guard()
+        def revalidate():
+            adoption_read_inputs(manifest)
+            adoption_pin(manifest['ownerGeneration'],profile);adoption_profile(profile);adoption_runtime(manifest['runtime'],profile)
+            for keep in manifest['preserve']:adoption_pin(keep,profile)
+            for completed in record['completed']:adoption_require(adoption_snapshot(completed['path'],profile=profile)[0]==completed['after'],'completed file changed')
+            for target in manifest['targets']:
+                for alias in target['aliases']:adoption_alias(alias,target['path'])
+            adoption_require(adoption_snapshot(manifest_path,profile=profile)[0]==manifest_before,'manifest changed during apply')
+            journal_guard()
+        checkpoint()
+        # Recheck the whole completed set at both sides of each replacement,
+        # including the last launcher; prepared is never inferred from one file.
+        for path,before,value in writes:
+            revalidate()
+            current,_=adoption_snapshot(path,missing=True,profile=profile);adoption_require(current==before,'destination changed before write')
+            temporary=path+'.'+manifest['operationId']+'.tmp'
+            mode=before['mode'] if before else (0o700 if path.endswith('/private-mcp-'+manifest['operationId']) else 0o600)
+            adoption_read_guard(profile,[temporary])
+            handle=os.open(temporary,os.O_WRONLY|os.O_CREAT|os.O_EXCL|os.O_NOFOLLOW,mode)
+            with os.fdopen(handle,'wb') as stream:
+                temporary_identity=os.fstat(stream.fileno());os.fchmod(stream.fileno(),mode)
+                stream.write(value);stream.flush();os.fsync(stream.fileno())
+            revalidate()
+            temp,actual=adoption_snapshot(temporary,profile=profile)
+            adoption_require((temp['device'],temp['inode'])==(temporary_identity.st_dev,temporary_identity.st_ino) and actual==value,'temporary custody changed; retain journal')
+            adoption_require(adoption_snapshot(manifest_path,profile=profile)[0]==manifest_before,'manifest changed during apply')
+            current,_=adoption_snapshot(path,missing=True,profile=profile);adoption_require(current==before,'destination changed during write; retained temp and journal')
+            journal_guard();os.replace(temporary,path)
+            after,actual=adoption_snapshot(path,profile=profile);adoption_require(actual==value,'afterimage differs; retain journal')
+            record['completed'].append({'path':path,'after':after});revalidate();checkpoint()
+        revalidate();record['state']='configuration-prepared-native-adoption-unverified';checkpoint();journal_guard()
+    return {'operationId':manifest['operationId'],'planDigest':digest,'state':record['state'],'journal':str(journal),'nativeACK':False}
+
+
+def compile_native_cli_command(value,store,pack,input_path,environment):
+    """Compile a fixed native tool command; no shell/model text is accepted."""
+    import shlex
+    from . import lanes
+    value=lanes.native_cli_input(value)
+    allowed={'HOME','USER','LOGNAME','PATH','LANG','LC_ALL','TMPDIR','TOPOLO_CONFIG_PATH','TOPOLO_ENV','TOPOLO_CONTEXT'}
+    if (not isinstance(environment,dict) or not set(environment)<=allowed or
+            any(not isinstance(v,str) or len(v)>4096 or any(ord(c)<32 for c in v) for v in environment.values()) or
+            not environment.get('TOPOLO_CONFIG_PATH') or not pathlib.Path(environment['TOPOLO_CONFIG_PATH']).is_absolute() or
+            environment.get('TOPOLO_ENV')!=value['context']['environment'] or environment.get('TOPOLO_CONTEXT')!=value['context']['contextKey']):
+        raise PackError('Exact child-only native-cli environment required; inherited credentials are forbidden')
+    if any(not pathlib.Path(p).is_absolute() for p in [store,input_path]) or pack!=value['sourceRoleKey'].split('/')[0]:
+        raise PackError('Exact owned store, pack and input references required')
+    argv=['/usr/bin/env','-i',*[k+'='+environment[k] for k in sorted(environment)],value['cli']['nodeExecutable'],value['cli']['entry'],
+        'agent-packs','--store',str(store),'remote-context',pack,'--environment',value['context']['environment'],
+        '--context-key',value['context']['contextKey'],'--role',value['context']['logicalId'],'--continuity-input',str(input_path)]
+    return shlex.join(argv)
+
+
+def native_cli_codex_tool_proof(value,command,result,turn_id,cwd,guide_command,guide_digest):
+    """Verify actual owned Codex tool DTOs; printed/foreign receipts do not ACK."""
+    import shlex
+    from . import lanes
+    value=lanes.native_cli_input(value);lanes.native_cli_hash(guide_digest)
+    if guide_digest!=value['source']['charterDigest']:
+        raise PackError('Native-cli actual charter read differs from the pinned receipt source')
+    thread=result.get('thread',{});turns=[t for t in thread.get('turns',[]) if t.get('id')==turn_id]
+    if (thread.get('id')!=value['nativeId'] or thread.get('cwd')!=str(cwd) or len(turns)!=1 or
+            turns[0].get('status')!='completed' or turns[0].get('error')):
+        raise PackError('Exact same-child native-cli turn/cwd completion required')
+    receipts=[];reads=[]
+    for item in turns[0].get('items',[]):
+        if item.get('type')!='commandExecution' or item.get('status')!='completed' or type(item.get('exitCode'))is not int or item['exitCode']!=0 or not item.get('id'):
+            continue
+        actual=item.get('command');args=shlex.split(actual) if isinstance(actual,str) else []
+        unwrapped=args[2] if len(args)==3 and args[0] in {'/bin/sh','/bin/bash','/bin/zsh'} and args[1]=='-c' else actual
+        if unwrapped==guide_command and hashlib.sha256(item.get('aggregatedOutput','').encode()).hexdigest()==guide_digest:
+            reads.append(item['id'])
+        if unwrapped!=command:
+            continue
+        try:
+            receipt=json.loads(item.get('aggregatedOutput',''))
+        except (ValueError,TypeError):
+            continue
+        receipt=lanes.native_cli_receipt(value,receipt);receipts.append((item['id'],receipt))
+    if len(receipts)!=1 or len(reads)!=1 or receipts[0][0]==reads[0]:
+        raise PackError('Actual native-cli command/receipt and own charter read require unique successful tool results')
+    identity,receipt=receipts[0]
+    proof={'harness':'codex','nativeId':value['nativeId'],'generation':value['nativeConnectionGeneration'],'turnId':turn_id,
+        'itemId':identity,'commandDigest':lanes.digest(command),'exitCode':0,'receiptDigest':lanes.digest(receipt)}
+    return {'receipt':receipt,'proof':proof,'nativeCharterReadItemId':reads[0]}