@topolo/cli 0.13.17 → 0.13.21

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

@@ -0,0 +1,414 @@
+"""Event-driven task dispatch on the existing owning native connection.
+
+No extra app server, renderer automation, schedule or parallel thread reuse.
+"""
+import asyncio
+import copy
+import hashlib
+import json
+import pathlib
+import shutil
+import time
+from . import task_models, policy
+from .execution import ExecutionGate
+from .cicd import RELEASE_RISK_TYPES
+from .storage import PackError, read_json, atomic_json, canonical, component_key
+from .work import Store, require, parse_route, TERMINAL
+
+class Broker:
+    def __init__(self,owner):
+        from .cloud_work import open_store
+        self.owner=owner;self.store=open_store(owner.lib.root);self.lock=asyncio.Lock();self.jobs=set();self.watchers=set();self.native_ids=set()
+        from .cloud_cutover import closure
+        self.cutover_closure=closure();self.cutover_record=None
+    def writable(self):
+        require(not getattr(self.owner,'quiesced',False),'Native task admission is quiesced for cutover')
+        if (self.store.root/'cutover.json').exists():
+            require(getattr(self.store,'cloud',False),'Native task admission is quiesced for cutover')
+            from .cloud_migrate import verified
+            verified(self.store.root.parent)
+    async def quiesce(self,cutover=False):
+        async with self.lock:
+            self.writable()
+            require(not any(not job.done() for job in self.jobs),'Native task broker jobs are still live')
+            require(not self.owner.active_turns and not self.owner.pending,'Native task delivery is still live')
+            from .cloud_cutover import freeze,acknowledge
+            if cutover:record=freeze(self.owner)
+            else:
+                require(all(w['state']=='archived' and w.get('nativeArchived') is True or w['state']=='failed' and not w.get('turnId') and (not w.get('nativeId') or w.get('nativeArchived') is True) for w in await self.state_call('workers')),'Native worker closure is unresolved')
+            self.owner.quiesced=True
+            await self.owner.stop_child()
+            if cutover:self.cutover_record=acknowledge(self.owner,record)
+            return self.cutover_record
+    async def state_call(self,name,*args,**kwargs):
+        from .cloud_work import READS
+        if name not in READS:self.writable()
+        method=getattr(self.store,name)
+        return await asyncio.to_thread(method,*args,**kwargs) if getattr(self.store,'cloud',False) else method(*args,**kwargs)
+    async def initialize(self):
+        self.native_ids={w['nativeId'] for w in await self.state_call('workers') if w.get('nativeId')}
+        await self.state_call('recover')
+        if read_json(self.store.root/'config.json',{}).get('frontdoorDispatch') is True:
+            from .role_context import materialize as materialize_role
+            for role in self.owner.execution.roles.values():
+                if '/intakes/' in role['key']:
+                    await asyncio.to_thread(materialize_role,self.store.root,role['key'],pathlib.Path(role['cwd']))
+    async def resume_ready(self):
+        if (self.store.root/'cloud-migration.json').exists():
+            from .cloud_migrate import verified
+            verified(self.store.root.parent)
+            # Attaching this installation never transfers another installation's
+            # task custody, including otherwise resumable cloud checkpoints.
+            return
+        if not getattr(self.store,'cloud',False) or read_json(self.store.root/'config.json',{}).get('format')!='topolo-task-dispatch-v2':return
+        try:
+            tasks=await self.state_call('list')
+            if not any(t['state'] in {'queued','executing','reviewing'} for t in tasks):return
+            await self.owner.ensure_catalog()
+            for role in list(self.owner.execution.roles.values()):
+                if '/intakes/' not in role['key']:continue
+                require(role.get('installationConsent') and role['settings']['sandbox_mode']=='danger-full-access' and role['settings']['approval_policy']=='never','Fresh coordinators need qualified full-access installation consent before resumption')
+                await self.owner.qualify_organization(role['threadId'])
+            workers=await self.state_call('workers')
+            for task in tasks:
+                if task.get('ownerInstallationId')==self.store.binding['installationId'] or task.get('resumeAfterCheckpoint') is not True or task['state'] not in {'queued','executing','reviewing'}:continue
+                owned=[w for w in workers if w['taskId']==task['id']]
+                phase={'queued':'route','executing':'execute','reviewing':'review'}[task['state']]
+                if any(w['phase']==phase and w.get('attempt',1)==task.get('attempt',1) and (phase!='review' or w.get('reviewGeneration',0)==task.get('reviewGeneration',0)) for w in owned):continue
+                if not all(w['state']=='archived' and w.get('nativeArchived') is True or w['state']=='failed' and not w.get('turnId') and (not w.get('nativeId') or w.get('nativeArchived') is True) for w in owned):continue
+                await self.state_call('adopt_ready',task['id'],task['revision'])
+            self.owner.work_startup_error=None
+            await self.pump();await self.notify()
+        except Exception as exc:self.owner.work_startup_error=str(exc)
+    async def snapshot(self):
+        if getattr(self.store,'cloud',False):return await asyncio.to_thread(self.store.snapshot)
+        return {'tasks':(await self.state_call('list',)),'workers':(await self.state_call('workers',)),'events':(await self.state_call('events',)),'retainedCount':len((await self.state_call('retained',))),'authority':'local-migration-source'}
+    async def read(self,tid):
+        return {'task':await self.state_call('get',tid),'events':await self.state_call('events',tid)}
+    def config(self,channel='engineering'):
+        p=self.store.root/'config.json';require(p.is_file() and not p.is_symlink(),'Task dispatch is not installed for this runtime')
+        saved=read_json(p)
+        if saved.get('format')=='topolo-task-dispatch-v2':
+            from .role_catalog import configuration
+            require(getattr(self.store,'cloud',False),'Source-independent dispatch requires activated cloud task authority; no local fallback')
+            return configuration(self.owner,saved,channel)
+        require(set(saved)-{'authority','frontdoorDispatch'} in ({'pack','revision','templateRuntime','maxWorkers'},{'pack','revision','templateRuntime','maxWorkers','channels'}),'Invalid work dispatch configuration')
+        require('authority' not in saved or (saved['authority']=='topolo-docs' and getattr(self.store,'cloud',False)),'Task dispatch requires its selected cloud authority')
+        require(channel in {'engineering','operations','cicd'},'Unknown task channel')
+        selected=saved.get('channels',{}).get(channel)
+        if selected is None:
+            require(channel!='cicd','CI/CD task templates are not installed')
+            config={k:saved[k] for k in ['pack','revision','templateRuntime','maxWorkers']}
+            config.update(intakeRole='engineering' if channel=='engineering' else 'operator-01',reviewRole='adversarial-qa' if channel=='engineering' else 'workflow-integration-specialist')
+        else:
+            require(isinstance(selected,dict) and set(selected)=={'pack','revision','templateRuntime','intakeRole','reviewRole'},'Invalid channel binding')
+            config={**selected,'maxWorkers':saved['maxWorkers']}
+        m,revision=self.owner.lib.load(config['pack']);require(revision==config['revision'],'Role template revision changed; review before dispatch')
+        current=self.owner.lib.active();expected=config['pack']+'/intakes/'+config['intakeRole']
+        matches=[c for c in current['components'] if c['key']==expected]
+        require(len(matches)==1 and self.owner.execution.roles.get(matches[0]['threadId'],{}).get('key')==expected,'Task channel has no current owned coordinator')
+        require(type(config['maxWorkers']) is int and 1<=config['maxWorkers']<=8,'Invalid native capacity')
+        template=pathlib.Path(config['templateRuntime']);require(template.is_relative_to(self.owner.lib.root/'runtimes') and template.is_dir() and not template.is_symlink(),'Template runtime is outside owned storage')
+        model_config=read_json(self.owner.lib.root/'dynamic-models'/(config['pack']+'.json'));require(model_config['sourceRevision']==revision,'Task model policy revision is stale')
+        if (self.store.root/'cloud-migration.json').exists():
+            from .cloud_migrate import verified
+            migration=verified(self.store.root.parent);require(getattr(self.store,'cloud',False),'Verified cloud authority required')
+            selected=migration['channelRoleKeys'][channel]
+            require({component_key(a) for a in m['agents']}>=set(selected),'Reviewed channel specialization is missing')
+            m={**m,'sourceIndependent':True,'agents':[a for a in m['agents'] if component_key(a) in selected]}
+            config['catalogOnly']=True
+        return config,m,model_config
+    async def notify(self):
+        data=canonical({'sequence':(await self.state_call('events',))[-1]['sequence'] if (await self.state_call('events',)) else 0})+b'\n'
+        for writer in list(self.watchers):
+            try:writer.write(data);await writer.drain()
+            except (ConnectionError,OSError):self.watchers.discard(writer)
+    async def watch(self,reader,writer):
+        self.watchers.add(writer)
+        try:
+            writer.write(canonical({'connected':True})+b'\n');await writer.drain();await reader.read()
+        finally:self.watchers.discard(writer)
+    def launch(self,coroutine):
+        if getattr(self.owner,'quiesced',False):
+            coroutine.close();return
+        job=asyncio.create_task(coroutine);self.jobs.add(job);job.add_done_callback(self.jobs.discard)
+    async def submit(self,request):
+        self.writable()
+        self.config(request.get('channel') if isinstance(request,dict) else None);task,created=(await self.state_call('submit',request))
+        if created:self.launch(self.pump())
+        await self.notify();return {'task':task,'created':created,'delivery':'durable_request_not_completion'}
+    async def adoption_plan(self,request):
+        from .work_adoption import validate,read_evidence,plan
+        validate(request)
+        _,manifest,_=self.config(request['channel'])
+        require(getattr(self.store,'cloud',False),'Retained continuation requires activated cloud authority')
+        rows=[r for r in await self.state_call('retained') if r.get('claimId')==request['canonicalClaimId']]
+        require(len(rows)==1,'Unknown or ambiguous canonical claim; preserve custody')
+        claim=await asyncio.to_thread(read_evidence,self.store,request['checkpointRef'])
+        return plan(request,rows[0],claim,{a['id'] for a in manifest['agents'] if a['set']!='intakes'})
+    async def adopt_retained(self,request):
+        from .work_adoption import read_evidence,verify_authority
+        from . import permissions
+        async with self.lock:
+            self.writable()
+            prepared=await self.adoption_plan(request)
+            config,_,_=self.config(request['channel']);manifest,revision=self.owner.lib.load(config['pack'])
+            consent=permissions.load(self.owner.lib,config['pack'],manifest['agents'])
+            require(isinstance(consent,dict) and consent.get('pack')==config['pack'] and consent.get('sourceRevision')==revision,
+                    'Current installation consent source revision differs')
+            actor=await asyncio.to_thread(self.store.client.run,['whoami'])
+            authorization=await asyncio.to_thread(read_evidence,self.store,request['authorizationRef'])
+            receipt=verify_authority(request,prepared,authorization,actor,consent,self.store.binding['installationId'])
+            current=await self.adoption_plan(request)
+            require(current==prepared,'Canonical checkpoint changed during authorization')
+            task,created=await self.state_call('adopt_retained',request,prepared,receipt)
+        if created:self.launch(self.pump())
+        await self.notify()
+        return {'task':task,'created':created,'delivery':'human_authorized_diagnostic_dispatch_pending'}
+    async def frontdoor(self,value):
+        role=self.owner.execution.roles.get(value.get('params',{}).get('threadId'),{})
+        parts=role.get('key','').split('/')
+        if len(parts)!=3 or parts[1]!='intakes':return value
+        saved=read_json(self.store.root/'config.json',{})
+        if saved.get('frontdoorDispatch') is not True:return value
+        channel={'engineering':'engineering','operator-01':'operations','cicd':'cicd'}.get(parts[2])
+        require(channel is not None,'This legacy coordinator is not an active front door')
+        from .coordinator_context import context,augment
+        selected=context(self.owner.lib.root,channel,role['threadId'],value['params'].get('clientUserMessageId'),await self.snapshot(),'codex')
+        return augment(value,selected)
+    async def respond(self,request):
+        self.writable()
+        task,created=(await self.state_call('respond',request))
+        if created and task['state']=='queued':self.launch(self.pump())
+        await self.notify();return {'task':task,'created':created}
+    async def re_review(self,request):
+        async with self.lock:
+            self.writable()
+            task,created=await self.state_call('re_review',request)
+        if created:self.launch(self.pump())
+        await self.notify()
+        return {'task':task,'created':created,'executionReplayed':False}
+    async def reconcile_unstarted(self,params):
+        require(isinstance(params,dict) and set(params)=={'workerId'},'Exact worker identity required')
+        async with self.lock:
+            self.writable()
+            worker=(await self.state_call('worker',params['workerId']));owner=self.owner
+            require(worker['state'] in {'creating','unknown','archiving'} and not worker.get('turnId') and worker.get('nativeId'),'Only an owned worker without a sent turn can reconcile here')
+            tid=worker['nativeId'];require(tid not in owner.active_turns,'Worker is active; preserve custody')
+            native=await owner.call_native('thread/read',{'threadId':tid,'includeTurns':True})
+            thread=native.get('thread',{})
+            require(thread.get('id')==tid and thread.get('cwd')==worker['cwd'] and thread.get('turns')==[],
+                    'Native history is not an empty owned worker; preserve custody without replay')
+            (await self.state_call('worker_update',worker['id'],{'state':'archiving'}))
+            await owner.call_native('thread/archive',{'threadId':tid})
+            listing=await owner.call_native('thread/list',{'limit':100,'archived':False})
+            require(tid not in {r['id'] for r in listing['data']},'Unstarted worker remains active')
+            (await self.state_call('worker_update',worker['id'],{'state':'failed','nativeArchived':True,'error':'Verified empty native history; archived without retry.'}))
+            owner.execution.roles.pop(tid,None);owner.execution.verified.discard(tid);self.persist()
+            task=(await self.state_call('get',worker['taskId']));(await self.state_call('update',task['id'],task['revision'],{'state':'blocked','summary':'Verified no native turn was sent. Empty worker archived; no task replayed.'},'unstarted-worker-reconciled'))
+            await self.notify()
+            return {'workerId':worker['id'],'nativeId':tid,'nativeTurns':0,'archived':True,'replayed':False}
+    async def reconcile_route(self,params):
+        require(isinstance(params,dict) and set(params)=={'taskId'},'Exact task identity required')
+        async with self.lock:
+            self.writable()
+            task=(await self.state_call('get',params['taskId']));require(task['state']=='blocked' and task['phase']=='route','Only a blocked routing result can reconcile')
+            workers=[w for w in (await self.state_call('workers',)) if w['taskId']==task['id'] and w['phase']=='route' and w.get('attempt',1)==task.get('attempt',1)]
+            require(len(workers)==1 and workers[0]['state']=='archived','Routing worker closure is unresolved')
+            proof=workers[0]['checkpoint']
+            if 'artifact' in proof:
+                from .work_artifacts import read_checkpoint
+                payload=await asyncio.to_thread(read_checkpoint,self.store.root,proof,task['id'],workers[0]['id'])
+                require(payload['phase']=='route' and payload['nativeReceipt']['status']=='completed' and payload['nativeReceipt']['toolItems']==0,'Saved routing checkpoint needs effect reconciliation')
+                actual={'status':'completed','items':[{'type':'agentMessage','text':payload['output']}]}
+            else:
+                path=pathlib.Path(proof['path'])
+                require(path.is_relative_to(self.store.root/'checkpoints'/task['id']) and not path.is_symlink() and hashlib.sha256(path.read_bytes()).hexdigest()==proof['sha256'],'Routing checkpoint changed')
+                actual=read_json(path)['nativeTurn']
+            require(actual['status']=='completed','Routing turn did not complete')
+            output='\n'.join(i.get('text','') for i in actual.get('items',[]) if i.get('type')=='agentMessage' and i.get('phase')!='commentary')
+            _,manifest,_=self.config(task['channel']);route=parse_route(output,{a['id'] for a in manifest['agents'] if a['set']!='intakes'})
+            result=(await self.state_call('update',task['id'],task['revision'],{'state':'executing','phase':'execute','route':route,'summary':'Saved routing result reconciled; no router turn replayed.'},'routing-checkpoint-reconciled'))
+        self.launch(self.pump());await self.notify();return {'task':result,'routingReplayed':False}
+    async def pump(self):
+        async with self.lock:
+            if getattr(self.owner,'quiesced',False):
+                return
+            try:self.writable();config,manifest,models=self.config()
+            except PackError:return
+            workers=(await self.state_call('workers',));occupied=sum(w['state'] in {'reserved','creating','running','archiving','unknown'} for w in workers)
+            if occupied>=config['maxWorkers']:
+                return
+            for task in reversed((await self.state_call('list',))):
+                if occupied>=config['maxWorkers']:break
+                if task['state'] in TERMINAL:continue
+                if getattr(self.store,'cloud',False) and task.get('ownerInstallationId')!=self.store.binding['installationId']:continue
+                phase={'queued':'route','routing':'route','executing':'execute','reviewing':'review'}[task['state']]
+                if any(w['taskId']==task['id'] and w['phase']==phase and w.get('attempt',1)==task.get('attempt',1) and (phase!='review' or w.get('reviewGeneration',0)==task.get('reviewGeneration',0)) for w in workers):continue
+                try:
+                    channel_config,channel_manifest,channel_models=self.config(task['channel'])
+                    await self.start(task,phase,channel_config,channel_manifest,channel_models);occupied+=1
+                except Exception as exc:
+                    current=await self.state_call('get',task['id'])
+                    if getattr(self.store,'cloud',False) and current.get('ownerInstallationId')!=self.store.binding['installationId']:continue
+                    if current['state']=='unknown':
+                        await self.notify()
+                        continue
+                    for reserved in (await self.state_call('workers',)):
+                        if reserved['taskId']==task['id'] and reserved['state']=='reserved':
+                            (await self.state_call('worker_update',reserved['id'],{'state':'failed','error':str(exc)}))
+                    current=(await self.state_call('get',task['id']));(await self.state_call('update',task['id'],current['revision'],{'state':'blocked','summary':str(exc)},'dispatch-blocked'));await self.notify()
+    async def start(self,task,phase,config,manifest,models):
+        owner=self.owner
+        if phase=='execute' and task.get('adoption'):
+            prepared=await self.adoption_plan(task['adoption']['request'])
+            require(prepared==task['adoption']['plan'],'Adopted checkpoint changed before native dispatch; preserve custody')
+        intake=next((r for r in owner.execution.roles.values() if r['key']==config['pack']+'/intakes/'+config['intakeRole']),None)
+        require(intake is not None,'Original coordinator is missing')
+        await owner.qualify_organization(intake['threadId'])
+        catalog=await owner.read_catalog();native_catalog={'harness':'codex','source':'native-account','connectionGeneration':str(owner.child.pid),'models':[{'model':x['model'],'efforts':[v['reasoningEffort'] for v in x['supportedReasoningEfforts']]} for x in catalog['data']]}
+        if phase=='route':
+            role_id=config['intakeRole'];model_task={'type':'route-request','complexity':'routine','risk':'normal'}
+        elif phase=='execute':role_id=task['route']['role'];model_task=task['route']['task']
+        else:
+            role_id=config['reviewRole'];model_task={**task['route']['task'],'type':'verify-task','complexity':'complex' if task['route']['task']['risk']=='security-critical' or task['channel']=='cicd' and task['route']['task']['type'] in RELEASE_RISK_TYPES else 'standard'}
+        matches=[a for a in manifest['agents'] if a['id']==role_id];require(len(matches)==1,'Role template is ambiguous');agent=matches[0];key=component_key(agent)
+        constraints=task_models.role_constraints(models['constraints'],key);resolution=task_models.resolve(models['configuration'],model_task,'codex',native_catalog,constraints)
+        require(task['channel']!='cicd' or model_task['type'] not in RELEASE_RISK_TYPES or resolution['profile']=='deep','Release-risk tasks require a deep profile')
+        worker=(await self.state_call('reserve',task['id'],phase,key,resolution,config['maxWorkers']));wid=worker['id'];cwd=pathlib.Path(owner.runtime)/'task-workspaces'/wid
+        if config.get('catalogOnly'):
+            source=copy.deepcopy(intake)
+        else:
+            source_rows=read_json(pathlib.Path(config['templateRuntime'])/'execution-policy.json')['roles'];source=next((r for r in source_rows if r['key']==key),None)
+        require(source is not None,'Discipline permission context is missing')
+        cwd.mkdir(parents=True,mode=0o700)
+        from .work_context import ensure as ensure_context
+        context_ref=await asyncio.to_thread(ensure_context,self.store.root,task)
+        if task.get('contextRef')!=context_ref:
+            current=await self.state_call('get',task['id'])
+            task=await self.state_call('update',task['id'],current['revision'],{'contextRef':context_ref,'summary':'Individual cloud task context is verified; native dispatch is next.'},'task-context-bound')
+        from .role_context import materialize as materialize_role
+        role_receipt=await asyncio.to_thread(materialize_role,self.store.root,key,cwd)
+        with (cwd/'AGENTS.md').open('a') as file:
+            file.write('\n\n## Current bounded task assignment\nThis is a new single-use worker, not a reusable role lane. The current task packet overrides older standby/intake routing examples. Do only the assigned phase. Never send peer chat messages, create schedules, take over existing claims or replay UNKNOWN effects. Your output is checkpointed before this native thread is archived. The shared task record retains continuity. Use /opt/homebrew/bin/topolo for supported platform actions when authorized.\n')
+        atomic_json(cwd/'TASK.json',task)
+        from .work_context import materialize
+        await asyncio.to_thread(materialize,self.store.root,task,cwd)
+        if phase in {'execute','review'}:
+            from .linked_task_context import materialize as materialize_linked
+            await materialize_linked(self.store,task,cwd,lambda tid:self.state_call('get',tid))
+        if config.get('catalogOnly') and phase=='review':
+            from .work_artifacts import materialize_result
+            await asyncio.to_thread(materialize_result,self.store.root,task,cwd)
+        spec=copy.deepcopy(source['settings']);spec.update(model=resolution['resolved']['model'],model_reasoning_effort=resolution['resolved']['effort'])
+        (await self.state_call('worker_update',wid,{'state':'creating','cwd':str(cwd),'roleSource':role_receipt}))
+        native=await owner.call_native('thread/start',{'cwd':str(cwd),'model':spec['model'],'approvalPolicy':spec['approval_policy'],'approvalsReviewer':spec['approvals_reviewer'],'sandbox':spec['sandbox_mode'],'config':{'model_reasoning_effort':spec['model_reasoning_effort'],'sandbox_workspace_write':spec['sandbox_workspace_write'],'apps':spec['apps']},'historyMode':'paginated','ephemeral':False,'allowProviderModelFallback':False})
+        tid=native['thread']['id'];(await self.state_call('worker_update',wid,{'nativeId':tid}))
+        self.native_ids.add(tid)
+        row={**copy.deepcopy(source),'key':config['pack']+'/tasks/'+wid,'threadId':tid,'cwd':str(cwd),'sourceRoleKey':key,'sourceRoleNativeId':source['threadId'],'sourcePermissionRoleKey':source['key'],'taskWorkerId':wid,'taskId':task['id'],'taskModelResolution':resolution,'settings':spec,'intakeKey':intake['key']}
+        candidate=ExecutionGate({'format':'topolo-codex-runtime-execution','schemaVersion':1,'roles':[row]});owner.execution.roles[tid]=candidate.roles[tid];owner.execution.set_catalog(catalog);owner.catalog_ready.set();self.persist()
+        await owner.call_native('thread/name/set',{'threadId':tid,'name':phase.capitalize()+' · '+task['objective'][:70]})
+        resumed=await owner.call_native('thread/resume',{'threadId':tid,'allowProviderModelFallback':False})
+        require(tid in owner.execution.verified,'Task model/effort did not receive native ACK')
+        require(resumed.get('model')==spec['model'] and resumed.get('reasoningEffort')==spec['model_reasoning_effort'],'Native task settings acknowledgement differs')
+        resolution['nativeACK']={'boundary':'native thread/resume settings acknowledgement','threadId':tid,'model':resumed['model'],'effort':resumed['reasoningEffort'],'providerFallbackAllowed':False}
+        await self.state_call('worker_update',wid,{'resolution':resolution})
+        owner.execution.roles[tid]['taskModelResolution']=copy.deepcopy(resolution);self.persist()
+        prompt=self.prompt(task,phase,manifest,cwd)
+        current=(await self.state_call('get',task['id']));(await self.state_call('update',task['id'],current['revision'],{'state':{'route':'routing','execute':'executing','review':'reviewing'}[phase],'phase':phase,'workerIds':current['workerIds']+[wid],'summary':{'route':'Coordinator is selecting the discipline and task profile.','execute':'A fresh task worker is carrying out the request.','review':'An independent fresh specialist is checking the result.'}[phase]},'native-resume-verified'))
+        (await self.state_call('worker_update',wid,{'state':'running'}))
+        try:
+            started=await owner.call_native('turn/start',{'threadId':tid,'input':[{'type':'text','text':prompt}]});(await self.state_call('worker_update',wid,{'turnId':started['turn']['id']}))
+        except Exception as exc:
+            (await self.state_call('worker_update',wid,{'state':'unknown','error':str(exc)}));current=(await self.state_call('get',task['id']));(await self.state_call('update',task['id'],current['revision'],{'state':'unknown','summary':'Native task delivery is uncertain; no retry will be sent.'},'delivery-unknown'));raise
+        await self.notify()
+    def prompt(self,task,phase,manifest,cwd):
+        common='Ash authorized this task through the local engineering GUI/native coordinator. Task identity: '+task['id']+'. Shared packet: '+str(cwd/'TASK.json')+'.\nObjective: '+task['objective']+'\n'
+        if phase in {'execute','review'} and (cwd/'context/linked-tasks.json').is_file():
+            common+='Read context/linked-tasks.json and its selected task/checkpoint/context/evidence files before execution or review. These are the explicitly cited existing findings from the same cloud task authority. Do not replace them with the first retained page or repeat a completed review. Missing cited tasks remain explicit; preserve their owners and effects.\n'
+        if task.get('adoption'):
+            common+='Accepted checkpoint continuation: '+json.dumps(task['adoption'])+'\nCurrent effect boundary: '+task['effectBoundary']+'\n'
+        if phase=='route':
+            roles=[{'id':a['id'],'title':a['title']} for a in manifest['agents'] if a['set']!='intakes']
+            return common+'You are the short routing phase only. Do not perform the work, use tools, contact chats or claim existing tasks. Select the suitable discipline from '+json.dumps(roles)+'. Return ONLY JSON with keys role (exact role id), task {type,complexity,risk}, acceptance (clear measurable criteria). Complexity: trivial/routine/standard/complex. Risk: low/normal/security-critical. Trivial is only low-risk format, extract-fields, reference-lookup or status-read work. Ordinary coding is routine or higher. Security-sensitive work is security-critical. Be conservative when uncertain. No markdown.'
+        if phase=='execute' and manifest.get('sourceIndependent'):
+            return common+'Read AGENTS.md, TASK.json and the relevant context. Execute only the assigned acceptance: '+task['route']['acceptance']+'. Preserve current owners, pauses and uncertain effects. Return ONLY JSON {"summary":"actual result and checks","artifacts":["absolute regular file paths inside this worker workspace only"],"references":["canonical Topolo or Git references"]}. At most sixteen artifact files; omit files when a canonical platform/Git reference is appropriate. Never include secrets, whole workspace/history exports or raw deliberation. The adapter verifies and publishes declared files before closing this worker. Do not claim delivery without actual evidence.'
+        if phase=='review' and manifest.get('sourceIndependent'):
+            common+='Read context/worker-result.json and context/result-source.json. They contain the selected cloud checkpoint and verified artifact cache paths; do not depend on any previous machine or worker directory. Evidence paths in your final review must be regular files in this reviewer workspace. '
+        if phase=='execute':return common+'Read AGENTS.md, TASK.json and relevant context. Work within the objective and acceptance: '+task['route']['acceptance']+'. Preserve existing source/task owners and explicit pauses. If an existing owner or missing authority prevents execution, report the exact blocker instead of duplicating work. Do not manage this lane or start other agents. Return a concise result, actual checks performed and exact evidence/artifact paths. A native turn finishing alone is not business completion.'
+        return common+'Independent verification phase. Do not implement changes, contact chats, modify source or perform business effects. Inspect the actual worker result and the referenced evidence against acceptance: '+task['route']['acceptance']+'. Worker result: '+json.dumps(task.get('result',{}))+'. Return ONLY JSON {"verdict":"completed"|"needs_input"|"blocked","summary":"...","evidence":["absolute existing evidence path",...]}. Choose completed only when actual inspected evidence satisfies acceptance; otherwise preserve the gap. No markdown.'
+    def persist(self):
+        owner=self.owner;atomic_json(pathlib.Path(owner.runtime)/'execution-policy.json',{'format':'topolo-codex-runtime-execution','schemaVersion':1,'roles':list(owner.execution.roles.values()),'applied':False,'modelTurnsStarted':False})
+    async def progress(self,params):
+        item=params.get('item',{})
+        if item.get('type')!='agentMessage' or item.get('phase')!='commentary' or not isinstance(item.get('text'),str) or not item['text'].strip():return
+        async with self.lock:
+            worker=next((w for w in await self.state_call('workers') if w.get('nativeId')==params.get('threadId') and w['state']=='running' and w['phase']=='execute'),None)
+            if worker:
+                await self.state_call('progress',worker['id'],item['id'],item['text'].strip()[:1600])
+                await self.notify()
+    def completed(self,tid,turn):
+        self.launch(self.completed_worker(tid,turn))
+    async def completed_worker(self,tid,turn):
+        worker=next((w for w in (await self.state_call('workers',)) if w['nativeId']==tid and w['state']=='running'),None)
+        if worker:self.launch(self.finish(worker['id'],turn))
+    async def read_turn(self,worker,turn):
+        native=await self.owner.call_native('thread/read',{'threadId':worker['nativeId'],'includeTurns':True})
+        matches=[t for t in native['thread'].get('turns',[]) if t['id']==turn['id']]
+        require(len(matches)==1,'Completed native turn receipt is unavailable')
+        return matches[0]
+    async def archive_worker(self,worker):
+        tid=worker['nativeId']
+        await self.owner.call_native('thread/archive',{'threadId':tid})
+        archived=await self.owner.call_native('thread/read',{'threadId':tid,'includeTurns':False})
+        require(archived['thread']['id']==tid,'Archive readback identity changed')
+        listing=await self.owner.call_native('thread/list',{'limit':100,'archived':False})
+        require(tid not in {r['id'] for r in listing['data']},'Worker remains in native active list')
+        return {}
+    async def finish(self,wid,turn):
+        async with self.lock:
+            worker=(await self.state_call('worker',wid))
+            if worker['state']!='running':
+                return
+            owner=self.owner;task=(await self.state_call('get',worker['taskId']));tid=worker['nativeId']
+            try:
+                actual=await self.read_turn(worker,turn)
+                text_value='\n'.join(i.get('text','') for i in actual.get('items',[]) if i.get('type')=='agentMessage' and i.get('phase')!='commentary')
+                if not text_value:text_value='\n'.join(i.get('text','') for i in actual.get('items',[]) if i.get('type')=='agentMessage')
+                portable=read_json(self.store.root/'config.json',{}).get('format')=='topolo-task-dispatch-v2';normalized=None;portable_payload=None
+                checkpoint=self.store.root/'checkpoints'/task['id']/(wid+'.json');checkpoint.parent.mkdir(parents=True,exist_ok=True)
+                if portable:
+                    from .work_artifacts import checkpoint as cloud_checkpoint
+                    proof,portable_payload,normalized=await asyncio.to_thread(cloud_checkpoint,self.store.root,task,worker,actual)
+                    atomic_json(checkpoint,portable_payload)
+                else:
+                    atomic_json(checkpoint,{'taskId':task['id'],'worker':worker,'nativeTurn':actual,'resolution':worker['resolution']});proof={'path':str(checkpoint),'sha256':hashlib.sha256(checkpoint.read_bytes()).hexdigest()}
+                (await self.state_call('worker_update',wid,{'state':'archiving','checkpoint':proof}))
+                # Persist the result before archiving; a failed archive retains
+                # its exact native identity and is never replaced by a new one.
+                current=(await self.state_call('get',task['id']));task=(await self.state_call('update',task['id'],current['revision'],{'checkpoints':current['checkpoints']+[proof]},'checkpoint-saved'))
+                retirement=await self.archive_worker(worker)
+                (await self.state_call('worker_update',wid,{'state':'archived','nativeArchived':True,**retirement}));owner.execution.roles.pop(tid,None);owner.execution.verified.discard(tid);self.persist()
+                if actual['status']!='completed':
+                    raise PackError('Native worker '+actual['status']+'; checkpoint retained')
+                if portable and portable_payload['outputError']:
+                    raise PackError(portable_payload['outputError'])
+                if worker['phase']=='route':
+                    _,manifest,_=self.config(task['channel']);route=parse_route(text_value,{a['id'] for a in manifest['agents'] if a['set']!='intakes'});task=(await self.state_call('update',task['id'],task['revision'],{'state':'executing','phase':'execute','route':route,'summary':'Routed to '+route['role']+'; a new worker will be created.'},'coordinator-released'))
+                elif worker['phase']=='execute':
+                    result={**normalized,'checkpoint':proof,'workerId':worker['id']} if portable else {'summary':text_value,'checkpoint':proof}
+                    task=(await self.state_call('update',task['id'],task['revision'],{'state':'reviewing','phase':'review','result':result,'summary':'Worker checkpoint saved and lane archived; independent verification pending.'},'worker-released'))
+                else:
+                    raw=text_value.strip()
+                    if raw.startswith('```'):raw=raw.split('\n',1)[1].rsplit('```',1)[0]
+                    review=normalized if portable else json.loads(raw);require(set(review)=={'verdict','summary','evidence'} and review['verdict'] in {'completed','needs_input','blocked'} and isinstance(review['evidence'],list),'Invalid independent verification receipt')
+                    evidence=[]
+                    for value in ([] if portable else review['evidence']):
+                        p=pathlib.Path(value);require(p.is_absolute() and p.is_file() and not p.is_symlink(),'Verification evidence is missing');evidence.append({'path':str(p),'sha256':hashlib.sha256(p.read_bytes()).hexdigest()})
+                    if portable:evidence=review['evidence']
+                    if review['verdict']=='completed':require(bool(evidence),'Completion requires inspected evidence files')
+                    task=(await self.state_call('update',task['id'],task['revision'],{'state':review['verdict'],'summary':review['summary'],'verification':{**review,'evidence':evidence,'nativeCheckpoint':proof}},'verification-recorded'))
+            except Exception as exc:
+                current=(await self.state_call('get',task['id']));(await self.state_call('update',task['id'],current['revision'],{'state':'blocked','summary':str(exc)},'completion-blocked'))
+            await self.notify()
+        self.launch(self.pump())

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

@@ -0,0 +1,151 @@
+"""Bounded read-only native task following; no dispatcher, retry or model turn."""
+import json
+import os
+import socket
+import stat
+import time
+import uuid
+
+from .storage import PackError, canonical, read_json
+from .work import TERMINAL, require
+
+LIMIT = 1024 * 1024
+
+
+def _remaining(deadline):
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        raise TimeoutError('Task wait deadline reached')
+    return remaining
+
+
+def _record(lib):
+    path = lib.root / 'live-bridge.json'
+    info = path.lstat()
+    require(stat.S_ISREG(info.st_mode) and info.st_uid == os.getuid()
+            and not info.st_mode & 0o077 and not path.is_symlink(),
+            'Task wait requires the privately owned native connection')
+    value = read_json(path)
+    require(isinstance(value, dict) and isinstance(value.get('token'), str) and value['token']
+            and isinstance(value.get('socket'), str) and os.path.isabs(value['socket']),
+            'Task wait native connection is unavailable')
+    info = os.lstat(value['socket'])
+    require(stat.S_ISSOCK(info.st_mode) and info.st_uid == os.getuid()
+            and not info.st_mode & 0o077, 'Task wait native socket ownership differs')
+    return value
+
+
+class _Connection:
+    def __init__(self, lib, record, operation, params, deadline):
+        require(_record(lib) == record, 'Native owner changed during task wait; reconnect explicitly')
+        self.socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.buffer = b''
+        try:
+            self.socket.settimeout(_remaining(deadline))
+            self.socket.connect(record['socket'])
+            self.socket.settimeout(_remaining(deadline))
+            self.socket.sendall(canonical({'token': record['token'], 'operation': operation, 'params': params}) + b'\n')
+        except BaseException:
+            self.socket.close()
+            raise
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_args):
+        self.socket.close()
+
+    def read(self, deadline):
+        while b'\n' not in self.buffer:
+            require(len(self.buffer) <= LIMIT, 'Task wait response exceeds its boundary')
+            self.socket.settimeout(_remaining(deadline))
+            chunk = self.socket.recv(min(65536, LIMIT + 1 - len(self.buffer)))
+            require(chunk, 'Native task connection closed before its reply')
+            self.buffer += chunk
+        line, self.buffer = self.buffer.split(b'\n', 1)
+        require(len(line) <= LIMIT, 'Task wait response exceeds its boundary')
+        value = json.loads(line)
+        require(isinstance(value, dict), 'Native task reply is not an object')
+        require('error' not in value, 'Native task read refused: ' + str(value.get('error')))
+        return value
+
+
+def _snapshot(lib, record, task_id, deadline):
+    with _Connection(lib, record, 'work-read', {'taskId': task_id}, deadline) as connection:
+        value = connection.read(deadline)
+    require(set(value) == {'task', 'events'} and isinstance(value['task'], dict)
+            and value['task'].get('id') == task_id and isinstance(value['events'], list),
+            'Task wait readback identity differs')
+    require(type(value['task'].get('revision')) is int and value['task']['revision'] >= 1,
+            'Task wait revision is invalid')
+    events = []
+    for event in value['events']:
+        require(isinstance(event, dict), 'Task wait event is invalid')
+        if event.get('taskId') != task_id:
+            continue
+        require(type(event.get('sequence')) is int and event['sequence'] > 0,
+                'Task wait event sequence is invalid')
+        events.append(event)
+    require(len({event['sequence'] for event in events}) == len(events), 'Task event sequence repeats')
+    return {'task': value['task'], 'events': sorted(events, key=lambda event: event['sequence'])}
+
+
+def _result(task_id, snapshot, revision, sequence, timed_out):
+    if snapshot is None:
+        return {'taskId': task_id, 'task': None, 'events': [],
+                'cursor': {'revision': revision, 'sequence': sequence},
+                'changed': False, 'terminal': False, 'timedOut': True,
+                'snapshotAvailable': False, 'deliveryId': None}
+    task, events = snapshot['task'], snapshot['events']
+    current = max((event['sequence'] for event in events), default=0)
+    require(revision <= task['revision'] and sequence <= current,
+            'Task wait cursor is ahead of the canonical task')
+    return {'taskId': task_id, 'task': task,
+            'events': [event for event in events if event['sequence'] > sequence],
+            'cursor': {'revision': task['revision'], 'sequence': current},
+            'changed': task['revision'] > revision or current > sequence,
+            'terminal': task['state'] in TERMINAL, 'timedOut': timed_out,
+            'snapshotAvailable': True,
+            'deliveryId': task_id + ':' + str(task['revision']) + ':' + str(current)}
+
+
+def wait(lib, value):
+    """Follow one existing task within the caller's real native tool turn.
+
+    Repeat only on an explicit subsequent tool call with the returned cursor.
+    A timeout, native cancellation or disconnect never cancels/adopts work.
+    """
+    require(isinstance(value, dict) and set(value) == {'taskId', 'afterRevision', 'afterSequence', 'timeoutSeconds'},
+            'Exact bounded task wait request required')
+    task_id = value['taskId']
+    try:
+        valid_id = isinstance(task_id, str) and str(uuid.UUID(task_id)) == task_id
+    except ValueError:
+        valid_id = False
+    require(valid_id, 'Task wait requires the exact canonical task UUID')
+    revision, sequence, seconds = value['afterRevision'], value['afterSequence'], value['timeoutSeconds']
+    require(type(revision) is int and revision >= 0 and type(sequence) is int and sequence >= 0
+            and type(seconds) is int and 1 <= seconds <= 30, 'Task wait cursor or deadline is invalid')
+    deadline = time.monotonic() + seconds
+    record = _record(lib)
+    snapshot = None
+    try:
+        snapshot = _snapshot(lib, record, task_id, deadline)
+        result = _result(task_id, snapshot, revision, sequence, False)
+        if result['changed'] or result['terminal']:
+            return result
+        with _Connection(lib, record, 'work-watch', {}, deadline) as connection:
+            require(connection.read(deadline) == {'connected': True}, 'Native task watch was not acknowledged')
+            # Subscribe first, then re-read. A completion between the first read
+            # and watcher registration cannot disappear into a notification gap.
+            snapshot = _snapshot(lib, record, task_id, deadline)
+            while True:
+                result = _result(task_id, snapshot, revision, sequence, False)
+                if result['changed'] or result['terminal']:
+                    return result
+                event = connection.read(deadline)
+                require(set(event) == {'sequence'} and type(event['sequence']) is int and event['sequence'] >= 0,
+                        'Native task notification is invalid')
+                snapshot = _snapshot(lib, record, task_id, deadline)
+    except TimeoutError:
+        return _result(task_id, snapshot, revision, sequence, True)

package/agent-packs/templates/topolo-coordinators/AGENTS.md

@@ -0,0 +1,7 @@
+# Topolo task execution rules
+
+Load only the current specialization from Topolo Agent and the relevant canonical task and Docs/Bytes packets. This machine's conversation history is not task context. An empty workspace grants no permission to repeat, adopt or resume existing work.
+
+Preserve task, claim, owner, intent and checkpoint identities. Respect explicit holds and uncertain effects. Use supported credential-scoped Topolo actions and the governed release controller. Keep credentials out of ordinary context and evidence. Record meaningful outcomes and evidence in the existing task; distinguish reported progress, native settings acknowledgement, execution, independent verification and deployment.
+
+The three human front doors acknowledge broker receipts and remain available. Their local specialization charters define that boundary. Temporary task workers execute only their assigned phase and are archived after checkpointing; they do not become reusable lanes. Never load a whole role export, infer completion from a finished model turn, or create schedules or peer-message loops.

package/agent-packs/templates/topolo-coordinators/agents/intakes/cicd/AGENTS.md

@@ -0,0 +1,6 @@
+# Topolo CI/CD
+
+Acknowledge the queued request and remain available. If the adapter has not recorded a task, report that dispatch is unavailable; do not take over the implementation. Cloud specialization and task references must be qualified before model work.
+
+## Release-controller operating context
+The controller is the restricted internal service in Topolo-io/TopoloReleaseController, separate from the public application registry and Deploy Orchestrator. Read context/release-controller.md before routing or diagnosis: it is the selected immutable operating runbook, not task history. Current controller access, fleet endpoints and exact intent/job checkpoints belong in the selected task context. Dispatch immediate read-only diagnostics under the existing request; do not ask the human to re-explain the controller or approve an ordinary read. Use the existing broker, preserve owners and record precise missing observer access rather than guessing hosts or creating duplicate work. The submission gateway and native authority observer expose different read operations; follow the bound runbook. Mutations retain their existing release, review and effect gates.

package/agent-packs/templates/topolo-coordinators/agents/intakes/cicd/config.json

@@ -0,0 +1,4 @@
+{
+  "model": "gpt-6.1-sol",
+  "reasoningEffort": "low"
+}

package/agent-packs/templates/topolo-coordinators/agents/intakes/engineering/AGENTS.md

@@ -0,0 +1,3 @@
+# Topolo Engineering
+
+Acknowledge the queued request and remain available. If the adapter has not recorded a task, report that dispatch is unavailable; do not take over the implementation. Cloud specialization and task references must be qualified before model work.

package/agent-packs/templates/topolo-coordinators/agents/intakes/engineering/config.json

@@ -0,0 +1,4 @@
+{
+  "model": "gpt-6.1-sol",
+  "reasoningEffort": "low"
+}