@topolo/cli 0.13.17 → 0.13.21

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

@@ -0,0 +1,149 @@
+"""Bounded allocation decisions, without claim writes, wakeups or ownership changes.
+
+Callers supply current canonical and native observations, then atomically claim
+against snapshotDigest before dispatch. A plan is never evidence of execution.
+"""
+from .storage import PackError
+from .task_models import digest, resolve
+
+
+def _require(condition, message):
+    if not condition:
+        raise PackError(message)
+
+
+def _keys(value, fields):
+    _require(isinstance(value, dict) and set(value) == set(fields.split()),
+             'Allocation input requires exact fields: ' + fields)
+
+
+def _text(value):
+    return isinstance(value, str) and 0 < len(value) <= 240
+
+
+def _integer(value, minimum, maximum):
+    return type(value) is int and minimum <= value <= maximum
+
+
+def _names(value):
+    return (isinstance(value, list) and len(value) <= 256 and
+            all(_text(item) for item in value) and len(value) == len(set(value)))
+
+
+def allocate(snapshot):
+    """Choose compatible idle workers fairly; isolate stale/blocked work.
+
+    Observations are supplied evidence, not a native status probe. Existing
+    owners stay pinned. Retained custody is reusable only at an explicit safe
+    checkpoint with the actual native worker idle. Resource slots are separate
+    from chat availability and apply to both existing and proposed workers.
+    """
+    _keys(snapshot, 'schemaVersion now maxAgeSeconds slots maxNewLanes tasks lanes completed configuration catalog')
+    _require(snapshot['schemaVersion'] == 1 and
+             _integer(snapshot['now'], 1, 2**53) and
+             _integer(snapshot['maxAgeSeconds'], 1, 3600) and
+             _integer(snapshot['slots'], 0, 32) and
+             _integer(snapshot['maxNewLanes'], 0, 8) and
+             _names(snapshot['completed']), 'Invalid allocation bounds')
+    tasks, lanes = snapshot['tasks'], snapshot['lanes']
+    _require(isinstance(tasks, list) and len(tasks) <= 256 and
+             isinstance(lanes, list) and len(lanes) <= 256, 'Bounded task and lane lists required')
+    task_ids, lane_ids = set(), set()
+    for task in tasks:
+        _keys(task, 'id capability priority owner dependencies authorized paused modelTask')
+        _require(_text(task['id']) and task['id'] not in task_ids and
+                 _text(task['capability']) and _integer(task['priority'], 0, 9) and
+                 (task['owner'] is None or _text(task['owner'])) and
+                 _names(task['dependencies']) and task['id'] not in task['dependencies'] and
+                 type(task['authorized']) is bool and type(task['paused']) is bool,
+                 'Malformed or duplicate allocation task')
+        task_ids.add(task['id'])
+    for lane in lanes:
+        _keys(lane, 'id capabilities observedAt registryState nativeState activeTask retainedTasks reusableCheckpoint assignments lastAssigned constraints')
+        _require(_text(lane['id']) and lane['id'] not in lane_ids and
+                 _names(lane['capabilities']) and _names(lane['retainedTasks']) and
+                 _integer(lane['observedAt'], 1, 2**53) and
+                 lane['registryState'] in {'idle', 'busy', 'held', 'paused', 'unknown'} and
+                 lane['nativeState'] in {'idle', 'busy', 'unknown'} and
+                 (lane['activeTask'] is None or _text(lane['activeTask'])) and
+                 type(lane['reusableCheckpoint']) is bool and
+                 _integer(lane['assignments'], 0, 2**53) and
+                 _integer(lane['lastAssigned'], 0, 2**53), 'Malformed or duplicate allocation lane')
+        lane_ids.add(lane['id'])
+    completed = set(snapshot['completed'])
+    _require(not completed.intersection(task_ids), 'Completed tasks must not remain in the ready queue')
+    result = {'format': 'topolo-allocation-plan', 'schemaVersion': 1,
+              'snapshotDigest': digest(snapshot), 'assignments': [], 'createRequests': [],
+              'blocked': [], 'laneIssues': [], 'effectsStarted': False,
+              'executionRequirements': ['current exclusive claim against snapshotDigest',
+                                        'native model and effort acknowledgement',
+                                        'verified authorized task delivery and result readback']}
+    eligible = []
+    for lane in lanes:
+        age = snapshot['now'] - lane['observedAt']
+        issue = None
+        if age < 0 or age > snapshot['maxAgeSeconds']:
+            issue = 'stale-observation'
+        elif lane['registryState'] in {'paused', 'unknown'} or lane['nativeState'] == 'unknown':
+            issue = 'paused-or-unknown'
+        elif lane['activeTask'] is not None or lane['nativeState'] == 'busy':
+            issue = 'occupied'
+        elif lane['registryState'] == 'busy':
+            issue = 'reconcile-registry-with-idle-native'
+        elif lane['retainedTasks'] or lane['registryState'] == 'held':
+            if not lane['reusableCheckpoint']:
+                issue = 'custody-checkpoint-required'
+        if issue:
+            result['laneIssues'].append({'laneId': lane['id'], 'reason': issue})
+        else:
+            eligible.append(lane)
+    slots = snapshot['slots']
+    for task in sorted(tasks, key=lambda row: (row['priority'], row['id'])):
+        reason = None
+        if task['paused']:
+            reason = 'task-paused'
+        elif not task['authorized']:
+            reason = 'task-unauthorized'
+        elif not set(task['dependencies']).issubset(completed):
+            reason = 'dependencies-pending'
+        elif not slots:
+            reason = 'execution-capacity-exhausted'
+        if reason:
+            result['blocked'].append({'taskId': task['id'], 'reason': reason})
+            continue
+        compatible = [lane for lane in lanes if task['capability'] in lane['capabilities'] and
+                      (task['owner'] is None or lane['id'] == task['owner'])]
+        candidates = sorted((lane for lane in compatible if lane in eligible),
+                            key=lambda row: (row['assignments'], row['lastAssigned'], row['id']))
+        failures = []
+        for lane in candidates:
+            try:
+                resolution = resolve(snapshot['configuration'], task['modelTask'],
+                                     snapshot['catalog'].get('harness'), snapshot['catalog'], lane['constraints'])
+            except (PackError, AttributeError) as error:
+                failures.append({'laneId': lane['id'], 'reason': str(error)})
+                continue
+            result['assignments'].append({'taskId': task['id'], 'laneId': lane['id'],
+                                          'resolution': resolution,
+                                          'retainedTasks': list(lane['retainedTasks'])})
+            eligible.remove(lane)
+            slots -= 1
+            break
+        else:
+            uncertain = any(issue['laneId'] in {lane['id'] for lane in compatible} and
+                            issue['reason'] in {'stale-observation', 'paused-or-unknown',
+                                                'reconcile-registry-with-idle-native'}
+                            for issue in result['laneIssues'])
+            if (task['owner'] is None and not candidates and not uncertain and
+                    len(result['createRequests']) < snapshot['maxNewLanes']):
+                result['createRequests'].append({'taskId': task['id'], 'capability': task['capability'],
+                                                  'reason': 'no-compatible-free-lane',
+                                                  'requires': 'registered native lane and verified task model before claim'})
+                slots -= 1
+            else:
+                result['blocked'].append({'taskId': task['id'],
+                                          'reason': ('model-unavailable' if failures else
+                                                     'lane-state-reconciliation-required' if uncertain else
+                                                     'owner-or-capability-unavailable'),
+                                          'modelFailures': failures})
+    return result

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

@@ -51,7 +51,7 @@ class Client:
         if any(selected.get(k) for k in ['TOPOLO_API_KEY','TOPOLO_ACCESS_TOKEN','TOPOLO_'+environment.upper()+'_API_KEY','TOPOLO_'+environment.upper()+'_ACCESS_TOKEN']):
             raise PackError('Pinned connections require the CLI protected account context, not injected credentials')
         self.environment=environment;self.context=context
-        self.binary=binary or shutil.which('topolo')
+        self.binary=binary or shutil.which('topolo') or next((str(p) for p in [pathlib.Path('/opt/homebrew/bin/topolo'),pathlib.Path('/usr/local/bin/topolo')] if p.is_file() and os.access(p,os.X_OK)),None)
         if not self.binary:
             raise PackError('Install the public @topolo/cli and authenticate before connecting')
         self.env={**selected,'TOPOLO_CONTEXT':context}
@@ -81,6 +81,12 @@ class Client:
             if upload:
                 result=self.run(['actions','upload',*common,'--file',str(upload),'--content-type',input.get('type','application/octet-stream'),'--confirm'])
             else:result=self.run(['actions','call',*common,'--detail',*(['--confirm'] if write else [])])
+            # Public CLI action calls wrap the full service envelope in result.
+            # Do not mistake that transport wrapper for the actual cloud record.
+            if isinstance(result,dict) and 'actionId' in result and 'result' in result:
+                if result['actionId']!=action:
+                    raise PackError('Topolo action response identity mismatch')
+                result=result['result']
             if isinstance(result,dict) and result.get('success') is False:
                 raise PackError('Topolo action failed')
             return result.get('data',result) if isinstance(result,dict) else result

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

@@ -0,0 +1,322 @@
+"""Durable task records and single-use native workers; no model or transport mocks.
+
+The SQLite record owns continuity. Native threads are disposable execution slots.
+A reserved/uncertain send is never replayed by process recovery.
+"""
+import copy
+import hashlib
+import json
+import os
+import pathlib
+import re
+import sqlite3
+import time
+import uuid
+from contextlib import contextmanager
+from .storage import PackError, canonical
+
+STATES={'queued','routing','executing','reviewing','completed','needs_input','blocked','failed','unknown'}
+TERMINAL={'completed','needs_input','blocked','failed','unknown'}
+
+def require(ok,message):
+    if not ok:raise PackError(message)
+
+def text(value,limit=16000):
+    return isinstance(value,str) and 0<len(value.strip())<=limit
+
+class Store:
+    def __init__(self,root):
+        self.root=pathlib.Path(root)/'work';self.root.mkdir(mode=0o700,exist_ok=True)
+        require(not self.root.is_symlink() and self.root.stat().st_uid==os.getuid() and not self.root.stat().st_mode&0o022,'Work store must be privately owned')
+        self.path=self.root/'tasks.sqlite'
+        require(not self.path.is_symlink(),'Work database cannot be a symlink')
+        with self.db() as db:
+            db.executescript('''CREATE TABLE IF NOT EXISTS tasks(id TEXT PRIMARY KEY, input_hash TEXT NOT NULL, body TEXT NOT NULL);
+            CREATE TABLE IF NOT EXISTS workers(id TEXT PRIMARY KEY,task_id TEXT NOT NULL,body TEXT NOT NULL);
+            CREATE TABLE IF NOT EXISTS events(sequence INTEGER PRIMARY KEY AUTOINCREMENT, task_id TEXT NOT NULL, body TEXT NOT NULL);
+            CREATE TABLE IF NOT EXISTS retained(id TEXT PRIMARY KEY,body TEXT NOT NULL);''')
+            db.execute('CREATE TABLE IF NOT EXISTS responses(id TEXT PRIMARY KEY,input_hash TEXT NOT NULL,task_id TEXT NOT NULL)')
+        self.path.chmod(0o600)
+    @contextmanager
+    def db(self):
+        require(not (self.root/'cutover.json').exists(),'Legacy work is durably fenced for cloud cutover')
+        db=sqlite3.connect(self.path,timeout=10)
+        try:
+            db.execute('BEGIN IMMEDIATE')
+            require(not (self.root/'cutover.json').exists(),'Legacy work is durably fenced for cloud cutover')
+            yield db;db.commit()
+        except BaseException:db.rollback();raise
+        finally:db.close()
+    def event(self,db,tid,kind,summary):
+        db.execute('INSERT INTO events(task_id,body) VALUES (?,?)',(tid,json.dumps({'taskId':tid,'kind':kind,'summary':summary,'at':time.time()})))
+    def submit(self,request):
+        require(isinstance(request,dict) and set(request)=={'requestId','objective','channel','canonicalClaimId'},'Exact work request fields required')
+        try:valid=str(uuid.UUID(request['requestId']))==request['requestId']
+        except (ValueError,TypeError,AttributeError):valid=False
+        require(valid and text(request['objective']) and request['channel'] in {'engineering','operations','cicd'} and (request['canonicalClaimId'] is None or text(request['canonicalClaimId'],240)),'Invalid work request')
+        identity=request['requestId'];fingerprint=hashlib.sha256(canonical(request)).hexdigest()
+        with self.db() as db:
+            row=db.execute('SELECT input_hash,body FROM tasks WHERE id=?',(identity,)).fetchone()
+            if row:
+                require(row[0]==fingerprint,'Request ID already has a different objective');return json.loads(row[1]),False
+            claim=request['canonicalClaimId']
+            if claim:
+                retained=db.execute('SELECT body FROM retained WHERE id=?',(claim,)).fetchone()
+                require(retained is None,'Existing claim retains its owner and checkpoint; per-task adoption is required before dispatch')
+                raise PackError('Unknown canonical claim; reconcile its current owner before dispatch')
+            task={**copy.deepcopy(request),'id':identity,'revision':1,'attempt':1,'state':'queued','phase':'route','summary':'Request recorded; routing pending.','createdAt':time.time(),'updatedAt':time.time(),'deliveryOwner':'task:'+identity,'workerIds':[],'checkpoints':[]}
+            db.execute('INSERT INTO tasks VALUES (?,?,?)',(identity,fingerprint,json.dumps(task)));self.event(db,identity,'requested',task['summary']);return task,True
+    def get(self,tid):
+        with self.db() as db:
+            row=db.execute('SELECT body FROM tasks WHERE id=?',(tid,)).fetchone();require(row is not None,'Unknown task');return json.loads(row[0])
+    def adopt_retained(self,request,prepared,receipt,parent_proof=None):
+        """Commit a broker-verified receipt and unique continuation atomically.
+
+        Retained inventory is immutable. The original delivery task, source
+        owner, failed jobs and all uncertain effects retain their custody.
+        """
+        from .work_adoption import validate,digest,request_digest
+        validate(request)
+        require(prepared.get('requestSHA256')==request_digest(request)
+                and receipt.get('planSHA256')==digest(prepared)
+                and receipt.get('authority')=='current-authenticated-human-instruction'
+                and receipt.get('scope')==prepared.get('scope')=='read-only-checkpoint-diagnostic',
+                'Verified current human diagnostic authorization required')
+        identity=request['requestId'];fingerprint=digest(request)
+        with self.db() as db:
+            row=db.execute('SELECT input_hash,body FROM tasks WHERE id=?',(identity,)).fetchone()
+            if row:
+                require(row[0]==fingerprint,'Request ID already has a different adoption')
+                task=json.loads(row[1])
+                require(task.get('adoption',{}).get('receipt')==receipt,'Adoption receipt differs')
+                return task,False
+            row=db.execute('SELECT body FROM retained WHERE id=?',(request['canonicalClaimId'],)).fetchone()
+            require(row is not None and digest(json.loads(row[0]))==prepared['retainedSHA256'],
+                    'Retained claim changed; preserve original custody')
+            tasks=[json.loads(r[0]) for r in db.execute('SELECT body FROM tasks')]
+            require(not any(t.get('canonicalClaimId')==request['canonicalClaimId'] for t in tasks),
+                    'Canonical claim already has a continuation; no duplicate dispatch')
+            related={t['id'] for t in tasks if t.get('canonicalClaimId')==request['canonicalClaimId']}|{request['continuationOwnerTaskId']}
+            workers=[json.loads(r[0]) for r in db.execute('SELECT body FROM workers')]
+            require(all(w['state']=='archived' and w.get('nativeArchived') is True for w in workers if w['taskId'] in related),
+                    'Current cloud worker retains active or unresolved custody')
+            parents=[t for t in tasks if t['id']==request['continuationOwnerTaskId']]
+            require(len(parents)==1 and parents[0]['channel']=='engineering'
+                    and parents[0]['state'] not in {'unknown','completed','failed'},
+                    'Originating delivery task is missing, closed or uncertain')
+            parent=parents[0]
+            require(parent['revision']==request['continuationRevision'],'Parent revision changed; reread before adoption')
+            from .work_adoption import parent_heads
+            owned_workers=[w for w in workers if w['taskId']==parent['id']]
+            require(digest(parent_heads(parent,owned_workers))==request['parentCheckpointSHA256'],'Parent checkpoint heads changed')
+            if parent.get('ownerInstallationId')!=receipt['installationId']:
+                require(parent_proof is not None and parent['state'] in {'blocked','needs_input'}
+                        and parent_proof['fromInstallationId']==parent.get('ownerInstallationId')
+                        and parent_proof['toInstallationId']==receipt['installationId']
+                        and parent_proof['revision']==parent['revision']
+                        and parent_proof['checkpointHeadsSHA256']==request['parentCheckpointSHA256'],
+                        'Closed parent cloud checkpoint transfer is unverified')
+                parent['ownerInstallationId']=receipt['installationId']
+                self.event(db,parent['id'],'closed-parent-owner-adopted','Current human authorized portable checkpoint ownership; parent state and holds unchanged.')
+            task={k:copy.deepcopy(request[k]) for k in ['requestId','objective','channel','canonicalClaimId']}
+            task.update(id=identity,revision=1,attempt=1,state='executing',phase='execute',
+                        summary='Current human authorized diagnostic-only continuation; original source and UNKNOWN holds preserved.',
+                        createdAt=time.time(),updatedAt=time.time(),
+                        deliveryOwner=parents[0]['deliveryOwner'],workerIds=[],checkpoints=[],
+                        route={'role':request['role'],'task':{'type':'retained-checkpoint-diagnostic',
+                               'complexity':'complex','risk':'security-critical'},'acceptance':request['acceptance']},
+                        adoption={'request':copy.deepcopy(request),'plan':copy.deepcopy(prepared),'receipt':copy.deepcopy(receipt),'parentTransfer':copy.deepcopy(parent_proof)},
+                        effectBoundary='Read-only checkpoint diagnosis. Source, tests, provider writes and releases require their separate existing gates.')
+            db.execute('INSERT INTO tasks VALUES (?,?,?)',(identity,fingerprint,json.dumps(task)))
+            parent=parents[0];parent.setdefault('continuations',[]).append({'taskId':identity,'canonicalClaimId':request['canonicalClaimId']})
+            parent.update(revision=parent['revision']+1,updatedAt=time.time())
+            db.execute('UPDATE tasks SET body=? WHERE id=?',(json.dumps(parent),parent['id']))
+            self.event(db,identity,'retained-checkpoint-adopted',task['summary'])
+            self.event(db,parent['id'],'continuation-linked','Canonical claim checkpoint continuation linked; delivery acceptance remains open.')
+            return task,True
+    def list(self):
+        with self.db() as db:return [json.loads(x[0]) for x in db.execute('SELECT body FROM tasks ORDER BY rowid DESC LIMIT 500')]
+    def update(self,tid,revision,changes,kind):
+        require(isinstance(changes,dict) and not(set(changes)-{'state','phase','summary','route','workerIds','checkpoints','result','verification','archiveError','contextRef'}),'Unsupported work transition')
+        if 'state' in changes:require(changes['state'] in STATES,'Unknown work state')
+        with self.db() as db:
+            row=db.execute('SELECT body FROM tasks WHERE id=?',(tid,)).fetchone();require(row is not None,'Unknown task');task=json.loads(row[0]);require(task['revision']==revision,'Task changed; reread before transition')
+            task.update(copy.deepcopy(changes));task.update(revision=revision+1,updatedAt=time.time());db.execute('UPDATE tasks SET body=? WHERE id=?',(json.dumps(task),tid));self.event(db,tid,kind,task['summary']);return task
+    def re_review(self,request):
+        require(isinstance(request,dict) and set(request)=={'requestId','taskId','revision','reviewWorkerId','reviewCheckpoint','note'},'Exact review-only continuation required')
+        require(type(request['revision']) is int and text(request['requestId'],100) and text(request['note'],8000),'Review continuation identity and reason required')
+        fingerprint=hashlib.sha256(canonical(request)).hexdigest()
+        with self.db() as db:
+            previous=db.execute('SELECT input_hash,task_id FROM responses WHERE id=?',(request['requestId'],)).fetchone()
+            if previous:
+                require(previous==(fingerprint,request['taskId']),'Review continuation identity already used')
+                return json.loads(db.execute('SELECT body FROM tasks WHERE id=?',(request['taskId'],)).fetchone()[0]),False
+            row=db.execute('SELECT body FROM tasks WHERE id=?',(request['taskId'],)).fetchone()
+            require(row is not None,'Unknown review task');task=json.loads(row[0])
+            require(task['revision']==request['revision'] and task['state'] in {'blocked','needs_input'}
+                    and task.get('phase')=='review','Task is not the exact rejected review checkpoint')
+            workers=[json.loads(w[0]) for w in db.execute('SELECT body FROM workers WHERE task_id=?',(task['id'],))]
+            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 workers),'Existing native closure is unresolved; no review continuation')
+            rejected=[w for w in workers if w['id']==request['reviewWorkerId']]
+            require(len(rejected)==1 and rejected[0]['phase']=='review' and rejected[0]['state']=='archived'
+                    and rejected[0].get('nativeArchived') is True
+                    and rejected[0].get('attempt',1)==task.get('attempt',1)
+                    and rejected[0].get('reviewGeneration',0)==task.get('reviewGeneration',0)
+                    and rejected[0].get('checkpoint')==request['reviewCheckpoint']
+                    and task.get('verification',{}).get('nativeCheckpoint')==request['reviewCheckpoint']
+                    and task['verification']['verdict'] in {'blocked','needs_input'},'Exact latest rejected review must be preserved')
+            result=task.get('result',{});execution=[w for w in workers if w['id']==result.get('workerId')]
+            require(len(execution)==1 and execution[0]['phase']=='execute' and execution[0]['state']=='archived'
+                    and execution[0].get('nativeArchived') is True
+                    and execution[0].get('attempt',1)==task.get('attempt',1)
+                    and execution[0].get('checkpoint')==result.get('checkpoint') and task.get('route'),
+                    'Existing exact execution result is required; execution cannot replay')
+            task.setdefault('reviewHistory',[]).append({'reviewWorkerId':request['reviewWorkerId'],
+                    'generation':task.get('reviewGeneration',0),'verification':copy.deepcopy(task['verification']),
+                    'continuation':copy.deepcopy(request)})
+            task.update(state='reviewing',phase='review',reviewGeneration=task.get('reviewGeneration',0)+1,
+                        revision=task['revision']+1,updatedAt=time.time(),
+                        summary='Review-only continuation authorized; original execution and rejected review retained.')
+            db.execute('UPDATE tasks SET body=? WHERE id=?',(json.dumps(task),task['id']))
+            db.execute('INSERT INTO responses VALUES (?,?,?)',(request['requestId'],fingerprint,task['id']))
+            self.event(db,task['id'],'review-continuation-requested',task['summary'])
+            return task,True
+
+    def reserve(self,tid,phase,role,resolution,capacity):
+        require(phase in {'route','execute','review'} and type(capacity) is int and 1<=capacity<=16,'Invalid worker reservation')
+        with self.db() as db:
+            rows=[json.loads(r[0]) for r in db.execute('SELECT body FROM workers')]
+            require(sum(w['state'] in {'reserved','creating','running','archiving','unknown'} for w in rows)<capacity,'Execution capacity occupied')
+            task=json.loads(db.execute('SELECT body FROM tasks WHERE id=?',(tid,)).fetchone()[0]);attempt=task.get('attempt',1)
+            require(not any(w['taskId']==tid and w['phase']==phase and w.get('attempt',1)==attempt and (phase!='review' or w.get('reviewGeneration',0)==task.get('reviewGeneration',0)) for w in rows),'A task phase already has a worker; never reuse or replay it')
+            wid=str(uuid.uuid4());worker={'id':wid,'taskId':tid,'phase':phase,'attempt':attempt,'role':role,'resolution':copy.deepcopy(resolution),'state':'reserved','nativeId':None,'turnId':None,'createdAt':time.time()}
+            if phase=='review':worker['reviewGeneration']=task.get('reviewGeneration',0)
+            db.execute('INSERT INTO workers VALUES (?,?,?)',(wid,tid,json.dumps(worker)));self.event(db,tid,'worker-reserved',phase+' worker reserved');return worker
+    def worker(self,wid):
+        with self.db() as db:
+            row=db.execute('SELECT body FROM workers WHERE id=?',(wid,)).fetchone();require(row is not None,'Unknown worker');return json.loads(row[0])
+    def workers(self):
+        with self.db() as db:return [json.loads(r[0]) for r in db.execute('SELECT body FROM workers')]
+    def worker_update(self,wid,changes):
+        require(not(set(changes)-{'state','nativeId','turnId','cwd','checkpoint','error','nativeArchived','roleSource','resolution','nativeRetirement','nativePlan'}),'Unsupported worker transition')
+        with self.db() as db:
+            row=db.execute('SELECT body FROM workers WHERE id=?',(wid,)).fetchone();require(row is not None,'Unknown worker');worker=json.loads(row[0]);worker.update(copy.deepcopy(changes));db.execute('UPDATE workers SET body=? WHERE id=?',(json.dumps(worker),wid));return worker
+    def progress(self,wid,item_id,summary):
+        require(text(item_id,200) and text(summary,1600),'Invalid worker progress')
+        with self.db() as db:
+            row=db.execute('SELECT body FROM workers WHERE id=?',(wid,)).fetchone();require(row is not None,'Unknown worker')
+            worker=json.loads(row[0])
+            if worker['state']!='running' or item_id in worker.get('progressItems',[]):
+                return False
+            task=json.loads(db.execute('SELECT body FROM tasks WHERE id=?',(worker['taskId'],)).fetchone()[0])
+            if task['state'] in TERMINAL:
+                return False
+            worker.setdefault('progressItems',[]).append(item_id)
+            task.update(summary='Reported progress: '+summary,revision=task['revision']+1,updatedAt=time.time())
+            db.execute('UPDATE workers SET body=? WHERE id=?',(json.dumps(worker),wid))
+            db.execute('UPDATE tasks SET body=? WHERE id=?',(json.dumps(task),task['id']))
+            self.event(db,task['id'],'worker-progress',task['summary'])
+            return True
+    def adopt_ready(self,tid,revision,installation):
+        require(text(installation,200),'Installation identity required')
+        with self.db() as db:
+            row=db.execute('SELECT body FROM tasks WHERE id=?',(tid,)).fetchone();require(row is not None,'Unknown task');task=json.loads(row[0])
+            require(task['revision']==revision,'Task changed; reread before checkpoint adoption')
+            require(task.get('resumeAfterCheckpoint') is True and task['state'] in {'queued','executing','reviewing'},'Task is held, uncertain or has no checkpoint-resumption authority')
+            workers=[json.loads(w[0]) for w in db.execute('SELECT body FROM workers WHERE task_id=?',(tid,))]
+            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 workers),'Existing worker closure is unresolved; preserve its owner')
+            phase={'queued':'route','executing':'execute','reviewing':'review'}[task['state']]
+            require(not 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 workers),'Existing phase result needs reconciliation, not replay')
+            if task.get('ownerInstallationId')==installation:
+                return task
+            previous=task.get('ownerInstallationId');require(isinstance(previous,str) and previous,'Previous installation ownership is missing')
+            task.update(ownerInstallationId=installation,revision=revision+1,updatedAt=time.time(),summary='Verified closed checkpoint adopted; only the pending phase may execute.')
+            task.setdefault('ownershipCheckpoints',[]).append({'from':previous,'to':installation,'at':task['updatedAt'],'pendingPhase':phase})
+            db.execute('UPDATE tasks SET body=? WHERE id=?',(json.dumps(task),tid));self.event(db,tid,'checkpoint-owner-adopted',task['summary']);return task
+    def portable_delta(self,tid,revision,source_digest,workers,changes,operation):
+        require(set(changes)=={'contextRef','result','verification'} and isinstance(workers,dict) and isinstance(operation,str) and len(operation)==64,'Exact portable delta transition required')
+        with self.db() as db:
+            row=db.execute('SELECT body FROM tasks WHERE id=?',(tid,)).fetchone();require(row is not None,'Unknown task');task=json.loads(row[0])
+            current=[json.loads(w[0]) for w in db.execute('SELECT body FROM workers WHERE task_id=? ORDER BY id',(tid,))]
+            require(task['state'] in TERMINAL and set(workers)=={w['id'] for w in current} and all(w['state']=='archived' and w.get('nativeArchived') is True for w in current),'Only verified archived terminal task checkpoints may be converted')
+            migration={'operationId':operation,'sourceDigest':source_digest,'nativeIdentities':{w['id']:{k:w.get(k) for k in ['nativeId','turnId','phase']} for w in current}}
+            if task.get('portableMigration')==migration:
+                require(all(task.get(k)==v for k,v in changes.items()) and all(w['checkpoint']==workers[w['id']] for w in current),'Applied portable delta differs');return task
+            require(task['revision']==revision and hashlib.sha256(canonical({'task':task,'workers':current})).hexdigest()==source_digest,'Portable delta source changed; no records overwritten')
+            require(isinstance(changes['contextRef'].get('artifact'),dict) and all(isinstance(p.get('artifact'),dict) for p in workers.values()),'Verified cloud references are required')
+            for worker in current:
+                worker['historicalCheckpoint']=worker['checkpoint'];worker['checkpoint']=copy.deepcopy(workers[worker['id']]);db.execute('UPDATE workers SET body=? WHERE id=?',(json.dumps(worker),worker['id']))
+            task.update(copy.deepcopy(changes),portableMigration=migration,revision=revision+1,updatedAt=time.time())
+            db.execute('UPDATE tasks SET body=? WHERE id=?',(json.dumps(task),tid));self.event(db,tid,'portable-delta-bound','Existing closed task checkpoints are verified in cloud storage; no work was replayed.');return task
+    def retained_import(self,claims,source):
+        with self.db() as db:
+            for index,claim in enumerate(claims):
+                identity=claim.get('claimId') or 'legacy:'+str(index)+':'+str(claim.get('taskId'))
+                value={k:claim.get(k) for k in ['claimId','taskId','ownerRole','ownerThreadId','state','worktree','branch']};value.update(source=source,pointer='/claims/'+str(index),disposition='retained_original_owner_no_dispatch')
+                db.execute('INSERT INTO retained VALUES (?,?) ON CONFLICT(id) DO UPDATE SET body=excluded.body',(identity,json.dumps(value)))
+            return db.execute('SELECT COUNT(*) FROM retained').fetchone()[0]
+    def retained(self):
+        with self.db() as db:return [json.loads(r[0]) for r in db.execute('SELECT body FROM retained')]
+    def retained_page(self,params):
+        require(isinstance(params,dict) and not set(params)-{'cursor','limit'},'Unsupported retained inventory fields')
+        cursor=params.get('cursor',0);limit=params.get('limit',50)
+        require(type(cursor) is int and cursor>=0 and type(limit) is int and 1<=limit<=100,'Invalid retained inventory page')
+        with self.db() as db:
+            total=db.execute('SELECT COUNT(*) FROM retained').fetchone()[0]
+            rows=db.execute('SELECT rowid,body FROM retained WHERE rowid>? ORDER BY rowid LIMIT ?',(cursor,limit+1)).fetchall()
+        chosen=[];size=0;last=cursor
+        for rowid,body in rows[:limit]:
+            value=json.loads(body);count=len(canonical(value))
+            if count>800000:
+                value={'source':value.get('source'),'pointer':value.get('pointer'),'oversizedRecord':True,'bytes':count,'disposition':'retained_original_owner_no_dispatch'};count=len(canonical(value))
+            if size+count>900000 and chosen:break
+            chosen.append(value);size+=count;last=rowid
+        more=bool(rows and (len(rows)>len(chosen)))
+        return {'claims':chosen,'total':total,'nextCursor':last if more else None,'disposition':'inventory_only_no_work_resumed'}
+
+    def events(self,tid=None):
+        with self.db() as db:
+            rows=db.execute('SELECT sequence,body FROM events'+(' WHERE task_id=?' if tid else '')+' ORDER BY sequence', (tid,) if tid else ())
+            return [{'sequence':r[0],**json.loads(r[1])} for r in rows]
+    def recover(self):
+        # Native effects may have happened between a send and its receipt. Keep
+        # custody and prohibit replay; recovery never starts a thread or turn.
+        for worker in self.workers():
+            if worker['state'] not in {'archived','failed','unknown'}:
+                self.worker_update(worker['id'],{'state':'unknown','error':'Owning connection ended; reconcile native receipt before any replay.'})
+                task=self.get(worker['taskId'])
+                self.update(task['id'],task['revision'],{'state':'unknown','summary':'Native delivery requires reconciliation; no retry was started.'},'recovery-required')
+
+    def respond(self,request):
+        require(isinstance(request,dict) and set(request)=={'requestId','taskId','revision','intent','note'},'Exact task response required')
+        require(text(request['requestId'],100) and text(request['note'],8000) and request['intent'] in {'continue','request_changes','hold'},'Invalid task response')
+        fingerprint=hashlib.sha256(canonical(request)).hexdigest()
+        with self.db() as db:
+            previous=db.execute('SELECT input_hash,task_id FROM responses WHERE id=?',(request['requestId'],)).fetchone()
+            if previous:
+                require(previous==(fingerprint,request['taskId']),'Response identity already used')
+                return json.loads(db.execute('SELECT body FROM tasks WHERE id=?',(request['taskId'],)).fetchone()[0]),False
+            row=db.execute('SELECT body FROM tasks WHERE id=?',(request['taskId'],)).fetchone();require(row is not None,'Unknown task');task=json.loads(row[0])
+            require(task['revision']==request['revision'],'Task changed; review current progress before responding')
+            require(task['state'] in TERMINAL and task['state']!='unknown','Task is active or delivery is uncertain; reconcile before a new attempt')
+            workers=[json.loads(w[0]) for w in db.execute('SELECT body FROM workers WHERE task_id=?',(task['id'],))]
+            require(all(w['state']=='archived' or (w['state']=='failed' and not w.get('turnId') and (not w.get('nativeId') or w.get('nativeArchived') is True)) for w in workers),'Native worker closure is unresolved; no new attempt')
+            task.setdefault('humanResponses',[]).append(copy.deepcopy(request));task['revision']+=1;task['updatedAt']=time.time()
+            if request['intent']=='hold':task.update(state='blocked',summary='Held by your request: '+request['note'])
+            else:task.update(state='queued',phase='route',attempt=task.get('attempt',1)+1,objective=task['objective']+'\n\nCurrent human response: '+request['note'],summary='Your response is recorded; a fresh specialist attempt will be routed.')
+            db.execute('UPDATE tasks SET body=? WHERE id=?',(json.dumps(task),task['id']));db.execute('INSERT INTO responses VALUES (?,?,?)',(request['requestId'],fingerprint,task['id']));self.event(db,task['id'],'human-response',task['summary']);return task,True
+
+
+def parse_route(text_value,roles):
+    raw=text_value.strip()
+    if raw.startswith('```'):raw=re.sub(r'^```(?:json)?\s*|\s*```$','',raw)
+    try:value=json.loads(raw)
+    except (TypeError,ValueError):raise PackError('Coordinator did not return a valid route; no worker started')
+    require(isinstance(value,dict) and set(value)=={'role','task','acceptance'},'Coordinator route has unsupported fields')
+    require(value['role'] in roles,'Coordinator selected an unknown discipline')
+    if isinstance(value['acceptance'],list):
+        require(1<=len(value['acceptance'])<=30 and all(text(v,4000) for v in value['acceptance']),'Coordinator acceptance criteria are invalid')
+        value['acceptance']='\n'.join(value['acceptance'])
+    require(text(value['acceptance'],12000),'Coordinator returned no bounded acceptance criteria')
+    require(isinstance(value['task'],dict) and set(value['task'])=={'type','complexity','risk'},'Coordinator must classify type, complexity and risk')
+    return value