@topolo/cli 0.13.11 → 0.13.12

package/README.md

@@ -448,3 +448,13 @@ remain unqualified. Native CLI effects therefore refuse with
 `native_cli_startup_unqualified` before client/helper/native access. Private MCP
 startup retains its existing refusal. Version 1 plans stay readable and do not
 silently become version 2 CLI plans.
+
+### Preserving private pack runtime configuration
+
+`topolo agent-packs --store /owned/AgentPacks runtime-adoption plan --manifest /review/adoption.json` produces a nonwriting configuration plan. Review its physical targets and digest, then use `runtime-adoption apply --manifest /review/adoption.json --plan-digest <sha256> --confirm` for one configuration-only attempt.
+
+The closed owner manifest binds the actual consumer set and effective local Topolo transport origins, physical file preimages, shared aliases, private profile metadata, immutable CLI 0.13.11/MCP 0.14.26/SDK 0.23.21 targets and the separately pinned successor Python adapter. It must include every server in each physical config as either a targeted transport or an explicitly untouched server. Empty or incomplete manifests refuse. The command never installs skills, rebinds a home, changes existing instructions/permissions, starts a consumer or probes Auth.
+
+A successful apply means configuration is prepared. It does not mean existing processes reloaded it, the private account is healthy, permissions were granted or either native harness completed a task. Starting or refreshing consumers is a separate owner-authorized step and can contact private Auth and renew the selected private profile. Public credential-store repair is not a blanket prerequisite for independent private profiles. See [the manifest and effect boundaries](agent-packs/README.md#private-runtime-adoption).
+
+The protocol SDK pin addresses [GHSA-6qxp-vccf-f47h](https://github.com/modelcontextprotocol/typescript-sdk/security/advisories/GHSA-6qxp-vccf-f47h). The CLI doctor's protocol transport is stdio. Separate HTTP OAuth consumers still need appropriate issuer binding for legacy credentials and bundled providers; this source update neither inspects nor migrates credentials.

package/agent-packs/README.md

@@ -699,3 +699,26 @@ contracts are unavailable. Effects stay closed with
 `native_cli_tool_result_unqualified`. Input references, hashes or JSON flags do
 not grant admission. Private MCP is a separate unsupported transport and is never
 a fallback. Source fixtures do not activate either native harness.
+
+## Private runtime adoption
+
+The public CLI forwards `agent-packs runtime-adoption plan|apply` to the bundled successor adapter. `plan` performs no writes. `apply` requires the exact reviewed `--plan-digest` and `--confirm`; it never calls `prepare`, `bind`, `reconnect`, skill installation or a native/Auth client. The selected immutable public CLI/MCP cohort is separate from the successor Python adapter source. Do not edit an installed immutable runtime to add the successor hooks.
+
+The manifest is a local owner-reviewed configuration scope, not native provenance, a permission grant or a health certificate. Its exact top-level fields are:
+
+- `schemaVersion: 1`, a fresh UUID `operationId`, and the absolute physical `library`.
+- `ownerGeneration: {path, sha256}`: the owner's current bounded nonsecret effective-transport/generation record, inside that library. The owner must establish its native currency separately.
+- `consumers`: the complete unique existing native IDs in scope. Target rows must account for every ID; no new native IDs are created.
+- `profile: {path, publicPath, metadata, environment, contextKey, principalId}`: absolute private and public credential-file references, explicit organization context, and metadata only. Files must be physically distinct; the private profile must be owned, single-link, regular and mode 0600. Neither profile's contents are read or hashed. A renewal that changes private file metadata invalidates the descriptor and requires owner reconciliation.
+- `runtime: {node, cli, mcp, cohort, pythonSource, adapterFiles, osEnvironment}`. Each executable/entry and each `cohort` value is `{path, sha256}`. Cohort keys `cli`, `mcp`, `sdk` pin their package JSON; required target versions are 0.13.11, 0.14.26 and 0.23.21. CLI and MCP entries must be their pinned package's `dist/index.js`. `pythonSource` is the physical successor source directory; `adapterFiles` pins its `topolo_agent_pack/{cli,live,topolo}.py`. Verify the complete installed cohort independently before admitting its pins. `osEnvironment` permits only HOME/PATH and optional USER/LOGNAME/LANG/LC_ALL/TMPDIR, with no credential, service-origin, Node or installation overrides.
+- `targets`: one row per unique physical configuration file, with `{path, before, aliases, format, rootKey, consumers, transports, untouchedServers}`. Supported formats are JSON `mcpServers` and simple TOML `mcp_servers` tables. Each transport is `{name, origin, consumers}` and must already exist as a local command; URL, inherited `env_vars`, installation-mode, ambiguous names or unsupported TOML layouts refuse. `origin` is the exact physical file. The complete physical server map must equal the targeted names plus `untouchedServers`. The owner must independently bind all effective native layers; a zero-table query or a guessed server name is insufficient.
+- `launcher: {path, before}`: exactly the owned generated `launchers/topolo-agent-pack-backend`; its interpreter, owner and mode are preserved.
+- `preserve`: nonsecret `{path, sha256}` references to existing roster, model/effort, permission, charter/context, routing and lifecycle records. Include every protected fixed and dynamic record in the approved scope. These may not overlap destinations. No transcript or credential contents belong in a manifest.
+
+A physical `before` snapshot contains `device`, `inode`, `uid`, numeric permission `mode`, `bytes`, `mtimeNs`, `ctimeNs`, `parents` (absolute path/device/inode triples), and `sha256`. Profile `metadata` uses the same shape without `sha256`. Each alias is `{path, linkTarget, metadata}`, where `metadata` is the symlink's device/inode/uid/full mode/size/mtimeNs/ctimeNs tuple. The plan emits actual beforeimages for review; effect admission must independently establish the owner, complete source set, physical sharing and current generation. It cannot silently authorize another consumer sharing a file.
+
+Only existing owned physical destinations inside the library can change. Shared desktop/backend config symlinks remain intact and their common file changes once. The generated private descriptor and isolated Python MCP launcher are operation-specific. The isolated MCP launcher validates successor bytes before import, then current profile/generation/preservation pins before replacing itself with the explicit Node/MCP pair and closed private environment. This retains the native host's PID, stdio and cancellation custody. Existing host agent names are retained as a closed wrapper argument. Managed default helper clients use the exact Node/CLI pair regardless of PATH. Unmanaged clients retain their ordinary behavior. No parent credential/service-origin/installation/Node environment is copied into those Topolo children. An intentional installation credential mode needs its own separately explicit contract.
+
+Apply reserves `launchers/adoption-<UUID>.json` exclusively. The journal starts in `may-have-config-effects`, records each verified replacement, and becomes `configuration-prepared-native-adoption-unverified` only after all readbacks. Every write rechecks generation, source, profile metadata, preservation pins and destination custody. An interrupted or conflicting apply retains the journal and any uncertain temporary file; it never automatically replays or rolls back. Reconcile exact effects with the original owner.
+
+No apply result proves native reload, identity, current RBAC, model/effort, loaded context, original-intake permission routing or a native tool result. Hosts may react to configuration changes; admit the actual affected owner/generation and normal request settlement before applying in a live host. Later ordinary startup can renew the private credential and load identity. A previous 429/403 or scoped recovery hold remains separately applicable and elapsed time grants no retry. Actual Codex and Claude same-query context, permission, nonce result, cancellation/settlement and own retirement require independent native evidence.

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

@@ -290,6 +290,9 @@ def parser():
     p.add_argument('--version',action='version',version=__version__)
     p.add_argument('--store',default=os.environ.get('CODEX_PACK_HOME',str(pathlib.Path.home()/'AgentPacks')))
     sub=p.add_subparsers(dest='command',required=True)
+    q=sub.add_parser('runtime-adoption',help='Configuration-only private runtime plan/apply; no consumer startup or authentication')
+    q.add_argument('operation',choices=['plan','apply']);q.add_argument('--manifest',required=True)
+    q.add_argument('--plan-digest');q.add_argument('--confirm',action='store_true')
     def selection(q):
         q.add_argument('--set',dest='sets',action='append');q.add_argument('--agent',dest='agents',action='append')
     def activation(q):
@@ -374,7 +377,7 @@ def main(argv=None):
     elif command_args and command_args[0].startswith('--store='):command_args=command_args[1:]
     lane_command=bool(command_args and command_args[0]=='lane')
     cloud_command=bool(command_args and command_args[0] in {'connect','remote-context','remember','artifact','artifact-get','remote-recover'})
-    if harness == 'claude' and not policy_command and not cloud_command and not lane_command:
+    if harness == 'claude' and not policy_command and not cloud_command and not lane_command and not (command_args and command_args[0]=='runtime-adoption'):
         from . import claude
         return claude.main(argv)
     if harness not in {'codex', 'claude'}:
@@ -383,6 +386,11 @@ def main(argv=None):
     args=parser().parse_args(argv)
     args.harness=harness
     try:
+        if args.command=='runtime-adoption':
+            if harness!='codex':
+                raise PackError('Runtime adoption is one explicit cross-host owner manifest, not a harness override')
+            emit(live.private_runtime_adoption(args.store,args.manifest,args.operation,args.plan_digest,args.confirm))
+            return 0
         lib=Library(args.store)
         if args.command in {'connect','remote-context','remember','artifact','artifact-get','remote-recover'}:
             from . import topolo

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

@@ -1990,6 +1990,357 @@ def bind(lib,runtime):
         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

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

@@ -5,6 +5,36 @@ from .storage import PackError,atomic_json,canonical,read_json,safe_id
 class ConnectionSourceRefused(PackError):
     pass
 
+def managed_runtime_selection(path):
+    """Configuration custody only, never a health or native permission ACK."""
+    from . import live
+    before,raw=live.adoption_snapshot(path)
+    live.adoption_require(before['mode']==0o600 and len(raw)<=2*1024*1024,'private runtime descriptor required')
+    value=json.loads(raw)
+    live.adoption_keys(value,['schemaVersion','library','ownerGeneration','profile','runtime','preserve'])
+    live.adoption_require(value['schemaVersion']==1 and type(value['schemaVersion']) is int and
+                          pathlib.Path(path).parent==pathlib.Path(value['library'])/'launchers','owned runtime descriptor location required')
+    live.adoption_read_inputs(value)
+    live.adoption_pin(value['ownerGeneration'],value['profile'])
+    env=live.adoption_runtime(value['runtime'],value['profile'])
+    for pin in value['preserve']:live.adoption_pin(pin,value['profile'])
+    live.adoption_require(live.adoption_snapshot(path,profile=value['profile'])[0]==before,'runtime descriptor changed')
+    return value,env
+
+
+def managed_mcp_main(path,args=()):
+    from .live import adoption_require
+    adoption_require(len(args)<=1 and all(isinstance(v,str) and re.fullmatch(r'[A-Za-z0-9_-]+',v) for v in args),'closed MCP agent name required')
+    value,env=managed_runtime_selection(path)
+    if args:env['TOPOLO_AGENT_NAME']=args[0]
+    runtime=value['runtime']
+    # Only a later owner-admitted ordinary native startup invokes this wrapper.
+    # Credential resolution/refresh/identity are real private effects, not preflight.
+    # Replace this wrapper, retaining the native host's PID/stdin/cancellation
+    # custody instead of leaving an intermediate parent that can orphan MCP.
+    return os.execve(runtime['node']['path'],[runtime['node']['path'],runtime['mcp']['path']],env)
+
+
 class Client:
     def __init__(self,environment,context,binary=None,env=None,node=None):
         if environment not in {'development','staging','production'}:
@@ -12,6 +42,12 @@ class Client:
         if not context or any(c in context for c in '\n\r'):
             raise PackError('Explicit Topolo context required')
         selected=os.environ if env is None else env
+        descriptor=selected.get('TOPOLO_AGENT_PACK_RUNTIME')
+        if descriptor:
+            value,selected=managed_runtime_selection(descriptor)
+            if (environment!=value['profile']['environment'] or context!=value['profile']['contextKey'] or binary is not None or node is not None):
+                raise ConnectionSourceRefused('Managed private runtime tuple or explicit override differs')
+            binary=value['runtime']['cli']['path'];node=value['runtime']['node']['path']
         if any(selected.get(k) for k in ['TOPOLO_API_KEY','TOPOLO_ACCESS_TOKEN','TOPOLO_'+environment.upper()+'_API_KEY','TOPOLO_'+environment.upper()+'_ACCESS_TOKEN']):
             raise PackError('Pinned connections require the CLI protected account context, not injected credentials')
         self.environment=environment;self.context=context