@topolo/cli 0.13.19 → 0.13.21

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

@@ -96,7 +96,7 @@ def maps(values):
         result[old]=new
     return result
 
-def verify_backend(lib, runtime, cli):
+def verify_backend(lib, runtime, cli, presentation_journal=None, reconcile=None):
     """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()
@@ -129,9 +129,24 @@ def verify_backend(lib, runtime, cli):
             buffer+=chunk
         raise PackError('Native read-back timed out: '+method)
     checked=[]
+    account=None;sidebar=None
+    binary_hash=hashlib.sha256(cli.read_bytes()).hexdigest()
+    def current_context():
+        config=request('config/read',{'cwd':str(home),'includeLayers':True})
+        origins=[{'name':layer['name'],'version':layer['version']} for layer in config.get('layers',[])
+                 if layer.get('name',{}).get('type')=='user' and not layer.get('disabledReason')]
+        if not origins or any(row['name'].get('file')!=str(home/'config.toml') or not isinstance(row['version'],str) or not row['version'] for row in origins):
+            raise PackError('Native verification execution-home provenance differs')
+        actual=request('account/read',{'refreshToken':False})
+        native.sidebar_binding(runtime,actual)  # Validate the native schema without effects.
+        return {'kind':'offline','home':str(home),'binary':str(cli),'binarySHA256':binary_hash,
+                'configOrigins':origins,'account':{'type':(actual.get('account') or {}).get('type'),
+                'accountId':(actual.get('workspaceRouting') or {}).get('chatgptAccountId'),
+                'requiresOpenaiAuth':actual['requiresOpenaiAuth']},'readerPID':proc.pid},actual
     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()
+        initial_context,account=current_context()
         agents=read_json(pathlib.Path(runtime)/'agents.json')['agents']
         for a in agents:
             tid=a['threadId']; result=request('thread/read',{'threadId':tid,'includeTurns':False})
@@ -141,13 +156,23 @@ def verify_backend(lib, runtime, cli):
             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'])})
+        # The same original backend is still open here, after all history reads.
+        def guard():
+            context,actual=current_context()
+            if context!=initial_context:raise PackError('Native account/home/config changed during verification')
+            return context
+        if reconcile is not None:
+            path,document=reconcile
+            sidebar=native.reconcile_sidebar(lib,path,document,guard(),read_json(home/'.codex-global-state.json'),guard)
+        else:
+            sidebar=native.bind_sidebar(runtime,account,lib=lib,guard=guard,journal=presentation_journal,context=initial_context)
     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)
+    report={'boundary':'native backend read-back; desktop rendering not verified','agents':checked,'modelTurnsStarted':False,'sidebar':sidebar}
+    if reconcile is None:atomic_json(pathlib.Path(runtime)/'backend-proof.json',report)
     return report
 
 def desktop_open(runtime, app, user_data, codex_bin=None):
@@ -165,14 +190,20 @@ def desktop_open(runtime, app, user_data, codex_bin=None):
     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 lib.pending(): raise PackError('An incomplete operation needs recovery. Run topolo-agent-pack recover before another mutation.')
     if plan['noChange']:
         active=lib.active()
+        if live.available(lib):
+            sidebar=live.bind_sidebar(lib,active['runtime'],args.app)
+        else:
+            native.assert_idle(pathlib.Path(active['runtime'])/'home')
+            sidebar=verify_backend(lib,active['runtime'],args.codex_bin)['sidebar']
         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}
+            return {'state':active['state'],'active':active,'sidebarBinding':sidebar,'sidebar':sidebar,'sectionsRenderedVerified':False}
+        return {'state':'unchanged','active':active,'sidebar':sidebar,'sidebarBinding':sidebar,'sectionsRenderedVerified':False}
     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)
@@ -238,7 +269,7 @@ def apply_plan(lib,plan,args):
         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)
+        backend=verify_backend(lib,runtime,args.codex_bin,presentation_journal=(jpath,journal))
         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.')
@@ -247,16 +278,16 @@ def apply_plan(lib,plan,args):
         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['desktop']=live.reconnect(lib,runtime,old_runtime,args.app,presentation_journal=(jpath,journal)) 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']}
+                'desktop':after['desktop'],'backend':backend,'sidebarBinding':after['desktop'].get('sidebarBinding',backend['sidebar']),'sectionsRenderedVerified':False,'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'):
+        if bridge and journal.get('sidebar',{}).get('state') not in {'UNKNOWN','may-have-effects'} 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)
+                current=lib.active();journal['reconnectAfterFailure']=live.reconnect(lib,current['runtime'],old_runtime,args.app,presentation_journal=(jpath,journal));atomic_json(jpath,journal)
             except Exception as reconnect_error:
                 journal['reconnectFailure']=str(reconnect_error);atomic_json(jpath,journal)
         raise
@@ -265,11 +296,24 @@ def recover(lib):
     result=[]
     for path in sorted(lib.pending()):
         j=read_json(path); active=lib.active(); before=j['before']; after=j.get('after')
+        entry=j.get('sidebar')
+        if entry and entry.get('state') not in {'complete','not-executed'}:
+            context=entry['context'];runtime=entry['runtime']
+            if context['kind']=='managed':
+                live.bind_sidebar(lib,runtime,context.get('app',j.get('desktopApp','/Applications/ChatGPT.app')),reconcile=(path,j))
+            else:
+                binary=pathlib.Path(context['binary'])
+                if hashlib.sha256(binary.read_bytes()).hexdigest()!=context['binarySHA256']:
+                    raise PackError('Original sidebar recovery binary changed')
+                native.assert_idle(pathlib.Path(runtime)/'home')
+                verify_backend(lib,runtime,str(binary),reconcile=(path,j))
+            if j.get('operation')=='sidebar-bind':
+                result.append({'transaction':j['id'],'phase':j['phase'],'action':'Exact current presentation reconciled; no presentation replay.'});continue
         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'))
+            j['desktopRecovery']=live.reconnect(lib,active['runtime'],before.get('runtime'),j.get('desktopApp','/Applications/ChatGPT.app'),presentation_journal=(path,j))
             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.'
@@ -290,6 +334,8 @@ 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('desktop-launcher',help='Install the owned same-profile Agent Pack Dock launcher without opening it')
+    q.add_argument('--app',default='/Applications/ChatGPT.app');q.add_argument('--codex-bin',default=find_codex())
     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')
@@ -337,6 +383,33 @@ def parser():
     q=sub.add_parser('smoke',help='Start or read one closed, bound native acceptance case; never arbitrary prompts')
     q.add_argument('operation',choices=['start','read']);q.add_argument('identity')
     q.add_argument('--case',choices=sorted(live.SMOKE_CASES));q.add_argument('--operation-id')
+    q=sub.add_parser('work',help='Durable task dispatch and checkpoint reads on the owning connection')
+    q.add_argument('operation',choices=['submit','respond','re-review','list','read','retained','adoption-plan','adopt','wait','cutover','cutover-status','claude-hook','claude-worker-hook','bind-claude','serve-claude'])
+    q.add_argument('--input',help='Exact task request JSON')
+    q=sub.add_parser('work-recover',help='Recover verified cloud evidence to a new directory without creating or adopting work')
+    q.add_argument('--reference',required=True);q.add_argument('--destination',required=True)
+    q=sub.add_parser('work-cloud-cutover',help='Conditionally activate the existing cloud dataset from its authenticated idle native owner')
+    q.add_argument('--source-store',required=True);q.add_argument('--input',required=True)
+    q=sub.add_parser('work-closed-ledger-fence',help='Permanently fence a closed local task ledger without stopping unrelated native work')
+    q.add_argument('--input',required=True)
+    q=sub.add_parser('work-cloud-prepare-delta',help='Publish only selected closed legacy task context, final outputs and declared evidence')
+    q.add_argument('--source-store',required=True);q.add_argument('--input',required=True)
+    q=sub.add_parser('work-install',help='Prepare a three-coordinator installation from cloud specialization metadata; requires cloud authority before execution')
+    q.add_argument('--pack',required=True);q.add_argument('--agent-workspace',required=True);q.add_argument('--bytes-workspace',required=True);q.add_argument('--max-workers',type=int,default=4)
+    q=sub.add_parser('work-cloud-attach',help='Attach a clean installation to existing activated cloud task authority without dispatch')
+    q.add_argument('--input',required=True)
+    q=sub.add_parser('work-cloud-migrate',help='Plan or apply exact existing fenced Codex installation attachment without adopting cloud tasks')
+    q.add_argument('--input',required=True);q.add_argument('--apply',action='store_true')
+    q=sub.add_parser('work-renew-coordinators',help='Renew only the three canonical conversation definitions on an idle existing cloud installation')
+    q.add_argument('--input',required=True)
+    q=sub.add_parser('work-recover-claude-completion',help='Recover one exact already-delivered Claude completion without resending or starting a dispatcher')
+    q.add_argument('--input',required=True)
+    q=sub.add_parser('work-repair-model-ceilings',help='Repair stale Claude model ceilings from the existing qualified three-tier catalog only')
+    q.add_argument('--input',required=True)
+    q=sub.add_parser('work-refresh-role-refs',help='Refresh reviewed references only on the same stopped inactive cloud installation')
+    q.add_argument('--input',required=True)
+    q=sub.add_parser('work-bind-roles',help='Discover individual Agent definitions and bind metadata-only dispatch references')
+    q.add_argument('--pack',action='append',required=True);q.add_argument('--agent-workspace',required=True);q.add_argument('--bytes-workspace')
     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)
@@ -371,13 +444,14 @@ def main(argv=None):
             parser().error('--harness requires codex or claude')
         harness = argv[at + 1]
         del argv[at:at + 2]
-    policy_command = 'policy' in argv or 'permissions' in argv
     command_args=list(argv)
     if command_args and command_args[0]=='--store':command_args=command_args[2:]
     elif command_args and command_args[0].startswith('--store='):command_args=command_args[1:]
+    policy_command=bool(command_args and command_args[0] in {'policy','permissions'})
     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 and not (command_args and command_args[0]=='runtime-adoption'):
+    work_command=bool(command_args and command_args[0]=='work')
+    cloud_command=bool(command_args and command_args[0] in {'connect','remote-context','remember','artifact','artifact-get','remote-recover','work-recover','work-cloud-cutover','work-closed-ledger-fence','work-cloud-prepare-delta','work-bind-roles','work-install','work-refresh-role-refs','work-repair-model-ceilings','work-recover-claude-completion','work-cloud-attach','work-cloud-migrate','work-renew-coordinators'})
+    if harness == 'claude' and not policy_command and not cloud_command and not lane_command and not work_command and not (command_args and command_args[0]=='runtime-adoption'):
         from . import claude
         return claude.main(argv)
     if harness not in {'codex', 'claude'}:
@@ -391,7 +465,62 @@ def main(argv=None):
                 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
+        if args.command=='work-recover':
+            from .cloud_recovery import recover as recover_cloud
+            emit(recover_cloud(read_json(args.reference),args.destination))
+            return 0
+        if args.command=='work-cloud-cutover':
+            from .cloud_cutover import run
+            emit(run(args.source_store,args.store,read_json(args.input)));return 0
+        if args.command=='work-closed-ledger-fence':
+            from .closed_ledger_fence import run
+            emit(run(args.store,read_json(args.input)));return 0
+        if args.command=='work-cloud-prepare-delta':
+            from .cloud_delta import run
+            emit(run(args.source_store,args.store,read_json(args.input)));return 0
+        if args.command=='work' and args.operation=='claude-worker-hook':
+            if harness!='claude' or not args.input:raise PackError('Exact Claude worker hook binding required')
+            from .claude_runner import hook_main
+            return hook_main(args.input)
         lib=Library(args.store)
+        if args.command=='work-install':
+            from .role_catalog import install
+            emit(install(lib,args.pack,args.agent_workspace,args.bytes_workspace,args.max_workers))
+            return 0
+        if args.command=='work-cloud-attach':
+            from .cloud_attach import attach
+            emit(attach(lib,read_json(args.input)));return 0
+        if args.command=='work-renew-coordinators':
+            from .coordinator_refresh import renew
+            emit(renew(lib,read_json(args.input)));return 0
+        if args.command=='work-cloud-migrate':
+            if harness!='codex':raise PackError('Existing fenced Codex installation migration required')
+            from .cloud_migrate import plan,apply
+            value=read_json(args.input)
+            emit(apply(lib,value) if args.apply else plan(lib,value));return 0
+        if args.command=='work-recover-claude-completion':
+            if harness!='claude':raise PackError('Claude-only production native completion recovery required')
+            from .claude_completion_recovery import recover_completed
+            value=read_json(args.input)
+            if not isinstance(value,dict):raise PackError('Closed native completion recovery object required')
+            emit(recover_completed(lib,value));return 0
+        if args.command=='work-repair-model-ceilings':
+            from .role_catalog import repair_model_ceilings
+            value=read_json(args.input)
+            if not isinstance(value,dict) or set(value)!={'expectedCatalogDigest','expectedNative'}:raise PackError('Exact reviewed model ceiling repair input required')
+            emit(repair_model_ceilings(lib,value['expectedCatalogDigest'],value['expectedNative']));return 0
+        if args.command=='work-refresh-role-refs':
+            from .role_refresh import refresh_refs
+            value=read_json(args.input)
+            if not isinstance(value,dict) or set(value)!={'expectedCatalogDigest','expectedBindings','reviewedBindings'}:raise PackError('Exact reviewed role reference input required')
+            emit(refresh_refs(lib,value['expectedCatalogDigest'],value['expectedBindings'],value['reviewedBindings']));return 0
+        if args.command=='work-bind-roles':
+            from .role_context import bind
+            result=bind(lib.root/'work',[lib.load(name)[0] for name in args.pack],args.agent_workspace)
+            if args.bytes_workspace:
+                atomic_json(lib.root/'work/context-authority.json',{'format':'topolo-task-context-authority-v1','organizationId':'org_topolo_platform','workspaceId':args.bytes_workspace,'scope':'org'})
+            emit(result)
+            return 0
         if args.command in {'connect','remote-context','remember','artifact','artifact-get','remote-recover'}:
             from . import topolo
             if args.command=='remote-context' and args.continuity_input:
@@ -405,6 +534,29 @@ def main(argv=None):
                 raise PackError('Explicit Codex connection ID and reviewed input binding required')
             import asyncio
             asyncio.run(live.OwnedLaneConnection(lib,args.connection,read_json(args.input)).run());return 0
+        # Live requests are serialized by their authenticated owning service, which
+        # has its own owner lock. The setup lock must never span that service's
+        # lifetime or prevent its workers from reading/responding through the CLI.
+        if args.command=='work' and args.operation!='bind-claude':
+            if args.operation in {'claude-hook','serve-claude'}:
+                if harness!='claude':
+                    raise PackError('This operation requires the Claude owning connection')
+                if args.operation=='claude-hook':
+                    from .claude_prompt import main as hook
+                    return hook(lib.root)
+                from .claude_service import Service
+                import asyncio
+                asyncio.run(Service(lib).run());return 0
+            if harness=='claude':
+                try:status=live.request(lib,'status',{})
+                except (PackError,OSError) as exc:raise PackError('Claude cloud dispatcher is not active') from exc
+                if status.get('harness')!='claude' or status.get('cloudDispatchReady') is not True:
+                    raise PackError('Claude cloud dispatcher is not active')
+            params=read_json(args.input) if args.input else {}
+            if args.operation=='wait':
+                from .work_wait import wait
+                emit(wait(lib,params));return 0
+            emit(live.request(lib,'work-'+args.operation,params));return 0
         with lib.lock():
             if args.command=='lane':
                 from .lanes import Registry
@@ -433,6 +585,13 @@ def main(argv=None):
                 elif harness!='codex':
                     raise PackError('Use the native Claude lane adapter with its qualified connection')
                 else: result=(live.request_lane(lib,args.connection,'lane-'+args.operation,params) if args.connection else live.request(lib,'lane-'+args.operation,params))
+            elif args.command=='work':
+                if harness!='claude':
+                    raise PackError('This operation requires the Claude owning connection')
+                if not args.input:
+                    raise PackError('Exact native coordinator binding required')
+                from .claude_service import install
+                emit(install(lib.root,read_json(args.input)));return 0
             elif args.command=='smoke':
                 if args.operation=='start':
                     if not args.case or not args.operation_id:
@@ -514,17 +673,23 @@ def main(argv=None):
                     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=='desktop-launcher':
+                from .desktop_launcher import install
+                result=install(lib,args.app,args.codex_bin)
             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)}
+                bridge=live.available(lib)
+                if bridge:
+                    from .desktop_launcher import restore
+                    result=restore(lib,bridge,args.app)
                 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)}
+                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),'sidebarBinding':read_json(pathlib.Path(active['runtime'])/'sidebar-binding.json',{}) if active.get('runtime') else None,'sectionsRenderedVerified':False}
             elif args.command=='doctor':
                 checked=[]
                 if args.name:

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

@@ -0,0 +1,118 @@
+"""Fixed-schema closed-ledger migration barrier; unrelated native turns keep running."""
+import hashlib,json,os,pathlib,sqlite3,uuid
+from types import SimpleNamespace
+from .storage import atomic_json,canonical,read_json,sync_directory
+from .work import require
+from .cloud_cutover import snapshot,digest,birth
+
+CAPABILITY='topolo-closed-ledger-fence-v1'
+META='_topolo_closed_ledger_fence'
+TABLES={'tasks':('id','input_hash','body'),'workers':('id','task_id','body'),'events':('sequence','task_id','body'),'responses':('id','input_hash','task_id'),'retained':('id','body'),'sqlite_sequence':('name','seq')}
+META_SQL='CREATE TABLE '+META+' (operation_id TEXT PRIMARY KEY, body TEXT NOT NULL)'
+TABLE_SQL={'tasks':'CREATE TABLE tasks(id TEXT PRIMARY KEY, input_hash TEXT NOT NULL, body TEXT NOT NULL)','workers':'CREATE TABLE workers(id TEXT PRIMARY KEY,task_id TEXT NOT NULL,body TEXT NOT NULL)','events':'CREATE TABLE events(sequence INTEGER PRIMARY KEY AUTOINCREMENT, task_id TEXT NOT NULL, body TEXT NOT NULL)','responses':'CREATE TABLE responses(id TEXT PRIMARY KEY,input_hash TEXT NOT NULL,task_id TEXT NOT NULL)','retained':'CREATE TABLE retained(id TEXT PRIMARY KEY,body TEXT NOT NULL)','sqlite_sequence':'CREATE TABLE sqlite_sequence(name,seq)'}
+
+def triggers():
+    result={'_topolo_fence_'+table+'_'+op.lower():"CREATE TRIGGER _topolo_fence_"+table+'_'+op.lower()+' BEFORE '+op+' ON '+table+" BEGIN SELECT RAISE(ABORT, 'legacy task ledger is permanently cloud fenced'); END" for table in TABLES if table!='sqlite_sequence' for op in ['INSERT','UPDATE','DELETE']}
+    for op in ['INSERT','UPDATE','DELETE']:
+        name='_topolo_fence_receipt_'+op.lower()
+        result[name]='CREATE TRIGGER '+name+' BEFORE '+op+' ON '+META+(' WHEN EXISTS(SELECT 1 FROM '+META+')' if op=='INSERT' else '')+" BEGIN SELECT RAISE(ABORT, 'immutable closed ledger fence receipt'); END"
+    return result
+
+def code_digest():
+    base=pathlib.Path(__file__).parent
+    return digest({name:hashlib.sha256((base/name).read_bytes()).hexdigest() for name in ['closed_ledger_fence.py','cloud_cutover.py']})
+
+def owned(path,directory=False):
+    path=pathlib.Path(path);st=path.lstat()
+    require(path.is_absolute() and path.resolve()==path and not path.is_symlink() and st.st_uid==os.getuid() and not st.st_mode&0o022 and (path.is_dir() if directory else path.is_file() and st.st_nlink==1),'Closed ledger path ownership differs')
+    return {'path':str(path),'device':st.st_dev,'inode':st.st_ino,'uid':st.st_uid,'mode':st.st_mode&0o777}
+
+def identity(root):
+    return {name:owned(root/suffix,directory=name!='database') for name,suffix in [('root','.'),('work','work'),('database','work/tasks.sqlite')]}
+
+def schema(db,fenced):
+    tables={row[0] for row in db.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+    require(tables==set(TABLES)|({META} if fenced else set()),'Closed ledger schema table inventory differs')
+    for table,columns in {**TABLES,**({META:('operation_id','body')} if fenced else {})}.items():
+        require(tuple(row[1] for row in db.execute('PRAGMA table_info('+table+')'))==columns,'Closed ledger schema columns differ')
+    require(dict(db.execute("SELECT name,sql FROM sqlite_master WHERE type='table'"))=={**TABLE_SQL,**({META:META_SQL} if fenced else {})},'Closed ledger schema definitions differ')
+    actual={row[0]:row[1] for row in db.execute("SELECT name,sql FROM sqlite_master WHERE type='trigger'")}
+    require(actual==(triggers() if fenced else {}),'Closed ledger fixed write guards differ')
+    return digest([list(row) for row in db.execute('SELECT type,name,tbl_name,sql FROM sqlite_master ORDER BY type,name')])
+
+def owner(root,observe=None):
+    from . import live
+    bridge=root/'live-bridge.json';owned(bridge)
+    before=read_json(bridge)
+    require(set(before)=={'pid','socket','token'},'Native owner bridge fields differ')
+    result=(observe or (lambda r:live.request(SimpleNamespace(root=r),'status')))(root)
+    require(read_json(bridge)==before and result['pid']==before['pid'] and isinstance(result['activeTurns'],list) and all(isinstance(x,str) for x in result['activeTurns']) and isinstance(result['runtime'],str),'Authenticated native roster changed')
+    return {'pid':result['pid'],'birth':birth(result['pid']),'runtime':result['runtime'],'tokenDigest':hashlib.sha256(before['token'].encode()).hexdigest()},set(result['activeTurns'])
+
+def disjoint(state,active):
+    workers={json.loads(row[2]).get('nativeId') for row in state['tables']['workers']}
+    require(not workers.intersection(active),'A ledger worker still owns an active native turn')
+
+def target(request):
+    root=pathlib.Path(request['destinationRoot']);owned(root,True);owned(root/'work',True);owned(root/'work/cloud.json')
+    binding=read_json(root/'work/cloud.json')
+    require(binding['format']=='topolo-cloud-work-binding-v1' and binding['organizationId']=='org_topolo_platform' and all(binding[k]==request[k] for k in ['documentId','datasetId']),'Existing target cloud authority differs')
+    return digest(binding)
+
+def validate_request(root,request):
+    require(set(request)=={'operationId','sourceDigest','proxyPid','runtime','destinationRoot','documentId','datasetId','expectedCurrentVersionId'},'Exact closed ledger migration selectors required')
+    require(all(isinstance(request[k],str) and bool(request[k]) for k in ['operationId','sourceDigest','runtime','destinationRoot','documentId','datasetId','expectedCurrentVersionId']) and type(request['proxyPid']) is int and request['proxyPid']>0,'Closed ledger selector types differ')
+    require(len(request['sourceDigest'])==64 and all(c in '0123456789abcdef' for c in request['sourceDigest']),'Reviewed snapshot digest is invalid')
+    require(pathlib.Path(request['runtime']).is_absolute() and pathlib.Path(request['runtime']).resolve()==pathlib.Path(request['runtime']) and pathlib.Path(request['runtime']).is_relative_to(root/'runtimes'),'Native runtime is outside the source installation')
+    require(str(uuid.UUID(request['operationId']))==request['operationId'] and pathlib.Path(request['destinationRoot']).resolve()!=root,'Distinct migration operation and target required')
+
+def verify(root,observe=None):
+    root=pathlib.Path(root).resolve();ident=identity(root);journal=root/'work/cutover.json';owned(journal)
+    saved=read_json(journal)
+    require(saved['format']==CAPABILITY,'Closed ledger capability differs')
+    native,active=owner(root,observe)
+    db=sqlite3.connect('file:'+str(root/'work/tasks.sqlite')+'?mode=ro',uri=True)
+    try:
+        db.execute('BEGIN');rows=db.execute('SELECT operation_id,body FROM '+META).fetchall()
+        require(len(rows)==1,'Closed ledger durable receipt is ambiguous')
+        record=json.loads(rows[0][1]);require(rows[0][0]==saved['operationId']==record['operationId'],'Closed ledger operation identity differs')
+        require(record['format']==CAPABILITY and record['state']=='ledger-fenced' and record['root']==str(root) and record['databaseIdentity']==ident and record['codeDigest']==code_digest() and record['nativeOwner']==native,'Closed ledger ownership or executing source changed')
+        require(saved==record or saved=={'format':CAPABILITY,'operationId':record['operationId'],'state':'prepared','request':record['request']},'Closed ledger file receipt changed')
+        require(target(record['request'])==record['targetBindingDigest'] and schema(db,True)==record['schemaDigest'],'Closed ledger target or schema changed')
+        state=snapshot(db);disjoint(state,active)
+        require(digest(state)==record['sourceDigest']==digest(record['snapshot']),'Closed ledger source checkpoint changed')
+    finally:db.close()
+    require(identity(root)==ident,'Closed ledger file identity changed during observation')
+    return record
+
+def run(root,request,observe=None):
+    root=pathlib.Path(root).resolve();validate_request(root,request);ident=identity(root);binding=target(request)
+    journal=root/'work/cutover.json'
+    if journal.exists():
+        record=verify(root,observe)
+        require(record['request']==request,'Existing ledger fence request differs; no replay')
+        return record
+    native,active=owner(root,observe)
+    require(native['pid']==request['proxyPid'] and native['runtime']==request['runtime'],'Reviewed native owner differs')
+    prepared={'format':CAPABILITY,'operationId':request['operationId'],'state':'prepared','request':request}
+    fd=os.open(journal,os.O_WRONLY|os.O_CREAT|os.O_EXCL|os.O_NOFOLLOW,0o600)
+    with os.fdopen(fd,'wb') as file:file.write(canonical(prepared));file.flush();os.fsync(file.fileno())
+    sync_directory(journal.parent)
+    db=sqlite3.connect(root/'work/tasks.sqlite',timeout=10)
+    try:
+        db.execute('BEGIN IMMEDIATE');require(identity(root)==ident and read_json(journal)==prepared,'Source identity changed before fence')
+        current,active=owner(root,observe);require(current==native,'Native owner changed while awaiting ledger admission')
+        schema(db,False);state=snapshot(db);disjoint(state,active)
+        require(digest(state)==request['sourceDigest'],'Reviewed closed ledger snapshot changed')
+        db.execute(META_SQL)
+        for sql in triggers().values():db.execute(sql)
+        record={'format':CAPABILITY,'operationId':request['operationId'],'state':'ledger-fenced','root':str(root),'request':request,'databaseIdentity':ident,'nativeOwner':native,'codeDigest':code_digest(),'targetBindingDigest':binding,'schemaDigest':schema(db,True),'sourceDigest':digest(state),'snapshot':state,'unrelatedNativeTurnsPreserved':True}
+        require(len(canonical(record))<=900000,'Closed ledger receipt exceeds bound')
+        db.execute('INSERT INTO '+META+' VALUES (?,?)',(request['operationId'],canonical(record).decode()));db.commit()
+    except BaseException:db.rollback();raise
+    finally:db.close()
+    # A lost file acknowledgement is recovered from the immutable native DB row;
+    # another call can only verify that row, never execute the fence again.
+    actual=verify(root,observe);require(actual==record,'Committed ledger fence differs')
+    atomic_json(journal,record)
+    return record

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

@@ -0,0 +1,128 @@
+"""Attach a clean installation to existing cloud authority; never dispatch work."""
+import json
+import os
+import re
+import types
+
+from . import permissions, topolo
+from .cloud_work import CloudStore
+from .role_catalog import COORDINATORS, digest
+from .storage import atomic_json, canonical, read_json, sync_directory
+from .work import require
+
+FIELDS = {'pack', 'workspaceId', 'documentId', 'datasetId', 'installationId',
+          'expectedCurrentVersionId', 'expectedCatalogDigest'}
+METADATA = {'config.json', 'role-catalog.json', 'role-bindings.json', 'context-authority.json',
+            'cloud-attach.json', 'cloud.json'}
+
+
+def owned(path, directory=False):
+    stat = path.lstat()
+    require(not path.is_symlink() and stat.st_uid == os.getuid() and not stat.st_mode & 0o077
+            and (path.is_dir() if directory else path.is_file()), 'Private owned installation metadata required')
+
+
+def attach(lib, request, client=None):
+    require(isinstance(request, dict) and set(request) == FIELDS
+            and all(isinstance(v, str) and 1 <= len(v) <= 240 for v in request.values())
+            and re.fullmatch(r'[a-z0-9][a-z0-9-]{0,119}', request['installationId']),
+            'Exact cloud attachment selectors required')
+    with lib.lock():
+        return attach_locked(lib, request, client)
+
+
+def clean(lib, root):
+    owned(root, True)
+    require(not lib.active().get('components') and not lib.pending(), 'Clean stopped installation required')
+    require({p.name for p in root.iterdir()} <= METADATA, 'Local tasks, pending writes or unknown metadata prohibit attachment')
+    for path in root.iterdir():
+        owned(path)
+    for path in [lib.root / 'live-bridge.json', root / 'claude-frontdoors.json']:
+        require(not path.exists(), 'Existing native owner metadata prohibits attachment')
+    for name in ['startup-operation.json', 'native-operation.json', 'active.json', 'state.json']:
+        require(not (lib.root / 'claude' / name).exists(), 'Existing Claude preparation or startup prohibits fresh attachment')
+
+
+def attach_locked(lib, request, client):
+    root = lib.root / 'work'
+    clean(lib, root)
+    saved = read_json(root / 'config.json')
+    catalog = read_json(root / 'role-catalog.json')
+    registry = read_json(root / 'role-bindings.json')
+    manifest, revision = lib.load(request['pack'])
+    agents = manifest['agents']
+    require(set(saved) == {'format', 'pack', 'catalogDigest', 'maxWorkers', 'frontdoorDispatch', 'requireCloudAuthority'}
+            and saved['format'] == 'topolo-task-dispatch-v2' and saved['pack'] == request['pack']
+            and saved['frontdoorDispatch'] is True and saved['requireCloudAuthority'] is True
+            and type(saved['maxWorkers']) is int and 1 <= saved['maxWorkers'] <= 8,
+            'Qualified three-coordinator cloud configuration required')
+    require(len(agents) == 3 and {(a['set'], a['id']) for a in agents} == {('intakes', v) for v in COORDINATORS.values()}
+            and catalog['pack'] == request['pack'] and catalog['nativePackRevision'] == revision
+            and catalog['format'] == 'topolo-task-role-catalog-v1'
+            and saved['catalogDigest'] == request['expectedCatalogDigest'] == digest(catalog)
+            and registry.get('organizationId') == 'org_topolo_platform' and registry.get('roles') == catalog['bindings']
+            and set(catalog['channels']) == set(COORDINATORS), 'Reviewed role catalog differs')
+    owned(lib.root / 'permissions' / (request['pack'] + '.json'))
+    consent = permissions.load(lib, request['pack'], agents)
+    require(consent and consent.get('sourceRevision') == revision and consent.get('environment') == 'production'
+            and consent['contextKey'] == 'org:org_topolo_platform'
+            and consent['intakeRoutes'] == {request['pack'] + '/intakes/' + a['id']: request['pack'] + '/intakes/' + a['id'] for a in agents}
+            and all(ref.get('workspaceId') == consent.get('agentWorkspaceId') for ref in registry['roles'].values()),
+            'Current production installation consent required')
+    if client is None:
+        client = topolo.Client('production', 'org:org_topolo_platform')
+    require(client.environment == 'production' and client.context == consent['contextKey'], 'Production cloud reader context differs')
+    actor = client.run(['whoami'])
+    require(actor.get('organization', {}).get('id') == 'org_topolo_platform'
+            and actor.get('user', {}).get('id') == consent['principalId'], 'Current production identity differs')
+    _, policy = topolo.organization_execution_policy(client, consent, agents, consent.get('agentWorkspaceId'))
+    permissions.authorize_native_scope(policy)
+    binding = {'format': 'topolo-cloud-work-binding-v1', 'organizationId': 'org_topolo_platform',
+               **{k: request[k] for k in ['workspaceId', 'documentId', 'datasetId', 'installationId']}}
+    # Reuse the exact current-only authenticated reader before publishing a binding.
+    version, state = CloudStore.load(types.SimpleNamespace(binding=binding, client=client))
+    journal_path, binding_path = root / 'cloud-attach.json', root / 'cloud.json'
+    journal = read_json(journal_path, {})
+    pins = {'catalog': digest(catalog), 'registry': digest(registry), 'config': digest(saved), 'consent': digest(consent), 'revision': revision}
+    if journal:
+        require(set(journal) == {'format', 'state', 'request', 'binding', 'pins', 'cloudVersion', 'cloudDigest', 'verifiedCloudVersion', 'verifiedCloudDigest'}
+                and journal['format'] == 'topolo-cloud-attach-v1' and journal['state'] in {'prepared', 'verified'}
+                and journal['request'] == request and journal['binding'] == binding and journal['pins'] == pins,
+                'Existing cloud attachment requires its original exact selectors and metadata')
+        require(binding_path.exists() and read_json(binding_path) == binding, 'Attachment write is uncertain; no automatic replay')
+    else:
+        require(not binding_path.exists(), 'Existing unverified cloud binding cannot be replaced')
+    verified = journal.get('state') == 'verified'
+    require(journal or version == request['expectedCurrentVersionId'], 'Expected current cloud version changed')
+    if not verified:
+        for table in ['tasks', 'workers']:
+            for row in state['tables'][table]:
+                body = json.loads(row[2])
+                require(request['installationId'] not in [body.get('ownerInstallationId'), body.get('installationId'),
+                        body.get('nativePlan', {}).get('installationId')], 'Installation identity already owns recorded work')
+    # Awaited identity/policy/Docs reads must not race installation metadata changes.
+    require(read_json(root / 'config.json') == saved and read_json(root / 'role-catalog.json') == catalog
+            and read_json(root / 'role-bindings.json') == registry
+            and permissions.load(lib, request['pack'], agents) == consent
+            and lib.load(request['pack'])[1] == revision and not lib.active().get('components') and not lib.pending(),
+            'Installation metadata changed during attachment')
+    clean(lib, root)
+    if verified:
+        return {'state': 'cloud-authority-attached', 'alreadyApplied': True, 'binding': binding, 'tasksCreated': 0, 'workersAdopted': 0}
+    resumed = bool(journal)
+    if not journal:
+        journal = {'format': 'topolo-cloud-attach-v1', 'state': 'prepared', 'request': request, 'binding': binding,
+                   'pins': pins, 'cloudVersion': version, 'cloudDigest': digest(state),
+                   'verifiedCloudVersion': None, 'verifiedCloudDigest': None}
+        # The library lock serializes the exclusive journal reservation.
+        with journal_path.open('x', encoding='utf8') as stream:
+            os.chmod(journal_path, 0o600)
+            stream.write(canonical(journal).decode()); stream.flush(); os.fsync(stream.fileno())
+        sync_directory(root)
+        atomic_json(binding_path, binding)
+    require(read_json(binding_path) == binding, 'Cloud binding readback differs; reconcile without replay')
+    verified_record = {**journal, 'state': 'verified', 'verifiedCloudVersion': version, 'verifiedCloudDigest': digest(state)}
+    atomic_json(journal_path, verified_record)
+    require(read_json(journal_path) == verified_record, 'Cloud attachment acknowledgement is uncertain')
+    return {'state': 'cloud-authority-attached', 'alreadyApplied': False, 'binding': binding,
+            'tasksCreated': 0, 'workersAdopted': 0, 'cloudTaskStateChanged': False, 'reconciled': resumed}