@topolo/cli 0.13.11 → 0.13.13

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, one of the two reviewed immutable consumer tuples (CLI 0.13.11/MCP 0.14.26/SDK 0.23.21 or CLI 0.13.12/MCP 0.14.27/SDK 0.23.22) and the separately pinned successor Python adapter. Consumer tuple versions are independent of the driver package version; mixed tuples and other versions refuse. 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; the exact reviewed consumer tuples are CLI 0.13.11/MCP 0.14.26/SDK 0.23.21 and CLI 0.13.12/MCP 0.14.27/SDK 0.23.22. Each tuple is coupled: mixed or unreviewed versions refuse, and both CLI and MCP must depend on that tuple's exact SDK version. The consumer tuple is independent of the driver package version. 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,364 @@ 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'])
+    packages={}
+    for key,name in [('cli','@topolo/cli'),('mcp','@topolo/mcp'),('sdk','@topolo/sdk')]:
+        package=json.loads(adoption_pin(runtime['cohort'][key],profile))
+        adoption_require(package.get('name')==name,'immutable target cohort differs')
+        packages[key]=package
+    versions=tuple(packages[key].get('version') for key in ['cli','mcp','sdk'])
+    # Reviewed consumer tuples are independent of this adapter driver's version.
+    # Membership is coupled: independently allowed versions would admit mixtures.
+    adoption_require(versions in (('0.13.11','0.14.26','0.23.21'),('0.13.12','0.14.27','0.23.22')),
+                     'immutable target cohort differs')
+    for key in ['cli','mcp']:
+        adoption_require(runtime[key]['path']==str(pathlib.Path(runtime['cohort'][key]['path']).parent/'dist/index.js') and
+                         packages[key].get('dependencies',{}).get('@topolo/sdk')==versions[2],'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