@topolo/cli 0.13.17 → 0.13.21

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

@@ -0,0 +1,126 @@
+"""Docs-selected task state; local SQLite exists only inside a disposable operation.
+
+Requires the published conditional-version and current-only-read contracts.
+No network failure falls back to a local ledger, and startup never adopts workers.
+"""
+import copy,hashlib,json,pathlib,sqlite3,tempfile,uuid
+from .storage import PackError,read_json,canonical
+from .work import Store,require
+
+TABLES={'tasks':('id','input_hash','body'),'workers':('id','task_id','body'),'events':('sequence','task_id','body'),'responses':('id','input_hash','task_id')}
+READS={'get','list','worker','workers','events','retained','retained_page'}
+WRITES={'submit','update','reserve','worker_update','respond','re_review','progress','adopt_ready','adopt_retained'}
+
+class CloudStore:
+    cloud=True
+    def __init__(self,root,client=None,inventory=None):
+        self.root=pathlib.Path(root)/'work'
+        self.binding=read_json(self.root/'cloud.json')
+        renewal=self.root/'coordinator-renewal.json'
+        if renewal.exists() or renewal.is_symlink():
+            from .coordinator_refresh import verified_local
+            from types import SimpleNamespace
+            verified_local(SimpleNamespace(root=self.root.parent))
+        if (self.root/'cloud-migration.json').exists():
+            from .cloud_migrate import verified
+            verified(self.root.parent)
+        attachment_path=self.root/'cloud-attach.json'
+        if attachment_path.exists() or attachment_path.is_symlink():
+            require(not attachment_path.is_symlink(),'Cloud attachment journal cannot be a symlink')
+            attachment=read_json(attachment_path)
+            require(isinstance(attachment,dict) and attachment.get('format')=='topolo-cloud-attach-v1' and attachment.get('state')=='verified' and attachment.get('binding')==self.binding,'Cloud attachment is incomplete; reconcile before execution')
+        require(set(self.binding)=={'format','organizationId','workspaceId','documentId','datasetId','installationId'},'Invalid cloud work binding')
+        require(self.binding['format']=='topolo-cloud-work-binding-v1' and self.binding['organizationId']=='org_topolo_platform','Cloud work organization differs')
+        if client is None:
+            from .topolo import Client
+            client=Client('production','org:org_topolo_platform')
+        require(all(isinstance(self.binding[k],str) and 1<=len(self.binding[k])<=240 for k in ['workspaceId','documentId','datasetId','installationId']),'Cloud work binding identity is missing')
+        self.client=client;self.inventory=inventory
+    def recover(self):
+        # Another machine's running or UNKNOWN worker retains its owner. A fresh
+        # process is not a lease, checkpoint adoption, or execution authorization.
+        return None
+    def load(self):
+        r=self.client.action('app_topolo_docs.documents.get',{'documentId':self.binding['documentId'],'includeHistory':False},self.binding['workspaceId'])
+        doc=r['document'];rows=[v for v in r['versions'] if v['id']==doc['currentVersionId']]
+        require(doc['id']==self.binding['documentId'] and doc['workspaceId']==self.binding['workspaceId'] and doc['organizationId']==self.binding['organizationId'] and len(rows)==1,'Cloud task-state readback differs')
+        value=json.loads(rows[0]['bodyMarkdown'])
+        require(value['format']=='topolo-cloud-work-state-v1' and value['datasetId']==self.binding['datasetId'] and type(value['generation']) is int and set(value['tables'])==set(TABLES),'Cloud work state is unqualified')
+        require(value.get('activated') is True,'Cloud task-state migration has not been activated; no execution authority')
+        return doc['currentVersionId'],value
+    def retained_rows(self,ref):
+        if self.inventory is not None:
+            require(hashlib.sha256(canonical(self.inventory)).hexdigest()==ref['sha256'],'Retained inventory cache differs from cloud')
+            return self.inventory
+        from .topolo import read_artifact
+        with tempfile.TemporaryDirectory(prefix='topolo-work-inventory-') as tmp:
+            path=pathlib.Path(tmp)/'inventory.json'
+            read_artifact(self.client,{'input':{'bytesScope':ref['scope'],'bytesWorkspaceId':ref['workspaceId']}},ref['key'],ref,path)
+            value=json.loads(path.read_text())
+        require(hashlib.sha256(canonical(value)).hexdigest()==ref['sha256'],'Cloud retained inventory digest differs')
+        self.inventory=value;return value
+    def snapshot(self):
+        _,value=self.load()
+        return {'tasks':[json.loads(r[2]) for r in reversed(value['tables']['tasks'])],
+                'workers':[json.loads(r[2]) for r in value['tables']['workers']],
+                'events':[{'sequence':r[0],**json.loads(r[2])} for r in value['tables']['events']],
+                'retainedCount':value['inventory']['count'],'authority':'topolo-docs','generation':value['generation']}
+    def adopt_ready(self,tid,revision):
+        return self.invoke('adopt_ready',(tid,revision,self.binding['installationId']),{})
+    def __getattr__(self,name):
+        if name not in READS|WRITES:
+            raise AttributeError(name)
+        return lambda *args,**kwargs:self.invoke(name,args,kwargs)
+    def invoke(self,name,args,kwargs):
+        version,state=self.load()
+        with tempfile.TemporaryDirectory(prefix='topolo-work-operation-') as tmp:
+            store=Store(tmp)
+            with store.db() as db:
+                for table,columns in TABLES.items():
+                    db.executemany('INSERT INTO '+table+' VALUES ('+','.join('?' for _ in columns)+')',state['tables'][table])
+                if name in {'retained','retained_page','adopt_retained'}:
+                    db.executemany('INSERT INTO retained VALUES (?,?)',[(row[0],row[1]) for row in self.retained_rows(state['inventory'])])
+            if name in WRITES and name not in {'submit','adopt_ready','adopt_retained'}:
+                task_id=store.worker(args[0])['taskId'] if name in {'worker_update','progress'} else args[0]['taskId'] if name in {'respond','re_review'} else args[0]
+                if name!='respond':require(store.get(task_id).get('ownerInstallationId')==self.binding['installationId'],'Task belongs to another installation; explicit checkpoint adoption is required')
+            if name=='adopt_retained':
+                parent=store.get(args[0]['continuationOwnerTaskId'])
+                if parent.get('ownerInstallationId')!=self.binding['installationId']:
+                    from .work_adoption import verify_parent
+                    workers=[w for w in store.workers() if w['taskId']==parent['id']]
+                    proof=verify_parent(parent,workers,args[0],self.root,self.client,self.binding['installationId'])
+                    kwargs={**kwargs,'parent_proof':proof}
+            result=getattr(store,name)(*args,**kwargs)
+            if name in READS:
+                return result
+            if name in {'submit','adopt_retained'} and result[1]:
+                task=result[0];task['ownerInstallationId']=self.binding['installationId'];task['resumeAfterCheckpoint']=True
+                with store.db() as db:
+                    db.execute('UPDATE tasks SET body=? WHERE id=?',(json.dumps(task),task['id']))
+            if name=='respond' and result[1] and result[0]['state']=='queued':
+                task=result[0];task['ownerInstallationId']=self.binding['installationId'];task['resumeAfterCheckpoint']=True
+                with store.db() as db:
+                    db.execute('UPDATE tasks SET body=? WHERE id=?',(json.dumps(task),task['id']))
+            with store.db() as db:
+                tables={table:db.execute('SELECT * FROM '+table+' ORDER BY '+('sequence' if table=='events' else 'rowid')).fetchall() for table in TABLES}
+            if tables=={k:[tuple(row) for row in rows] for k,rows in state['tables'].items()}:
+                return result
+            operation=str(uuid.uuid4());next_state={**copy.deepcopy(state),'tables':tables,'generation':state['generation']+1,'operation':{'id':operation,'method':name,'installationId':self.binding['installationId']}}
+            body=canonical(next_state).decode();require(len(body)<=900000,'Active cloud ledger requires archival before accepting more state; no local fallback')
+            try:
+                self.client.action('app_topolo_docs.documents.versions.create',{'documentId':self.binding['documentId'],'bodyMarkdown':body,'expectedCurrentVersionId':version},self.binding['workspaceId'],write=True)
+            except Exception as exc:
+                # Reconcile a lost successful ACK once. A competing generation
+                # or unavailable read is never permission to repeat the write.
+                try:_,actual=self.load()
+                except Exception:
+                    raise PackError('Cloud task write is uncertain; no local commit or external replay was authorized') from exc
+                if actual.get('operation',{}).get('id')!=operation:
+                    raise PackError('Cloud state changed or write was refused; reread and reconcile without replay') from exc
+            return result
+
+def open_store(root):
+    config=read_json(pathlib.Path(root)/'work/config.json',{})
+    cloud=(pathlib.Path(root)/'work/cloud.json').is_file()
+    require(((config.get('authority')=='topolo-docs' or config.get('requireCloudAuthority') is True)==cloud),'Cloud authority binding is incomplete; no local fallback')
+    return CloudStore(root) if cloud else Store(root)

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

@@ -0,0 +1,27 @@
+"""Durable native coordinator observations, separate from task completion."""
+import time,fcntl
+from pathlib import Path
+from .storage import read_json,atomic_json
+
+def record(root,status):
+    roster=read_json(Path(status['runtime'])/'agents.json',{}).get('agents',[])
+    active=set(status['activeTurns'])
+    work=Path(root)/'work';work.mkdir(exist_ok=True)
+    with (work/'coordinator-observations.lock').open('a') as lock:
+        fcntl.flock(lock,fcntl.LOCK_EX)
+        path=work/'coordinator-observations.json'
+        record=read_json(path,{'states':{},'events':[]})
+        if read_json(work/'config.json',{}).get('frontdoorDispatch') is True:
+            return record['events']
+        for role in roster:
+            if role.get('set')!='intakes':continue
+            tid=role['threadId'];state='active' if tid in active else 'idle'
+            previous=record['states'].get(tid)
+            # Do not invent past starts or completion from the first idle observation.
+            if previous!=state and (state=='active' or previous is not None):
+                record['events'].append({'id':'native-observation:'+tid+':'+str(len(record['events'])+1),
+                    'at':time.time(),'threadId':tid,'owner':role.get('title',role['id']),'state':state,
+                    'summary':('Native coordinator execution is active outside the task broker. Existing work has not been dispatched again; task progress and outcome remain unverified.' if state=='active' else 'Native coordinator is now idle. This observation does not verify task completion or deployment.')})
+            record['states'][tid]=state
+        atomic_json(path,record)
+        return record['events']

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

@@ -0,0 +1,91 @@
+"""Bounded conversational context and typed coordinator broker-tool boundary."""
+import copy,json,pathlib,shlex,sys,uuid,re
+from .storage import canonical,atomic_json,read_json,PackError
+from .work import require
+
+CONTRACT='''Stay in the human-facing conversation. Answer questions, clarify scope, inspect current task status and explain results directly using canonical cloud evidence. A status question, follow-up or clarification is not a new assignment and must not create a task. For an actual new assignment, first reconcile the selected existing tasks; continue the original task when appropriate instead of duplicating it. Submit a new bounded assignment only through the installed task broker, using the supplied native-message dispatch identity exactly once. Delegate implementation, infrastructure, operational effects and bounded diagnostic execution to task-based specialists; do not perform them in this coordinator. Preserve task IDs, owners, holds, acceptance and uncertain effects. Use the existing broker read/wait tools to follow progress and inspect the final result, then explain the actual outcome here. A queue receipt is not completion and a GUI link is not a substitute for answering the human. Native model, effort, permissions and specialist-selection gates remain in force. Never invent a completed result, resend uncertain work, resume archived workers, or use another agent mechanism outside the task broker.'''
+
+OPERATIONS={'list','read','retained','submit','respond','re-review','wait'}
+
+def dispatch_id(thread,message):
+    require(isinstance(message,str) and 1<=len(message)<=200,'Native human message identity is missing; no new assignment can be dispatched')
+    return str(uuid.uuid5(uuid.NAMESPACE_URL,'topolo-frontdoor:'+thread+':'+message))
+
+def payload_valid(value,operation,identity,channel):
+    require(isinstance(value,dict),'Typed broker request object required')
+    if operation=='read':require(set(value)=={'taskId'} and isinstance(value['taskId'],str) and 1<=len(value['taskId'])<=200,'Exact existing task identity required')
+    elif operation=='wait':require(set(value)=={'taskId','afterRevision','afterSequence','timeoutSeconds'} and isinstance(value['taskId'],str) and type(value['afterRevision']) is int and value['afterRevision']>=0 and type(value['afterSequence']) is int and value['afterSequence']>=0 and type(value['timeoutSeconds']) is int and 1<=value['timeoutSeconds']<=30,'Bounded existing task wait required')
+    elif operation=='retained':require(set(value)<={'cursor','limit'} and type(value.get('cursor',0)) is int and value.get('cursor',0)>=0 and type(value.get('limit',50)) is int and 1<=value.get('limit',50)<=50,'Bounded retained query required')
+    elif operation in {'submit','respond','re-review'}:
+        expected={'submit':{'requestId','objective','channel','canonicalClaimId'},'respond':{'requestId','taskId','revision','intent','note'},'re-review':{'requestId','taskId','revision','reviewWorkerId','reviewCheckpoint','note'}}[operation]
+        require(set(value)==expected and value['requestId']==identity,'Use this exact native-message dispatch identity; no invented request')
+        if operation=='submit':require(value['channel']==channel and isinstance(value['objective'],str) and 1<=len(value['objective'])<=16000 and value['canonicalClaimId'] is None,'Bounded new assignment required; existing claims need their supported adoption authority')
+        else:require(isinstance(value['taskId'],str) and type(value['revision']) is int and value['revision']>0 and isinstance(value['note'],str) and 1<=len(value['note'])<=8000,'Existing task revision and human response required')
+    else:require(operation=='list' and value=={},'Unsupported coordinator broker operation')
+    return value
+
+def context(root,channel,thread,message,snapshot,harness):
+    require(harness in {'codex','claude'} and channel in {'engineering','operations','cicd'},'Qualified coordinator channel/harness required')
+    require(snapshot.get('authority')=='topolo-docs' and isinstance(snapshot.get('tasks'),list) and isinstance(snapshot.get('workers'),list),'Canonical cloud work snapshot required')
+    rows=[t for t in snapshot['tasks'] if t.get('channel')==channel][:20]
+    selected=[]
+    for task in rows:
+        workers=[w for w in snapshot['workers'] if w['taskId']==task['id']]
+        selected.append({k:task.get(k) for k in ['id','revision','state','phase','attempt','ownerInstallationId']}|{'objective':str(task.get('objective',''))[:500],'summary':str(task.get('summary',''))[:800],'workers':[{'phase':w['phase'],'state':w['state'],'nativeArchived':w.get('nativeArchived') is True} for w in workers[-8:]]})
+    adapter=pathlib.Path(__file__).resolve().parents[2]/'topolo-agent-pack'
+    require(adapter.is_file() and not adapter.is_symlink(),'Qualified bundled broker command is unavailable')
+    command=[sys.executable,str(adapter),'--store',str(pathlib.Path(root).resolve()),'--harness',harness,'work']
+    return {'format':'topolo-coordinator-conversation-v1','contract':CONTRACT,'channel':channel,'dispatchRequestId':dispatch_id(thread,message),'commands':{'list':shlex.join(command+['list']),'requestPrefix':shlex.join(command),'requestPath':'context/coordinator-request.json','wait':'Write {taskId, afterRevision, afterSequence, timeoutSeconds: 30} for an existing task, then wait --input <absolute request path>. This event-driven read returns changed or terminal state and results; do not create another task or poll in a background loop.','read':"Write {taskId} to the request file, then run the requestPrefix plus read --input <absolute request path>.",'dispatch':"Only for an actual assignment: write {requestId: dispatchRequestId, objective: exact bounded assignment, channel, canonicalClaimId: null}, then submit --input <absolute request path>. For existing work use read/respond instead of creating a duplicate.",'allowedOperations':sorted(OPERATIONS),'respond':"For a human-authorized continuation/change/hold of existing work, first read that task and use its returned latest task.revision. Write exactly {requestId: dispatchRequestId, taskId, revision: latest task.revision, intent: 'continue' | 'request_changes' | 'hold', note: exact human instruction}, then respond --input <absolute request path>. This updates the same task; never submit a replacement or reuse a stale revision. A refusal or uncertain response is not permission to replay.",'re-review':"Only for an explicitly requested fresh review of the same failed review, first read the task. Write exactly {requestId: dispatchRequestId, taskId, revision: latest task.revision, reviewWorkerId: rejected reviewer worker ID, reviewCheckpoint: rejected review checkpoint sha256, note: exact review correction}, then re-review --input <absolute request path>. Preserve the original route/execution, attempt, rejection and worker history; do not rerun execution.",'requestTemplates':{'respond':{'requestId':dispatch_id(thread,message),'taskId':'<existing task ID from read>','revision':'<latest task.revision integer from read>','intent':'continue','note':'<exact human continuation/change/hold instruction>'},'re-review':{'requestId':dispatch_id(thread,message),'taskId':'<existing task ID from read>','revision':'<latest task.revision integer from read>','reviewWorkerId':'<rejected reviewer worker ID from read>','reviewCheckpoint':'<rejected review checkpoint sha256 from read>','note':'<exact human review correction>'}}},'tasks':selected,'matchingTasks':sum(t.get('channel')==channel for t in snapshot['tasks']),'retainedCount':snapshot.get('retainedCount'),'evidenceBoundary':'Canonical recorded state only; queued is not running, retainedCount counts historical retained claims rather than active workloads, a model turn ending is not delivery, and no work is submitted by this context read.'}
+
+def augment(value,selected):
+    require(isinstance(value.get('params',{}).get('input'),list) and bool(value['params']['input']),'Native coordinator input is missing')
+    result=copy.deepcopy(value);result['params']['input'].append({'type':'text','text':'Topolo coordinator context (platform data; the original human message above is unchanged):\n'+canonical(selected).decode()});return result
+
+def prepare(root,role,event,snapshot,harness='claude'):
+    selected=context(root,role['channel'],'claude:'+event['session_id'],event['prompt_id'],snapshot,harness)
+    cwd=pathlib.Path(role['cwd']);require(cwd.is_absolute() and cwd.is_dir() and cwd.resolve()==cwd,'Owned coordinator workspace required')
+    directory=cwd/'context';require(not directory.is_symlink(),'Coordinator context cannot be a symlink');directory.mkdir(mode=0o700,exist_ok=True)
+    atomic_json(directory/'coordinator-session.json',{'format':'topolo-coordinator-session-v1','sessionId':event['session_id'],'dispatchRequestId':selected['dispatchRequestId'],'channel':role['channel'],'commandPrefix':shlex.split(selected['commands']['requestPrefix'])})
+    return selected
+
+def tool_allowed(root,role,event):
+    """Allow reads and exact broker transport, never direct engineering effects."""
+    cwd=pathlib.Path(role['cwd']);session=cwd/'context/coordinator-session.json'
+    require(cwd.is_absolute() and cwd.is_dir() and cwd.resolve()==cwd and not (cwd/'context').is_symlink() and not session.is_symlink(),'Owned coordinator context required')
+    record=read_json(session,{})
+    require(record.get('format')=='topolo-coordinator-session-v1' and record.get('sessionId')==event['session_id'] and record.get('channel')==role['channel'],'Current native prompt context is missing')
+    expected=[sys.executable,str(pathlib.Path(__file__).resolve().parents[2]/'topolo-agent-pack'),'--store',str(pathlib.Path(root).resolve()),'--harness','claude','work']
+    require(record.get('commandPrefix')==expected,'Current bundled broker command changed')
+    require(event.get('permission_mode')=='bypassPermissions','Coordinator native permissions differ')
+    request_path=cwd/'context/coordinator-request.json';tool=event.get('tool_name');value=event.get('tool_input') or {}
+    if tool=='Read':
+        path=pathlib.Path(value.get('file_path',''));return path.is_absolute() and path.resolve()==path and path.is_relative_to(cwd) and path.is_file()
+    if tool=='Write':
+        require(value.get('file_path')==str(request_path) and not request_path.is_symlink(),'Only the typed coordinator request file can be written')
+        body=value.get('content');require(isinstance(body,str) and len(body.encode())<=20000,'Bounded broker request required');payload=json.loads(body)
+        for operation in OPERATIONS:
+            try:payload_valid(payload,operation,record['dispatchRequestId'],role['channel']);return True
+            except PackError:pass
+        return False
+    if tool=='Bash':
+        require(set(value)<={'command','description','timeout','run_in_background'} and value.get('run_in_background') is not True,'Foreground typed broker command required')
+        args=shlex.split(value.get('command',''));prefix=record['commandPrefix']
+        require(args[:len(prefix)]==prefix,'Only the installed typed broker transport is allowed')
+        suffix=args[len(prefix):];require(bool(suffix) and suffix[0] in OPERATIONS,'Unsupported broker operation')
+        if suffix==['list']:return True
+        require(len(suffix)==3 and suffix[1]=='--input' and suffix[2]==str(request_path) and request_path.is_file() and request_path.resolve()==request_path,'Exact owned broker request path required')
+        require(request_path.stat().st_size<=20000,'Bounded broker request required')
+        payload_valid(read_json(request_path),suffix[0],record['dispatchRequestId'],role['channel']);return True
+    return False
+
+
+def charter(logical,previous):
+    """Authored canonical Agent update; installation still requires governed CAS."""
+    summaries={'intakes/engineering':'Coordinate engineering conversation and existing tasks; delegate implementation and bounded diagnostics through the task broker.',
+               'intakes/operator-01':'Coordinate operational conversation and existing tasks; delegate bounded business operations to the owning specialist through the task broker.',
+               'intakes/cicd':'Coordinate CI/CD conversation, existing releases and decisions. Delegate bounded diagnostics, engineering and release effects through the task broker; never SSH, edit source or deploy directly.'}
+    require(logical in summaries and isinstance(previous,str) and previous.count('## Specialization')==1,'Existing canonical coordinator definition required')
+    body=re.sub(r'## Specialization\n.*?(?=\n## |\Z)','## Specialization\n'+summaries[logical]+'\n\n'+CONTRACT+'\n',previous,flags=re.S)
+    body=body.replace('Capture exact request, attachments and desired outcome in the existing task. Check its request identity before creating anything. Select one discipline and task complexity/risk; dispatch promptly, then return idle. A separate task worker owns execution and progress. Surface decisions in the GUI; do not occupy this coordinator with implementation.', 'Read the selected cloud task context first. Answer status, follow-ups and clarification in this conversation. For actual assignments use the supplied deterministic request identity and the existing broker; reuse the original task for continuation. Follow its real result through read/wait before reporting the outcome. Specialists own implementation and operational effects.')
+    body=body.replace('Execute only the bounded assignment, then return its checkpoint and stop.', 'Report verified task outcomes and next actions in this conversation; specialists checkpoint and stop after their bounded work.')
+    return body

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

@@ -0,0 +1,116 @@
+"""Reviewed instruction-only renewal; task state and native identities never change."""
+import copy,fcntl,hashlib,json,os,pathlib
+from contextlib import ExitStack
+from .storage import read_json,atomic_json,PackError
+from .work import require
+from .cloud_work import CloudStore
+from .cloud_cutover import digest
+
+FORMAT='topolo-coordinator-renewal-v1'
+LOGICAL={'intakes/engineering','intakes/operator-01','intakes/cicd'}
+
+def local(lib):
+    names=['config.json','role-bindings.json','cloud.json','cutover.json','cloud-migration.json','role-catalog.json']
+    from .closed_ledger_fence import owned
+    paths=[lib.root/'work'/name for name in names if (lib.root/'work'/name).exists() or (lib.root/'work'/name).is_symlink()]
+    for path in paths:owned(path)
+    return {path.name:read_json(path) for path in paths}
+
+def verified_local(lib):
+    path=lib.root/'work/coordinator-renewal.json'
+    from .closed_ledger_fence import owned
+    owned(path)
+    record=read_json(path)
+    require(record.get('format')==FORMAT and record.get('state')=='verified'
+            and record.get('root')==str(lib.root.resolve()),
+            'Coordinator renewal is incomplete or belongs to another authority')
+    current=local(lib)
+    require(current==record['after'],'Renewed coordinator metadata changed')
+    return record
+
+def effective(lib,migration):
+    path=lib.root/'work/coordinator-renewal.json'
+    if not path.exists():return migration['afterMetadataDigest'],migration['request']['expectedTargetCatalogDigest']
+    record=verified_local(lib)
+    require(record.get('originalMigrationDigest')==digest(migration)
+            and record.get('binding')==migration['binding'],'Coordinator renewal changed migration authority')
+    return record['afterMetadataDigest'],record['targetCatalogDigest']
+
+def renew(lib,request,client=None):
+    require(isinstance(request,dict) and set(request)=={'expectedLocalDigest','reviewedBindings','expectedTargetCatalogDigest'},
+            'Exact coordinator renewal selectors required')
+    with lib.lock(),ExitStack() as stack:
+        for name in ['claude-service-start.lock','claude-service-owner.lock']:
+            path=lib.root/'work'/name
+            require(not path.is_symlink(),'Coordinator owner lock cannot be a symlink')
+            stream=stack.enter_context(path.open('a'))
+            try:fcntl.flock(stream.fileno(),fcntl.LOCK_EX|fcntl.LOCK_NB)
+            except BlockingIOError:raise PackError('Coordinator dispatcher owner lock is held')
+        bridge=read_json(lib.root/'live-bridge.json',{})
+        if bridge:
+            pid=bridge.get('pid');require(type(pid) is int and pid>1,'Native dispatcher owner is unverified')
+            try:os.kill(pid,0)
+            except ProcessLookupError:pass
+            else:require(False,'Stop the idle owning dispatcher before coordinator renewal')
+        journal=lib.root/'work/coordinator-renewal.json'
+        require(not journal.exists() and not journal.is_symlink(),'Existing coordinator renewal requires reconciliation, not replay')
+        before=local(lib);require(digest(before)==request['expectedLocalDigest'],'Reviewed coordinator preimage changed')
+        binding=before['cloud.json'];registry=before['role-bindings.json'];refs=request['reviewedBindings']
+        old={k:v for k,v in registry['roles'].items() if v['logicalId'] in LOGICAL}
+        require(len(old)==3 and isinstance(refs,dict) and set(refs)==set(old),'Exactly the three existing coordinators are required')
+        if client is None:
+            from .topolo import Client
+            client=Client('production','org:org_topolo_platform')
+        require(client.environment=='production' and client.context=='org:org_topolo_platform','Production organization context required')
+        from .coordinator_context import CONTRACT
+        for key,ref in refs.items():
+            prior=old[key]
+            require(set(ref)==set(prior) and {k:v for k,v in ref.items() if k!='instructionsSHA256'}=={k:v for k,v in prior.items() if k!='instructionsSHA256'},
+                    'Coordinator identity or domain context cannot change')
+            agent=client.action('app_topolo_agent.agents.get',{'id':ref['agentId']},ref['workspaceId'])['agent']
+            config=json.loads(agent['config']) if isinstance(agent['config'],str) else agent['config'];spec=config['specialization']
+            require(agent['id']==ref['agentId'] and agent['workspaceId']==ref['workspaceId']
+                    and agent['organizationId']==binding['organizationId']=='org_topolo_platform'
+                    and spec['format']=='topolo-role-specialization-v1' and spec['logicalId']==ref['logicalId']
+                    and config.get('domainContextRefs',[])==ref.get('domainContextRefs',[])
+                    and config['purpose']==spec['instructions'] and CONTRACT in spec['instructions']
+                    and hashlib.sha256(spec['instructions'].encode()).hexdigest()==ref['instructionsSHA256'],
+                    'Live coordinator conversation instructions differ')
+        from types import SimpleNamespace
+        version,state=CloudStore.load(SimpleNamespace(binding=binding,client=client))
+        for row in state['tables']['workers']:
+            w=json.loads(row[2])
+            require(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),
+                    'Native worker closure is unresolved; preserve its instructions')
+        after=copy.deepcopy(before);after['role-bindings.json']['roles'].update(copy.deepcopy(refs))
+        migration=before.get('cloud-migration.json')
+        if 'role-catalog.json' in before:
+            catalog=before['role-catalog.json'];require(registry['roles']==catalog['bindings'] and before['config.json']['catalogDigest']==digest(catalog)==request['expectedTargetCatalogDigest'],
+                    'Canonical role catalog preimage differs')
+            after['role-catalog.json']['bindings'].update(copy.deepcopy(refs))
+            target_digest=digest(after['role-catalog.json']);after['config.json']['catalogDigest']=target_digest
+        else:
+            require(migration is not None,'Existing migrated installation required')
+            target=pathlib.Path(before['cutover.json']['request']['destinationRoot'])
+            catalog=read_json(target/'work/role-catalog.json');target_digest=digest(catalog)
+            require(target_digest==request['expectedTargetCatalogDigest'],'Renewed canonical catalog differs')
+            canonical={r['logicalId']:r for r in catalog['bindings'].values()}
+            require(all(canonical.get(ref['logicalId'])==ref for ref in refs.values()),'Coordinator references differ from canonical renewal')
+        require(local(lib)==before,'Coordinator metadata changed during validation')
+        record={'format':FORMAT,'state':'prepared','root':str(lib.root.resolve()),'before':before,'after':after,
+                'binding':binding,'cloudVersionId':version,'targetCatalogDigest':target_digest,
+                'originalMigrationDigest':digest(migration) if migration else None,'cloudTaskStateChanged':False}
+        atomic_json(journal,record)
+        for name in ['role-bindings.json','role-catalog.json','config.json']:
+            if name in after:atomic_json(lib.root/'work'/name,after[name])
+        require(local(lib)==after,'Coordinator renewal readback differs')
+        if migration:
+            from .cloud_migrate import metadata
+            record['afterMetadataDigest']=digest(metadata(lib))
+        atomic_json(journal,{**record,'state':'verified'})
+        if migration:
+            from .cloud_migrate import verified
+            verified(lib.root)
+        return {'state':'coordinator-instructions-renewed','coordinators':3,'catalogDigest':target_digest,
+                'tasksCreated':0,'nativeSessionsCreated':0,'cloudTaskStateChanged':False}

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

@@ -0,0 +1,45 @@
+"""One fixed no-tool turn through the owning proxy; never replays delivery."""
+import pathlib
+import uuid
+from .storage import PackError,atomic_json,read_json
+
+async def run(owner,params):
+    if not isinstance(params,dict) or set(params)!={'operationId','key'}:
+        raise PackError('Exact desktop acceptance identity required')
+    try:valid=str(uuid.UUID(params['operationId']))==params['operationId']
+    except (ValueError,TypeError,AttributeError):valid=False
+    if not valid:
+        raise PackError('Acceptance UUID required')
+    path=pathlib.Path(owner.runtime)/'desktop-acceptance'/(params['operationId']+'.json')
+    rows=[r for r in owner.execution.roles.values() if r['key']==params['key']]
+    if len(rows)!=1:
+        raise PackError('Owned acceptance role missing')
+    role=rows[0];tid=role['threadId']
+    if path.exists():
+        record=read_json(path)
+        if record['key']!=params['key'] or record['threadId']!=tid:
+            raise PackError('Acceptance identity changed')
+        if not record.get('turnId'):return record
+        native=await owner.call_native('thread/read',{'threadId':tid,'includeTurns':True})
+        matches=[t for t in native['thread'].get('turns',[]) if t['id']==record['turnId']]
+        if len(matches)!=1:
+            raise PackError('Exact acceptance turn missing')
+        turn=matches[0];items=turn.get('items',[])
+        text='\n'.join(i.get('text','') for i in items if i.get('type')=='agentMessage' and i.get('phase')!='commentary')
+        record.update(nativeStatus=turn['status'],reply=text)
+        record['verified']=turn['status']=='completed' and text.strip().rstrip('.')=='TOPOLO_DESKTOP_ACCEPTED' and all(i.get('type') in {'userMessage','agentMessage','reasoning','tokenUsage'} for i in items)
+        atomic_json(path,record);return record
+    if owner.active_turns or owner.pending or owner.quiesced:
+        raise PackError('Acceptance requires an idle owner')
+    await owner.call_native('thread/resume',{'threadId':tid})
+    spec=role['settings'];record={**params,'threadId':tid,'state':'reserved','verified':False,'settings':spec}
+    atomic_json(path,record)
+    # Save uncertainty before sending. A lost ACK cannot create another turn.
+    record['state']='delivery-uncertain';atomic_json(path,record)
+    roots=[role['cwd']]
+    home=getattr(owner.execution,'desktop_home',None)
+    if home is not None:
+        matches=list((pathlib.Path(home)/'visualizations').glob('*/*/*/'+tid))
+        if len(matches)==1:roots.append(str(matches[0]))
+    result=await owner.call_native('turn/start',{'threadId':tid,'input':[{'type':'text','text':'Transport acceptance test only. Do not use tools, read files, perform work, contact anyone or resume any task. Reply exactly TOPOLO_DESKTOP_ACCEPTED.'}],'environments':[{'environmentId':'local','cwd':role['cwd'],'runtimeWorkspaceRoots':roots}], 'runtimeWorkspaceRoots':roots, 'collaborationMode':{'mode':'default','settings':{'model':spec['model'],'reasoning_effort':spec['model_reasoning_effort'],'developer_instructions':None}}})
+    record.update(state='native-accepted',turnId=result['turn']['id']);atomic_json(path,record);return record

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

@@ -0,0 +1,114 @@
+"""An owned Dock launcher for the selected Agent Pack, separate from personal apps."""
+import hashlib
+import json
+import os
+from pathlib import Path
+import plistlib
+import shlex
+import re
+import subprocess
+import sys
+import tempfile
+
+from .storage import PackError, atomic_json, read_json
+from .work import require
+
+
+def _digest(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _files(root):
+    result = {}
+    for path in sorted(root.rglob('*')):
+        metadata = path.lstat()
+        require(not path.is_symlink() and metadata.st_uid == os.getuid()
+                and not metadata.st_mode & 0o022, 'Desktop launcher contains an unowned or writable entry')
+        if path.is_file():
+            result[str(path.relative_to(root))] = _digest(path)
+    return result
+
+
+def install(lib, app, codex_bin, run=None):
+    """Caller owns Library.lock. Compilation/configuration does not open any app."""
+    require(sys.platform == 'darwin', 'Managed Dock launchers require macOS')
+    run = run or subprocess.run
+    root = lib.root.resolve(); folder = root / 'launchers'
+    folder.mkdir(exist_ok=True, mode=0o700)
+    target = folder / 'Topolo Agent Pack.app'; shim = folder / 'topolo-agent-pack-open'
+    record = folder / 'desktop-launcher.json'
+    require(not folder.is_symlink() and folder.stat().st_uid == os.getuid()
+            and not folder.stat().st_mode & 0o022, 'Unowned desktop launcher directory')
+    app = Path(app).expanduser().resolve(); native = Path(codex_bin).expanduser().resolve()
+    require(app.is_dir() and native.is_file(), 'Existing native application and CLI are required')
+    adapter = Path(__file__).resolve().parents[2] / 'topolo-agent-pack'
+    require(adapter.is_file(), 'Installed public pack adapter is unavailable')
+    argv = [sys.executable, str(adapter), '--store', str(root), 'open', '--app', str(app), '--codex-bin', str(native)]
+    source = '#!' + sys.executable + '\nimport os\nos.execv(' + repr(sys.executable) + ',' + repr(argv) + ')\n'
+    script = ('on openPack()\ntry\ndo shell script ' + json.dumps(shlex.join([str(shim)])) +
+              '\non error messageText number errorNumber\ndisplay alert "Topolo Agent Pack" message messageText as warning\nend try\nend openPack\non run\nmy openPack()\nend run\non reopen\nmy openPack()\nend reopen\n')
+    script_digest = hashlib.sha256(script.encode()).hexdigest()
+    previous = read_json(record, {})
+    if previous:
+        require(set(previous) == {'format', 'store', 'app', 'scriptSHA256', 'appFiles', 'shimSHA256'}
+                and previous['format'] == 'topolo-managed-desktop-launcher-v1'
+                and previous['store'] == str(root) and previous['app'] == str(target)
+                and previous['scriptSHA256'] == script_digest
+                and not target.is_symlink() and target.is_dir() and _files(target) == previous['appFiles']
+                and not shim.is_symlink() and shim.is_file() and _digest(shim) == previous['shimSHA256'],
+                'Existing managed Dock launcher changed; reconcile before replacement')
+    else:
+        require(not target.exists() and not target.is_symlink() and not shim.exists() and not shim.is_symlink(),
+                'Desktop launcher destination is not an owned installation')
+        with tempfile.TemporaryDirectory(prefix='.desktop-launcher-', dir=folder) as temporary:
+            temporary = Path(temporary); apple = temporary / 'launcher.applescript'; apple.write_text(script)
+            built = temporary / target.name
+            run(['/usr/bin/osacompile', '-s', '-o', str(built), str(apple)], check=True, timeout=30)
+            info = built / 'Contents/Info.plist'
+            value = plistlib.loads(info.read_bytes())
+            value.update(CFBundleIdentifier='io.topolo.agent-pack.' + hashlib.sha256(str(root).encode()).hexdigest()[:16],
+                         CFBundleName='Topolo Agent Pack', CFBundleDisplayName='Topolo Agent Pack')
+            info.write_bytes(plistlib.dumps(value))
+            run(['/usr/bin/codesign', '--force', '--sign', '-', str(built)], check=True, timeout=30)
+            run(['/usr/bin/codesign', '--verify', '--deep', '--strict', str(built)], check=True, timeout=15)
+            _files(built)
+            os.rename(built, target)
+    # Refuse unjournaled partial publication instead of silently replacing it.
+    temporary = shim.with_name(shim.name + '.new')
+    require(not temporary.exists() and not temporary.is_symlink(), 'Desktop launcher publication is unresolved')
+    with temporary.open('x') as stream:
+        os.chmod(temporary, 0o700); stream.write(source); stream.flush(); os.fsync(stream.fileno())
+    os.replace(temporary, shim)
+    value = {'format': 'topolo-managed-desktop-launcher-v1', 'store': str(root), 'app': str(target),
+             'scriptSHA256': script_digest, 'appFiles': _files(target), 'shimSHA256': _digest(shim)}
+    atomic_json(record, value)
+    require(read_json(record) == value and _files(target) == value['appFiles'], 'Desktop launcher readback differs')
+    return {'state': 'managed-desktop-launcher-installed', 'app': str(target), 'store': str(root),
+            'appOpened': False, 'dockPreferencesChanged': False}
+
+
+def restore(lib, bridge, app, run=None):
+    """Activate only the current managed PID; never prepare or restart its backend."""
+    require(sys.platform == 'darwin', 'Managed window restoration requires macOS')
+    run = run or subprocess.run
+    pid = bridge.get('desktopPid'); expected_runtime = lib.active().get('runtime')
+    require(type(pid) is int and pid > 1 and bridge.get('runtime') == expected_runtime
+            and bridge.get('nativeTransport') == 'owned-stdio', 'Exact managed Desktop owner is required')
+    os.kill(pid, 0)
+    command = run(['/bin/ps', '-p', str(pid), '-o', 'command='], check=True, capture_output=True,
+                  text=True, timeout=5).stdout.strip()
+    bundle = Path(app).expanduser().resolve()
+    executable_name = plistlib.loads((bundle / 'Contents/Info.plist').read_bytes())['CFBundleExecutable']
+    require(isinstance(executable_name, str) and Path(executable_name).name == executable_name,
+            'Native application executable identity differs')
+    executable = str(bundle / 'Contents/MacOS' / executable_name)
+    flag = '--user-data-dir=' + str(lib.root / 'desktop-data')
+    require(command.startswith(executable + ' ') and re.search(r'(?:^|\s)' + re.escape(flag) + r'(?:\s|$)', command),
+            'Managed Desktop process does not own this library profile')
+    # AppKit activation targets this PID. Electron's normal activate handler
+    # restores its primary window; a same-bundle personal process is untouched.
+    script = ('ObjC.import("AppKit"); const app=$.NSRunningApplication.runningApplicationWithProcessIdentifier(' +
+              str(pid) + '); if(!app || !app.activateWithOptions($.NSApplicationActivateAllWindows|$.NSApplicationActivateIgnoringOtherApps)) throw Error("Managed window activation refused");')
+    run(['/usr/bin/osascript', '-l', 'JavaScript', '-e', script], check=True, timeout=15)
+    return {'state': 'managed-window-restoration-requested', 'desktopPid': pid,
+            'runtime': expected_runtime, 'backendRestarted': False, 'frontendVerified': False}

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

@@ -0,0 +1,38 @@
+"""Selected immutable operating references, separate from task history."""
+import hashlib,pathlib
+from .storage import atomic_json
+from .work import require
+from .cicd import DISCIPLINES
+
+
+def references(config,logical):
+    selected=logical=='intakes/cicd' or logical in {'specialists/'+name for name in DISCIPLINES}
+    refs=config.get('domainContextRefs',[])
+    require(isinstance(refs,list) and len(refs)==(1 if selected else 0),'CI/CD requires one reviewed release-controller domain reference')
+    for ref in refs:
+        require(isinstance(ref,dict) and set(ref)=={'workspaceId','documentId','versionId','bodySHA256','heading','sectionSHA256'} and all(isinstance(v,str) and v for v in ref.values()),'Invalid domain context reference')
+        require(ref['heading']=='CI/CD operating bootstrap' and all(len(ref[k])==64 and all(c in '0123456789abcdef' for c in ref[k]) for k in ['bodySHA256','sectionSHA256']),'Unqualified release-controller bootstrap reference')
+    return refs
+
+
+def materialize(refs,cwd,client):
+    receipts=[]
+    for ref in refs:
+        result=client.action('app_topolo_docs.documents.get',{'documentId':ref['documentId']},ref['workspaceId'])
+        doc=result['document'];require(isinstance(result['versions'],list) and len(result['versions'])<=128,'Operating reference history exceeds the bounded reader')
+        versions=[v for v in result['versions'] if v['id']==ref['versionId']]
+        require(doc['id']==ref['documentId'] and doc['workspaceId']==ref['workspaceId'] and doc['organizationId']=='org_topolo_platform' and len(versions)==1,'Pinned operating reference is unavailable')
+        body=versions[0]['bodyMarkdown']
+        require(isinstance(body,str) and len(body.encode())<=1000000,'Operating reference body exceeds the bounded reader')
+        require(hashlib.sha256(body.encode()).hexdigest()==ref['bodySHA256'],'Pinned operating reference changed')
+        marker='## '+ref['heading']+'\n'
+        require(body.count(marker)==1,'Operating bootstrap heading is missing or ambiguous')
+        section=body.split(marker,1)[1].split('\n## ',1)[0].strip()+'\n'
+        require(100<=len(section.encode())<=12000 and hashlib.sha256(section.encode()).hexdigest()==ref['sectionSHA256'],'Operating bootstrap section differs')
+        require(all(term in section for term in ['Topolo-io/TopoloReleaseController','topolo-box-submit','"op":"intent-status"','"op":"job-diagnostic"','hosts','read-only']),'Operating bootstrap lacks controller access and custody boundaries')
+        target=pathlib.Path(cwd)/'context';require(not target.is_symlink(),'Domain context directory cannot be a symlink');target.mkdir(exist_ok=True,mode=0o700)
+        path=target/'release-controller.md';require(not path.is_symlink(),'Domain context file cannot be a symlink')
+        path.write_text('# Verified CI/CD operating reference\n\n'+marker+section);path.chmod(0o600)
+        receipts.append(dict(ref))
+    if receipts:atomic_json(pathlib.Path(cwd)/'context/domain-source.json',{'format':'topolo-selected-domain-context-v1','references':receipts,'taskHistoryLoaded':False,'wholeDocumentLoadedIntoContext':False})
+    return receipts