@topolo/cli 0.12.33 → 0.13.1

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

@@ -0,0 +1,443 @@
+"""The topolo-agent-pack command interface and recoverable composition transactions."""
+import argparse
+import copy
+import hashlib
+import json
+import os
+import pathlib
+import selectors
+import shutil
+import sqlite3
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+
+from . import __version__
+from . import native, live, fresh, blueprint, execution
+from .storage import Library, PackError, atomic_json, canonical, component_key, now, read_json, references, safe_id, select, sync_tree
+
+def emit(value):
+    print(json.dumps(value, indent=2, ensure_ascii=False))
+
+def source_components(manifest, revision, selected):
+    return [{'key':component_key(a),'sourcePack':manifest['packId'],'revision':revision,'originPack':manifest['packId'],'originRevision':revision,'threadId':a['threadId']} for a in selected]
+
+def make_plan(lib, args):
+    active = lib.active(); existing = active.get('components',[])
+    saved=read_json(lib.root/'workbenches'/(safe_id(args.source)+'.json'),{})
+    resume=bool(args.action=='switch' and saved and not getattr(args,'fresh',False))
+    if resume:
+        candidates=[]
+        for c in saved['components']:
+            m,_=lib.load(c['sourcePack'],c['revision'])
+            candidates.extend(a for a in m['agents'] if component_key(a)==c['key'])
+        manifest={'agents':candidates,'warnings':[]}
+        chosen=select(manifest,args.sets,args.agents)
+        incoming=[c for c in saved['components'] if c['key'] in {component_key(a) for a in chosen}]
+        revision='saved-workbench'
+    else:
+        manifest, revision = lib.load(args.source)
+        chosen = select(manifest, args.sets, args.agents)
+        incoming = source_components(manifest,revision,chosen)
+    if args.action=='switch' and active.get('name')==args.source and not args.sets and not args.agents and not getattr(args,'fresh',False):
+        return {'noChange':True,'before':active}
+    before = {c['key']:c for c in existing}
+    selected_keys = {c['key'] for c in incoming}
+    remove = set()
+    if args.action == 'switch': remove = set(before)
+    elif args.action == 'replace':
+        target = getattr(args,'target',None)
+        if target:
+            parts = target.split('/')
+            if not 1 <= len(parts) <= 3: raise PackError('--target must be PACK[/SET[/AGENT]]')
+            for part in parts: safe_id(part)
+            remove = {k for k in before if k == target or k.startswith(target+'/')}
+            if not remove: raise PackError('Replacement target is not in the active composition')
+            if len(parts)==3 and len(incoming)!=1: raise PackError('An individual target accepts exactly one incoming agent')
+            if len(parts)==2 and len({a['set'] for a in chosen})!=1: raise PackError('A set target accepts exactly one incoming set')
+        elif args.agents:
+            remove=selected_keys
+            if not remove <= set(before): raise PackError('Replacement agent is not active; use add or supply --target.')
+        elif args.sets:
+            prefixes={a['pack']+'/'+a['set']+'/' for a in chosen}
+            remove={k for k in before if any(k.startswith(p) for p in prefixes)}
+            if any(not any(k.startswith(p) for k in before) for p in prefixes): raise PackError('Replacement set is not active; use add or supply --target.')
+        else: remove=set(before)
+    elif args.action != 'add': raise PackError('Unknown composition action')
+    remaining={k:v for k,v in before.items() if k not in remove}
+    added=[]
+    for c in incoming:
+        if c['key'] in remaining:
+            old=remaining[c['key']]
+            if old.get('originRevision',old['revision'])==c.get('originRevision',c['revision']) and old.get('originPack',old['sourcePack'])==c.get('originPack',c['sourcePack']): continue
+            raise PackError('add would overwrite an installed identity: '+c['key']+'. Use replace.')
+        remaining[c['key']]=c; added.append(c['key'])
+    components=list(remaining.values())
+    threads=[c['threadId'] for c in components]
+    if len(threads)!=len(set(threads)): raise PackError('Native thread identity collision across selected agents')
+    return {'operation':args.action,'source':args.source,'sourceRevision':revision,'before':active,
+            'components':components,'removed':sorted(remove),'added':added,'noChange':not remove and not added,
+            'name':args.source if args.action=='switch' or not existing else active.get('name',args.source),
+            'resumeRuntime':saved.get('runtime') if resume and not args.sets and not args.agents else None,
+            'reuseOutgoingRuntime':args.action=='switch' and not args.sets and not args.agents,
+            'runtimeCheckpointRequired':bool(existing),'warnings':manifest.get('warnings',[]),
+            'activation':'not tested by plan; --no-open commits storage only'}
+
+def maps(values):
+    result={}
+    for value in values or []:
+        if '=' not in value: raise PackError('--map requires OLD=NEW')
+        old,new=value.split('=',1)
+        old=str(pathlib.Path(old).expanduser().resolve()); new=str(pathlib.Path(new).expanduser().resolve())
+        if not pathlib.Path(new).exists(): raise PackError('Mapped destination does not exist: '+new)
+        if old in result and result[old]!=new: raise PackError('Conflicting path mapping')
+        result[old]=new
+    return result
+
+def verify_backend(lib, runtime, cli):
+    """Read back through the installed native protocol; do not load/resume or start turns."""
+    if not cli: raise PackError('Native Codex binary not found; supply --codex-bin.')
+    cli=pathlib.Path(cli).expanduser().resolve()
+    home=pathlib.Path(runtime)/'home'
+    connection=native.ro(home/'state_5.sqlite')
+    try: expected_cwds=dict(connection.execute('SELECT id,cwd FROM threads'))
+    finally: connection.close()
+    stderr=open(pathlib.Path(runtime)/'backend-verify.log','a')
+    env=os.environ.copy(); env['CODEX_HOME']=str(home)
+    for key in list(env):
+        if key.startswith('CODEX_APP_TOOLS_'): del env[key]
+    proc=subprocess.Popen([str(cli),'app-server','--listen','stdio://'],cwd=runtime,env=env,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=stderr,bufsize=0)
+    sel=selectors.DefaultSelector(); sel.register(proc.stdout,selectors.EVENT_READ)
+    seq=0; buffer=b''
+    def request(method,params):
+        nonlocal seq,buffer
+        seq+=1; proc.stdin.write(canonical({'id':seq,'method':method,'params':params})+b'\n'); proc.stdin.flush()
+        deadline=time.monotonic()+20
+        while time.monotonic()<deadline:
+            while b'\n' in buffer:
+                line,buffer=buffer.split(b'\n',1)
+                if not line.strip(): continue
+                value=json.loads(line)
+                if value.get('id')==seq:
+                    if 'error' in value: raise PackError('Native protocol '+method+': '+value['error']['message'])
+                    return value['result']
+            if not sel.select(max(0,deadline-time.monotonic())): break
+            chunk=os.read(proc.stdout.fileno(),65536)
+            if not chunk: raise PackError('Native verification process exited')
+            buffer+=chunk
+        raise PackError('Native read-back timed out: '+method)
+    checked=[]
+    try:
+        init=request('initialize',{'clientInfo':{'name':'topolo_agent_pack','version':__version__},'capabilities':{'experimentalApi':True}})
+        proc.stdin.write(canonical({'method':'initialized'})+b'\n');proc.stdin.flush()
+        agents=read_json(pathlib.Path(runtime)/'agents.json')['agents']
+        for a in agents:
+            tid=a['threadId']; result=request('thread/read',{'threadId':tid,'includeTurns':False})
+            if result['thread']['id']!=tid: raise PackError('Native thread identity read-back mismatch')
+            expected=str(pathlib.Path(expected_cwds[tid]).resolve())
+            if str(pathlib.Path(result['thread']['cwd']).resolve())!=expected: raise PackError('Native working-directory read-back mismatch for '+tid+': expected '+expected+', got '+result['thread']['cwd'])
+            turns=request('thread/turns/list',{'threadId':tid,'limit':1,'itemsView':'notLoaded'})
+            items=request('thread/items/list',{'threadId':tid,'limit':1})
+            checked.append({'threadId':tid,'cwdVerified':True,'historyReadable':True,'sampledTurns':len(turns['data']),'sampledItems':len(items['data'])})
+    finally:
+        proc.terminate()
+        try: proc.wait(timeout=5)
+        except subprocess.TimeoutExpired: proc.kill(); proc.wait()
+        sel.close(); proc.stdin.close(); proc.stdout.close(); stderr.close()
+    report={'boundary':'native backend read-back; desktop rendering not verified','agents':checked,'modelTurnsStarted':False}
+    atomic_json(pathlib.Path(runtime)/'backend-proof.json',report)
+    return report
+
+def desktop_open(runtime, app, user_data, codex_bin=None):
+    if sys.platform!='darwin': raise PackError('Desktop activation adapter currently supports macOS. Use --no-open for portable storage on this platform.')
+    app=pathlib.Path(app).expanduser().resolve()
+    if not app.is_dir(): raise PackError('Desktop application not found: '+str(app))
+    runtime=pathlib.Path(runtime); user_data=pathlib.Path(user_data); user_data.mkdir(exist_ok=True,mode=0o700)
+    lib=Library(user_data.parent);real=codex_bin or find_codex()
+    executable,home=live.prepare(lib,real)
+    subprocess.run(['/usr/bin/open','-n','--env','CODEX_HOME='+str(home),
+                    '--env','CODEX_CLI_PATH='+str(executable),'--env','CODEX_PACK_HOME='+str(lib.root),
+                    '--env','CODEX_PACK_REAL_CLI='+str(real),
+                    '--env','CODEX_ELECTRON_USER_DATA_PATH='+str(user_data),str(app),
+                    '--args','--user-data-dir='+str(user_data),'--remote-debugging-port=0','--remote-debugging-address=127.0.0.1','codex://launch'],check=True,timeout=20)
+    return {'state':'managed-window-launch-requested','app':str(app),'frontendVerified':False,'note':'One-time managed window launch. Future changes reconnect this same window. Authenticate locally if prompted.'}
+
+def apply_plan(lib,plan,args):
+    if plan['noChange']:
+        active=lib.active()
+        if not args.no_open and not live.available(lib):
+            native.assert_idle(pathlib.Path(active['runtime'])/'home')
+            active['desktop']=desktop_open(active['runtime'],args.app,lib.root/'desktop-data',args.codex_bin)
+            active['state']=active['desktop']['state'];atomic_json(lib.root/'active.json',active)
+            return {'state':active['state'],'active':active}
+        return {'state':'unchanged','active':active}
+    if lib.pending(): raise PackError('An incomplete operation needs recovery. Run topolo-agent-pack recover before another mutation.')
+    before=plan['before']; old_runtime=pathlib.Path(before['runtime']) if before.get('runtime') else None
+    bridge=live.available(lib)
+    if bridge:
+        if not old_runtime or bridge['runtime']!=str(old_runtime): raise PackError('Live bridge and active runtime disagree; run recover before switching')
+        live.adapter(args.app)
+        ws,target=live.renderer(lib);ws.close()
+    elif old_runtime: native.assert_idle(old_runtime/'home')
+    tx=uuid.uuid4().hex; runtime=lib.root/'runtimes'/tx
+    journal={'id':tx,'phase':'started','createdAt':now(),'desktopApp':args.app,'before':before,'operation':plan['operation'],'targetRuntime':str(runtime),'plan':{k:v for k,v in plan.items() if k!='before'}}
+    jpath=lib.root/'journals'/(tx+'.json'); atomic_json(jpath,journal)
+    try:
+        if bridge:
+            journal['liveBridge']={'targetId':target,'beforePid':bridge['pid'],'desktopPid':bridge['desktopPid']};atomic_json(jpath,journal)
+            try:live.quiesce(lib)
+            except Exception:
+                current=live.available(lib)
+                if current and not current['quiesced']:journal['phase']='rolled-back'
+                raise
+            journal['phase']='quiesced';atomic_json(jpath,journal)
+        if old_runtime: native.assert_idle(old_runtime/'home')
+        if bridge:live.checkpoint_ui(lib,old_runtime)
+        if old_runtime and not plan.get('reuseOutgoingRuntime'):
+            known={a['threadId'] for a in read_json(old_runtime/'agents.json')['agents']}
+            if native.unregistered_threads(old_runtime/'home',known):
+                raise PackError('Additional independent threads need registration before partial composition. Run capture NAME --all, then switch NAME --fresh. Whole-pack switches retain these threads in their runtime.')
+        checkpoint_components=copy.deepcopy(before.get('components',[]))
+        if old_runtime:
+            if plan.get('reuseOutgoingRuntime'):
+                # The complete stopped runtime already lives in the independent
+                # pack library. Whole-pack switching can retain it in place.
+                journal['checkpoint']={'mode':'retained-runtime','runtime':str(old_runtime),'components':checkpoint_components}
+            else:
+                checkpoint_name='checkpoint-'+tx
+                snapshot,revision=native.capture(old_runtime/'home',lib,checkpoint_name,all_threads=True,template=read_json(old_runtime/'agents.json'))
+                checkpoint_components=[{**c,'sourcePack':checkpoint_name,'revision':revision} for c in checkpoint_components]
+                journal['checkpoint']={'mode':'immutable-snapshot','pack':checkpoint_name,'revision':revision,'components':checkpoint_components}
+            journal['phase']='checkpointed';atomic_json(jpath,journal)
+            if before.get('name'):
+                atomic_json(lib.root/'workbenches'/(safe_id(before['name'])+'.json'),{**before,'components':checkpoint_components})
+        checkpoint_by_key={c['key']:c for c in checkpoint_components}
+        # Unchanged agents are taken from the current installed state, never the old source template.
+        added=set(plan['added'])
+        target_components=[checkpoint_by_key.get(c['key'],c) if c['key'] not in added else c for c in plan['components']]
+        if plan.get('resumeRuntime'):
+            runtime=pathlib.Path(plan['resumeRuntime']);native.assert_idle(runtime/'home')
+            if args.mappings: raise PackError('Saved workbench paths are already bound. Use --fresh with --map to rebuild.')
+            proof=read_json(runtime/'verification.json')
+            journal['targetRuntime']=str(runtime)
+        else:
+            proof=native.materialize(lib,target_components,runtime,maps(args.mappings))
+            atomic_json(runtime/'composition.json',target_components)
+            # Authentication and local tool configuration are machine-local and
+            # deliberately kept out of portable manifests and export bundles.
+            if old_runtime and (old_runtime/'home'/'auth.json').exists():
+                shutil.copyfile(old_runtime/'home'/'auth.json',runtime/'home'/'auth.json')
+                (runtime/'home'/'auth.json').chmod(0o600)
+            local_config=lib.root/'local-config.toml'
+            if local_config.exists():
+                shutil.copyfile(local_config,runtime/'home'/'config.toml');(runtime/'home'/'config.toml').chmod(0o600)
+        if old_runtime and old_runtime!=runtime and (old_runtime/'desktop-view.json').exists():shutil.copyfile(old_runtime/'desktop-view.json',runtime/'desktop-view.json')
+        execution.compile_runtime(lib, target_components, runtime)
+        journal['phase']='staged';atomic_json(jpath,journal)
+        if old_runtime and old_runtime!=runtime and (old_runtime/'home/auth.json').exists():
+            shutil.copyfile(old_runtime/'home/auth.json',runtime/'home/auth.json');(runtime/'home/auth.json').chmod(0o600)
+        backend=verify_backend(lib,runtime,args.codex_bin)
+        if not plan.get('resumeRuntime'): sync_tree(runtime)
+        if old_runtime: native.assert_idle(old_runtime/'home')
+        if lib.active()!=before: raise PackError('Active composition changed concurrently; refusing to overwrite it.')
+        after={'name':plan['name'],'runtime':str(runtime),'components':target_components,'selectedAt':now(),'state':'backend-verified','desktop':{'state':'not-opened','frontendVerified':False},'transaction':tx}
+        journal['after']=after;journal['phase']='verified';atomic_json(jpath,journal)
+        atomic_json(lib.root/'active.json',after)
+        journal['phase']='committed';atomic_json(jpath,journal)
+        if bridge or not args.no_open:
+            after['desktop']=live.reconnect(lib,runtime,old_runtime,args.app) if bridge else desktop_open(runtime,args.app,lib.root/'desktop-data',args.codex_bin)
+            after['state']=after['desktop']['state'];atomic_json(lib.root/'active.json',after)
+        journal['after']=after;journal['phase']='complete';atomic_json(jpath,journal)
+        return {'state':after['state'],'agents':proof['agents'],'totalHistoryThreads':proof['threads'],'runtime':str(runtime),'checkpoint':journal.get('checkpoint'),
+                'desktop':after['desktop'],'backend':backend,'dependencies':proof['dependencies'],'activeGoalsPaused':proof['activeGoalsPaused']}
+    except Exception as exc:
+        journal['failure']=str(exc);atomic_json(jpath,journal)
+        if bridge and live.available(lib) and live.available(lib).get('quiesced'):
+            try:
+                current=lib.active();journal['reconnectAfterFailure']=live.reconnect(lib,current['runtime'],old_runtime,args.app);atomic_json(jpath,journal)
+            except Exception as reconnect_error:
+                journal['reconnectFailure']=str(reconnect_error);atomic_json(jpath,journal)
+        raise
+
+def recover(lib):
+    result=[]
+    for path in sorted(lib.pending()):
+        j=read_json(path); active=lib.active(); before=j['before']; after=j.get('after')
+        previous=(active.get('runtime')==before.get('runtime') and active.get('transaction')==before.get('transaction') and active.get('components')==before.get('components'))
+        committed=bool(after and active.get('transaction')==j['id'] and active.get('runtime')==after['runtime'] and active.get('components')==after.get('components'))
+        if not previous and not committed:raise PackError('Recovery found a concurrent active-pointer change; no state overwritten. Inspect '+str(path))
+        if j.get('liveBridge'):
+            j['desktopRecovery']=live.reconnect(lib,active['runtime'],before.get('runtime'),j.get('desktopApp','/Applications/ChatGPT.app'))
+            active['desktop']=j['desktopRecovery'];active['state']=active['desktop']['state'];atomic_json(lib.root/'active.json',active)
+        if previous:
+            j['phase']='rolled-back';j['recovery']='Previous active pointer retained; staged files kept for inspection.'
+        elif after and active.get('transaction')==j['id'] and active.get('runtime')==after['runtime']:
+            if not j.get('liveBridge'): native.assert_idle(pathlib.Path(active['runtime'])/'home')
+            if not (pathlib.Path(active['runtime'])/'backend-proof.json').exists(): raise PackError('Committed runtime lacks backend proof; recovery needs inspection.')
+            j['phase']='complete';j['recovery']='Verified committed runtime retained.'+(' Same window reconnected and read back.' if j.get('liveBridge') else ' Desktop activation was not replayed.')
+        else: raise PackError('Recovery found a concurrent active-pointer change; no state overwritten. Inspect '+str(path))
+        atomic_json(path,j);result.append({'transaction':j['id'],'phase':j['phase'],'action':j['recovery']})
+    return {'recovered':result,'active':lib.active()}
+
+def find_codex():
+    bundled=pathlib.Path('/Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex')
+    return str(bundled) if bundled.exists() else shutil.which('codex')
+
+def parser():
+    p=argparse.ArgumentParser(description='Capture, install and compose portable Topolo Agent Packs. No cloud service or API key required for storage operations.')
+    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)
+    def selection(q):
+        q.add_argument('--set',dest='sets',action='append');q.add_argument('--agent',dest='agents',action='append')
+    def activation(q):
+        q.add_argument('--no-open',action='store_true',help='Commit a backend-verified composition without opening the desktop')
+        q.add_argument('--map',dest='mappings',action='append',help='External path binding OLD=NEW (never overwrites the external destination)')
+        q.add_argument('--codex-bin',default=find_codex());q.add_argument('--app',default='/Applications/ChatGPT.app')
+    cap=sub.add_parser('capture');cap.add_argument('name');selection(cap)
+    cap.add_argument('--source-home',help='Source Codex home. Defaults to the selected managed runtime, otherwise CODEX_HOME or ~/.codex')
+    cap.add_argument('--include',action='append',help='Explicit additional workflow/asset path')
+    cap.add_argument('--all',action='store_true',help='Explicitly capture all non-archived threads when group names do not identify the pack')
+    cap.add_argument('--workspace-mode',choices=['copy','reference'],default='copy')
+    cap.add_argument('--offline',action='store_true',help='Require an idle source instead of taking a read-only live snapshot')
+    q=sub.add_parser('context',help='Extract operating context and conversation rule candidates for review');q.add_argument('source');q.add_argument('directory');selection(q)
+    q=sub.add_parser('fresh',help='Create new native agents from reviewed file-backed context, without old work history');q.add_argument('source');q.add_argument('name');q.add_argument('--context',required=True);selection(q);q.add_argument('--codex-bin',default=find_codex())
+    q=sub.add_parser('build',help='Build a new native instance from a portable authored template; no source pack required');q.add_argument('name');q.add_argument('--template',required=True);selection(q);q.add_argument('--codex-bin',default=find_codex())
+    install=sub.add_parser('install');install.add_argument('bundle');selection(install)
+    export=sub.add_parser('export');export.add_argument('name');export.add_argument('destination')
+    for action in ['add','replace','switch']:
+        q=sub.add_parser(action);q.add_argument('source');selection(q);activation(q)
+        q.set_defaults(action=action)
+        if action=='add': q.add_argument('--catalog',action='store_true',help='Build an uninstalled bundled catalog pack before adding it')
+        if action=='replace': q.add_argument('--target')
+        if action=='switch': q.add_argument('--fresh',action='store_true',help='Use the captured source instead of resuming a previously saved workbench')
+    q=sub.add_parser('plan');q.add_argument('action',choices=['add','replace','switch']);q.add_argument('source');selection(q);q.add_argument('--target');q.add_argument('--fresh',action='store_true')
+    q=sub.add_parser('policy',help='Render portable role settings for review; never changes live sessions')
+    q.add_argument('source');selection(q);q.add_argument('--output')
+    for command in ['connect','remote-context','remember','artifact','artifact-get','remote-recover']:
+        q=sub.add_parser(command,help='Use public Topolo Agent continuity and Bytes artifact contracts')
+        q.add_argument('name');q.add_argument('--environment',choices=['development','staging','production'],required=True)
+        q.add_argument('--context-key',required=True);q.add_argument('--role',required=command not in ['connect','remote-recover'])
+        if command in ['connect','remember','artifact']:q.add_argument('--confirm',action='store_true',required=True)
+        if command=='connect':
+            q.add_argument('--roles',required=True);q.add_argument('--agent-workspace',required=True);q.add_argument('--bytes-workspace',required=True)
+            q.add_argument('--ownership',choices=['user','organization'],required=True);q.add_argument('--bytes-scope',choices=['private','org'],required=True);q.add_argument('--instance')
+        if command=='remember':
+            q.add_argument('--content',required=True);q.add_argument('--kind',choices=['instruction','knowledge','durable'],required=True)
+            q.add_argument('--provenance',required=True);q.add_argument('--visibility',choices=['private','shared'],default='private')
+            q.add_argument('--sharing-policy');q.add_argument('--expires-at',type=int)
+        if command=='artifact':
+            q.add_argument('--file',required=True);q.add_argument('--content-type',default='application/octet-stream')
+            q.add_argument('--visibility',choices=['private','shared'],default='private')
+        if command=='artifact-get':q.add_argument('--reference',required=True);q.add_argument('--destination',required=True)
+    sub.add_parser('status');q=sub.add_parser('list');q.add_argument('name',nargs='?');sub.add_parser('recover')
+    q=sub.add_parser('open');q.add_argument('--codex-bin',default=find_codex());q.add_argument('--app',default='/Applications/ChatGPT.app')
+    q=sub.add_parser('doctor');q.add_argument('name',nargs='?');q.add_argument('--codex-bin',default=find_codex())
+    return p
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    harness = 'codex'
+    explicit_harness = '--harness' in argv
+    if '--harness' in argv:
+        at = argv.index('--harness')
+        if at + 1 >= len(argv):
+            parser().error('--harness requires codex or claude')
+        harness = argv[at + 1]
+        del argv[at:at + 2]
+    policy_command = 'policy' in argv
+    if harness == 'claude' and not policy_command:
+        from . import claude
+        return claude.main(argv)
+    if harness not in {'codex', 'claude'}:
+        print('topolo-agent-pack: Unsupported harness: ' + harness, file=sys.stderr)
+        return 2
+    args=parser().parse_args(argv)
+    try:
+        lib=Library(args.store)
+        if args.command in {'connect','remote-context','remember','artifact','artifact-get','remote-recover'}:
+            from . import topolo
+            with topolo.connection_lock(lib,args):result=topolo.dispatch(lib,args)
+            emit(result)
+            return 0
+        with lib.lock():
+            if args.command=='policy':
+                from . import policy
+                manifest,revision=lib.load(args.source)
+                result=policy.render(manifest,revision,select(manifest,args.sets,args.agents),
+                                     (harness,) if explicit_harness else ('codex','claude'))
+                if args.output:
+                    from .claude import write_new
+                    write_new(pathlib.Path(args.output).expanduser().absolute(), canonical(result)+b'\n')
+            elif args.command=='capture':
+                safe_id(args.name)
+                active=lib.active();template=None
+                if args.source_home: home=pathlib.Path(args.source_home)
+                elif active.get('runtime'):
+                    home=pathlib.Path(active['runtime'])/'home';template=read_json(pathlib.Path(active['runtime'])/'agents.json')
+                else: home=pathlib.Path(os.environ.get('CODEX_HOME',str(pathlib.Path.home()/'.codex')))
+                manifest,revision=native.capture(home,lib,args.name,args.sets,args.agents,args.include,args.all,template,args.workspace_mode,live=not args.offline)
+                result={'pack':args.name,'revision':revision,'agents':len(manifest['agents']),'historyThreads':len(manifest['threads']),'warnings':manifest['warnings'],'state':'captured'}
+            elif args.command=='context':result=fresh.prepare(lib,args.source,args.directory,args.sets,args.agents)
+            elif args.command=='fresh':result=fresh.create(lib,args.source,args.name,args.context,args.codex_bin,args.sets,args.agents)
+            elif args.command=='build':result=blueprint.build(lib,args.name,args.template,args.codex_bin,args.sets,args.agents)
+            elif args.command=='install':
+                manifest,revision=lib.install(args.bundle,publish=False)
+                selected=select(manifest,args.sets,args.agents)
+                if args.sets or args.agents:
+                    manifest=native.slice_manifest(lib,manifest,selected)
+                revision=lib.save(manifest)
+                result={'state':'installed-not-activated','pack':manifest['packId'],'revision':revision,'agents':len(selected),'warnings':manifest['warnings']}
+            elif args.command=='export': result=lib.export(args.name,args.destination)
+            elif args.command=='list':
+                if args.name:
+                    manifest,revision=lib.load(args.name)
+                    result={'pack':args.name,'revision':revision,'sets':sorted({a['set'] for a in manifest['agents']}),
+                            'agents':[{'key':component_key(a),'title':a['title'],'aliases':a.get('aliases',[])} for a in manifest['agents']]}
+                else:
+                    result={'packs':[{'name':path.parent.name,'revision':read_json(path)['revision']} for path in sorted((lib.root/'packs').glob('*/head.json')) if not path.parent.name.startswith('checkpoint-')],
+                            'workbenches':[p.stem for p in sorted((lib.root/'workbenches').glob('*.json'))]}
+            elif args.command=='plan': result=make_plan(lib,args)
+            elif args.command in {'add','replace','switch'}:
+                if args.command=='add' and args.catalog and not (lib.root/'packs'/safe_id(args.source)/'head.json').exists():
+                    template=pathlib.Path(__file__).resolve().parents[2]/'templates'/safe_id(args.source)
+                    if not template.is_dir():raise PackError('Unknown catalog pack: '+args.source)
+                    blueprint.build(lib,args.source,template,args.codex_bin)
+                result=apply_plan(lib,make_plan(lib,args),args)
+            elif args.command=='recover': result=recover(lib)
+            elif args.command=='open':
+                active=lib.active()
+                if not active.get('runtime'):raise PackError('Select a pack first with switch NAME')
+                if live.available(lib):result={'state':'already-open','liveBridge':live.available(lib)}
+                else:
+                    native.assert_idle(pathlib.Path(active['runtime'])/'home')
+                    result=desktop_open(active['runtime'],args.app,lib.root/'desktop-data',args.codex_bin)
+                    active['desktop']=result;active['state']=result['state'];atomic_json(lib.root/'active.json',active)
+            elif args.command=='status':
+                active=lib.active();pids=native.busy_writers(pathlib.Path(active['runtime'])/'home') if active.get('runtime') else []
+                result={'store':str(lib.root),'active':active,'liveBridge':live.available(lib),'runtimeDatabaseHolders':pids,'recoveryRequired':[str(p) for p in lib.pending()],'frontendVerified':active.get('desktop',{}).get('frontendVerified',False)}
+            elif args.command=='doctor':
+                checked=[]
+                if args.name:
+                    manifest,revision=lib.load(args.name)
+                    for ref in references(manifest).values(): lib.object(ref)
+                    checked.append({'pack':args.name,'revision':revision,'objectsVerified':len(references(manifest))})
+                result={'library':str(lib.root),'nativeCodex':args.codex_bin,'desktopAdapter':'macOS managed backend proxy and same-window reconnect','liveBridge':live.available(lib),
+                        'recoveryRequired':bool(lib.pending()),'checked':checked,'version':__version__}
+            emit(result)
+        return 0
+    except (PackError,OSError,ValueError,sqlite_error(),subprocess.SubprocessError,zip_error()) as exc:
+        print('topolo-agent-pack: '+str(exc),file=sys.stderr)
+        return 2
+
+def sqlite_error():
+    import sqlite3
+    return sqlite3.Error
+
+def zip_error():
+    import zipfile
+    return zipfile.BadZipFile
+
+if __name__=='__main__': raise SystemExit(main())

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

@@ -0,0 +1,154 @@
+"""Per-role defaults for the owned Codex proxy, with explicit native read-back.
+
+No model turns are created here. A manifest is intent, never activation proof.
+Conflicting frontend settings are rejected instead of silently broadening the
+reviewed role. Changing that intent requires rebuilding the selected policy.
+"""
+import copy
+import hashlib
+import json
+import pathlib
+import sqlite3
+import subprocess
+import tempfile
+from contextlib import closing
+
+from . import policy
+from .storage import PackError, atomic_json, component_key, read_json
+
+
+def compile_runtime(lib, components, runtime):
+    runtime = pathlib.Path(runtime)
+    with closing(sqlite3.connect('file:' + str(runtime / 'home/state_5.sqlite') + '?mode=ro', uri=True)) as db:
+        cwds = dict(db.execute('SELECT id,cwd FROM threads'))
+    rows = []
+    for component in components:
+        manifest, revision = lib.load(component['sourcePack'], component['revision'])
+        matches = [a for a in manifest['agents'] if component_key(a) == component['key'] and a['threadId'] == component['threadId']]
+        if len(matches) != 1 or component['threadId'] not in cwds:
+            raise PackError('Execution policy has no unique owned role: ' + component['key'])
+        rows.append({'key': component['key'], 'threadId': component['threadId'],
+                     'sourceRevision': revision, 'cwd': cwds[component['threadId']],
+                     'settings': policy.settings(matches[0], 'codex')['nativeSettings']})
+    document = {'format': 'topolo-codex-runtime-execution', 'schemaVersion': 1,
+                'roles': rows, 'applied': False, 'modelTurnsStarted': False}
+    # Construct/validate fully before installing intent in a staged runtime.
+    ExecutionGate(document)
+    atomic_json(runtime / 'execution-policy.json', document)
+    return document
+
+
+class ExecutionGate:
+    def __init__(self, document):
+        if document.get('format') != 'topolo-codex-runtime-execution' or document.get('schemaVersion') != 1:
+            raise PackError('Unqualified runtime execution policy')
+        self.roles = {}; self.pending = {}; self.verified = set(); self.catalog = {}
+        for role in document['roles']:
+            tid = role['threadId']; spec = role['settings']
+            if tid in self.roles or not pathlib.Path(role['cwd']).is_absolute():
+                raise PackError('Duplicate thread or non-absolute role workspace')
+            required = {'model', 'model_reasoning_effort', 'approval_policy', 'approvals_reviewer',
+                        'sandbox_mode', 'sandbox_workspace_write', 'apps'}
+            if (set(spec) != required or not isinstance(spec['model'], str) or not spec['model'] or
+                    spec['model_reasoning_effort'] not in {'medium', 'high'} or
+                    spec['approval_policy'] != 'on-request' or spec['approvals_reviewer'] != 'user' or
+                    spec['sandbox_mode'] not in {'read-only', 'workspace-write'} or
+                    spec['sandbox_workspace_write'] != {'network_access': False, 'writable_roots': [],
+                                                       'exclude_slash_tmp': True, 'exclude_tmpdir_env_var': True} or
+                    spec['apps'] != {'_default': {'default_tools_approval_mode': 'writes'}}):
+                raise PackError('Unqualified role execution settings')
+            self.roles[tid] = copy.deepcopy(role)
+
+    def set_catalog(self, result):
+        self.catalog = {row['model']: {e['reasoningEffort'] for e in row['supportedReasoningEfforts']}
+                        for row in result['data']}
+
+    def sandbox(self, role):
+        if role['settings']['sandbox_mode'] == 'read-only':
+            return {'type': 'readOnly', 'networkAccess': False}
+        return {'type': 'workspaceWrite', 'networkAccess': False, 'writableRoots': [role['cwd']],
+                'excludeSlashTmp': True, 'excludeTmpdirEnvVar': True}
+
+    def prepare(self, message):
+        value = copy.deepcopy(message); method = value.get('method'); params = value.get('params') or {}
+        tid = params.get('threadId'); role = self.roles.get(tid)
+        if not role or method not in {'thread/resume', 'turn/start'}:
+            return value
+        if 'id' not in value or str(value['id']) in self.pending:
+            raise PackError('Managed execution requires a unique request identity')
+        spec = role['settings']
+        if spec['model_reasoning_effort'] not in self.catalog.get(spec['model'], set()):
+            raise PackError('Role model/effort is absent from the native account catalog; no fallback selected')
+        if any(params.get(key) is not None for key in ['permissions', 'path', 'history', 'collaborationMode', 'environments', 'runtimeWorkspaceRoots']):
+            raise PackError('Frontend supplied unreviewed permission, identity or execution overrides')
+        wanted = {'cwd': role['cwd'], 'model': spec['model'], 'approvalPolicy': spec['approval_policy'],
+                  'approvalsReviewer': spec['approvals_reviewer']}
+        if method == 'thread/resume':
+            wanted['sandbox'] = spec['sandbox_mode']
+            wanted['config'] = {'model_reasoning_effort': spec['model_reasoning_effort'],
+                                'sandbox_workspace_write': spec['sandbox_workspace_write'], 'apps': spec['apps']}
+            self.verified.discard(tid)
+        else:
+            if tid not in self.verified:
+                raise PackError('Role needs a verified native resume before starting a turn')
+            wanted.update(effort=spec['model_reasoning_effort'], sandboxPolicy=self.sandbox(role))
+        for key, expected in wanted.items():
+            if params.get(key) is not None and params[key] != expected:
+                raise PackError('Frontend ' + key + ' conflicts with the reviewed role policy')
+            params[key] = copy.deepcopy(expected)
+        value['params'] = params
+        if method == 'thread/resume': self.pending[str(value['id'])] = tid
+        return value
+
+    def reply(self, value):
+        tid = self.pending.pop(str(value.get('id')), None)
+        if tid is None: return value
+        self.verified.discard(tid)
+        if 'error' in value: return value
+        role = self.roles[tid]; spec = role['settings']; result = value.get('result', {})
+        expected = {'model': spec['model'], 'cwd': role['cwd'], 'approvalPolicy': spec['approval_policy'],
+                    'approvalsReviewer': spec['approvals_reviewer'], 'reasoningEffort': spec['model_reasoning_effort'],
+                    'sandbox': self.sandbox(role)}
+        sandbox = result.get('sandbox', {})
+        # Native responses can omit false read-only networkAccess defaults.
+        actual = copy.deepcopy(result)
+        if sandbox.get('type') == 'readOnly': actual['sandbox'] = {'type': 'readOnly', 'networkAccess': sandbox.get('networkAccess', False)}
+        if result.get('thread', {}).get('id') != tid or any(actual.get(k) != v for k, v in expected.items()):
+            return {'id': value['id'], 'error': {'code': -32000,
+                    'message': 'Native role settings differ from the reviewed policy; model work is blocked'}}
+        self.verified.add(tid)
+        return value
+
+    def status(self):
+        return {'configuredRoles': len(self.roles), 'nativeResumeVerifiedRoles': sorted(self.verified),
+                'requested': [{'key': r['key'], 'threadId': tid, 'settings': r['settings']} for tid, r in self.roles.items()],
+                'appToolApprovalReadbackVerified': False, 'modelIdentityResponseVerified': False}
+
+
+def load_gate(runtime):
+    path = pathlib.Path(runtime) / 'execution-policy.json'
+    return ExecutionGate(read_json(path)) if path.exists() else None
+
+
+def qualify_protocol(binary, run=subprocess.run):
+    """Generate schema offline from this executable; never initialize an app server."""
+    required = {'ThreadResumeParams': {'threadId', 'model', 'approvalPolicy', 'approvalsReviewer', 'sandbox', 'config'},
+                'ThreadResumeResponse': {'thread', 'model', 'cwd', 'reasoningEffort', 'approvalPolicy', 'approvalsReviewer', 'sandbox'},
+                'TurnStartParams': {'threadId', 'model', 'effort', 'approvalPolicy', 'approvalsReviewer', 'sandboxPolicy'},
+                'ModelListParams': {'includeHidden', 'cursor'}, 'ModelListResponse': {'data', 'nextCursor'}}
+    with tempfile.TemporaryDirectory(prefix='topolo-codex-protocol-') as temp:
+        result = run([binary, 'app-server', 'generate-json-schema', '--experimental', '--out', temp],
+                     capture_output=True, timeout=20, check=False)
+        if result.returncode:
+            raise PackError('Installed Codex protocol export refused; no backend started')
+        hashes = {}
+        for name, fields in required.items():
+            matches = list(pathlib.Path(temp).rglob(name + '.json'))
+            if len(matches) != 1:
+                raise PackError('Installed Codex protocol has no unique ' + name)
+            data = matches[0].read_bytes(); schema = json.loads(data)
+            if not fields <= set(schema.get('properties', {})):
+                raise PackError('Installed Codex protocol settings are incompatible: ' + name)
+            hashes[name] = hashlib.sha256(data).hexdigest()
+    return {'boundary': 'offline installed executable protocol export', 'schemas': hashes,
+            'modelTurnsStarted': False}