@topolo/cli 0.13.19 → 0.13.21

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

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

@@ -0,0 +1,122 @@
+"""Human-authorized diagnostic continuation of one immutable cloud claim.
+
+Never reconstruct authority from a chat, local source path or worker assertion.
+The original failed jobs, source custody and uncertain effects remain held.
+"""
+import hashlib
+import json
+import pathlib
+import tempfile
+import uuid
+from .storage import canonical
+from .work import require, text
+
+FIELDS={'requestId','objective','channel','canonicalClaimId','continuationOwnerTaskId',
+        'role','acceptance','checkpointSHA256','checkpointRef','authorizationRef','continuationRevision','parentCheckpointSHA256'}
+SCOPE='read-only-checkpoint-diagnostic'
+
+def digest(value):
+    return hashlib.sha256(canonical(value)).hexdigest()
+
+def request_digest(request):
+    return digest(request)
+
+def validate(request):
+    require(isinstance(request,dict) and set(request)==FIELDS,'Exact retained adoption fields required')
+    for key in ['requestId','continuationOwnerTaskId']:
+        try:valid=str(uuid.UUID(request[key]))==request[key]
+        except (TypeError,ValueError,AttributeError):valid=False
+        require(valid,'Adoption requires exact task identities')
+    require(type(request['continuationRevision']) is int and request['continuationRevision']>0,'Exact parent revision required')
+    require(isinstance(request['parentCheckpointSHA256'],str) and len(request['parentCheckpointSHA256'])==64 and all(c in '0123456789abcdef' for c in request['parentCheckpointSHA256']),'Exact parent checkpoint heads required')
+    require(request['requestId']!=request['continuationOwnerTaskId'],'Continuation must retain its originating delivery task')
+    require(request['channel']=='engineering','Retained engineering channel required')
+    require(all(text(request[k],12000 if k=='acceptance' else 16000 if k=='objective' else 240)
+                for k in ['objective','canonicalClaimId','role','acceptance']),'Adoption requires objective, claim, registered role and string acceptance')
+    require(isinstance(request['checkpointSHA256'],str) and len(request['checkpointSHA256'])==64
+            and all(c in '0123456789abcdef' for c in request['checkpointSHA256']),'Exact canonical checkpoint digest required')
+    for key in ['checkpointRef','authorizationRef']:
+        ref=request[key]
+        require(isinstance(ref,dict) and set(ref)=={'appId','workspaceId','scope','key','etag','size','sha256'}
+                and ref['appId']=='app_topolo_bytes' and ref['scope']=='org'
+                and all(text(ref[k],1000) for k in ['workspaceId','key','etag','sha256'])
+                and type(ref['size']) is int and 0<ref['size']<=131072,'Exact bounded cloud evidence reference required')
+
+def read_evidence(store,ref):
+    from .topolo import read_artifact
+    require(getattr(store,'cloud',False),'Retained continuation requires activated cloud authority; no local history fallback')
+    authority=json.loads((store.root/'context-authority.json').read_text())
+    require(authority.get('organizationId')==store.binding['organizationId']
+            and authority.get('scope')==ref['scope'] and authority.get('workspaceId')==ref['workspaceId'],
+            'Selected claim evidence belongs to another cloud authority')
+    with tempfile.TemporaryDirectory(prefix='topolo-selected-claim-') as tmp:
+        path=pathlib.Path(tmp)/'selected.json'
+        read_artifact(store.client,{'input':{'bytesScope':ref['scope'],'bytesWorkspaceId':ref['workspaceId']}},ref['key'],ref,path)
+        return json.loads(path.read_text())
+
+def plan(request,retained,claim,roles):
+    validate(request)
+    require(request['role'] in roles,'Exact registered specialist role required')
+    require(retained['claimId']==request['canonicalClaimId']==claim.get('claimId'),'Claim identity differs')
+    require(text(retained.get('ownerThreadId'),200) and retained['ownerThreadId']==claim.get('ownerThreadId'),'Recorded original controller differs')
+    require(digest(claim)==request['checkpointSHA256'],'Canonical checkpoint changed')
+    require(any(word in str(claim.get('state','')).lower() for word in ['failed','blocked','held','paused','unknown']),
+            'Recorded claim is active or unqualified; preserve current custody')
+    require(not any(claim.get(key) for key in ['lease','activeLease','ownerLease','leaseId','ownerLeaseId','leaseExpiresAt','ownerLeaseExpiresAt','activeWorkerId','activeRunId']),
+            'Canonical claim has a live or unresolved owner lease')
+    return {'format':'topolo-retained-continuation-plan-v2','canonicalClaimId':request['canonicalClaimId'],
+            'checkpointSHA256':digest(claim),'retainedSHA256':digest(retained),
+            'fromOwnerThreadId':claim['ownerThreadId'],'toRole':request['role'],
+            'continuationOwnerTaskId':request['continuationOwnerTaskId'],'acceptance':request['acceptance'],
+            'requestSHA256':request_digest(request),'canonicalSource':request['checkpointRef'],
+            'authorizationRef':request['authorizationRef'],'checkpoint':claim,'scope':SCOPE,
+            'preserveUnknownEffects':True,'sourceOwnerRetained':True,'releaseGatesRetained':True}
+
+def verify_authority(request,prepared,authorization,actor,consent,installation):
+    consent=consent or {}
+    required={'format','principalId','organizationId','canonicalClaimId','checkpointSHA256','sourceHead',
+              'continuationOwnerTaskId','continuationRevision','parentCheckpointSHA256','scope','instruction','instructionSHA256'}
+    require(isinstance(authorization,dict) and set(authorization)==required
+            and authorization['format']=='topolo-human-retained-continuation-v1'
+            and authorization['scope']==prepared['scope']==SCOPE,'Exact human diagnostic authorization required')
+    require(actor.get('user',{}).get('role')=='owner' and actor.get('user',{}).get('id')==authorization['principalId']==consent.get('principalId')
+            and actor.get('organization',{}).get('id')==authorization['organizationId']=='org_topolo_platform'
+            and consent.get('approved') is True and consent.get('contextKey')=='org:org_topolo_platform',
+            'Current authenticated owner and installation consent differ')
+    require(all(authorization[k]==request[k] for k in ['canonicalClaimId','checkpointSHA256','continuationOwnerTaskId','continuationRevision','parentCheckpointSHA256'])
+            and text(authorization['instruction']) and hashlib.sha256(authorization['instruction'].encode()).hexdigest()==authorization['instructionSHA256'],
+            'Human instruction does not bind this exact claim continuation')
+    head=prepared['checkpoint'].get('head') or prepared['checkpoint'].get('sourceCommit')
+    require(isinstance(head,str) and len(head)==40 and all(c in '0123456789abcdef' for c in head)
+            and authorization['sourceHead']==head,'Exact source head differs from human authorization')
+    return {'authority':'current-authenticated-human-instruction','principalId':authorization['principalId'],
+            'organizationId':authorization['organizationId'],'installationId':installation,
+            'authorizationSHA256':digest(authorization),'consentSHA256':digest(consent),
+            'planSHA256':digest(prepared),'scope':SCOPE,'originalWorkerAcceptance':False}
+
+def parent_heads(parent,workers):
+    return {'result':parent.get('result',{}).get('checkpoint'),
+            'workers':[{'id':w['id'],'phase':w['phase'],'checkpoint':w.get('checkpoint')} for w in sorted(workers,key=lambda w:w['id'])]}
+
+def verify_parent(parent,workers,request,root,client,installation):
+    """Only closed portable checkpoints permit a foreign installation transfer."""
+    from .work_artifacts import read_checkpoint
+    require(parent['state'] in {'blocked','needs_input'} and parent['revision']==request['continuationRevision'],
+            'Parent is active, uncertain or revision changed; preserve custody')
+    require(workers and digest(parent_heads(parent,workers))==request['parentCheckpointSHA256'],
+            'Parent cloud checkpoint heads differ')
+    for worker in workers:
+        require(worker['state']=='archived' and worker.get('nativeArchived') is True
+                and text(worker.get('nativeId'),200) and text(worker.get('turnId'),200)
+                and isinstance(worker.get('checkpoint',{}).get('artifact'),dict),
+                'Parent native worker has unresolved or nonportable custody')
+        payload=read_checkpoint(root,worker['checkpoint'],parent['id'],worker['id'],client=client)
+        native=payload['nativeReceipt']
+        require(payload['phase']==worker['phase'] and native['threadId']==worker['nativeId']
+                and native['turnId']==worker['turnId'] and native['status'] in {'completed','failed','cancelled'},
+                'Parent terminal checkpoint differs')
+    require(parent.get('result',{}).get('checkpoint') in [w['checkpoint'] for w in workers],
+            'Parent result does not bind a verified terminal checkpoint')
+    return {'fromInstallationId':parent.get('ownerInstallationId'),'toInstallationId':installation,
+            'revision':parent['revision'],'checkpointHeadsSHA256':request['parentCheckpointSHA256'],
+            'scope':SCOPE,'taskStatePreserved':parent['state']}

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

@@ -0,0 +1,84 @@
+"""Portable task results and declared evidence; never exports native reasoning/history."""
+import hashlib,json,pathlib,tempfile,mimetypes
+from .storage import atomic_json,read_json,canonical,PackError,safe_id
+from .work import require
+
+def client_default():
+    from .topolo import Client
+    return Client('production','org:org_topolo_platform')
+
+def publish(root,task_id,label,data,content_type='application/json',client=None):
+    safe_id(task_id)
+    root=pathlib.Path(root);authority=read_json(root/'context-authority.json',{})
+    require(authority.get('format')=='topolo-task-context-authority-v1' and authority.get('organizationId')=='org_topolo_platform' and authority.get('scope')=='org' and authority.get('workspaceId'),'Cloud artifact authority is missing')
+    require(isinstance(data,bytes) and 0<len(data)<=100*1024*1024 and all(c.isalnum() or c in '-_.' for c in label),'Invalid declared artifact')
+    digest=hashlib.sha256(data).hexdigest();directory=root/'artifact-uploads'/task_id;directory.mkdir(parents=True,exist_ok=True,mode=0o700)
+    name=label+'-'+digest[:16];file=directory/name;receipt=directory/(name+'.receipt.json');prior=read_json(receipt,{})
+    client=client or client_default()
+    if prior:
+        require(prior.get('sha256')==digest and prior.get('state') in {'uploaded','verified'},'Artifact upload is uncertain; reconcile before retrying')
+        key=prior['key']
+    else:
+        require(not file.exists(),'Artifact source exists without an upload receipt; reconcile first')
+        file.write_bytes(data);file.chmod(0o600);atomic_json(receipt,{'state':'prepared','sha256':digest})
+        result=client.action('app_topolo_bytes.files.upload_url.create',{'key':'task-results/'+task_id+'/'+name,'type':content_type,'size':len(data),'scope':authority['scope']},authority['workspaceId'],write=True,upload=file)
+        key=result.get('key') or result.get('session',{}).get('key');require(isinstance(key,str) and key,'Artifact upload key is unconfirmed; reconcile before retrying')
+        atomic_json(receipt,{'state':'uploaded','sha256':digest,'key':key})
+    from .topolo import read_artifact
+    ref=read_artifact(client,{'input':{'bytesScope':authority['scope'],'bytesWorkspaceId':authority['workspaceId']}},key)
+    require(ref['sha256']==digest,'Cloud artifact differs from declared output')
+    atomic_json(receipt,{'state':'verified','sha256':digest,'key':key,'artifact':ref});return ref
+
+def declared_files(worker,values):
+    require(isinstance(values,list) and len(values)<=16,'Declare at most sixteen evidence files')
+    cwd=pathlib.Path(worker['cwd']).resolve();paths=[]
+    for value in values:
+        require(isinstance(value,str),'Evidence path must be a string')
+        path=pathlib.Path(value)
+        require(path.is_absolute() and '..' not in path.parts and path.is_file() and not path.is_symlink() and path.resolve().is_relative_to(cwd) and not any(p.is_symlink() for p in path.parents if p!=cwd.parent),'Evidence must be a regular file in this worker workspace')
+        require(0<path.stat().st_size<=100*1024*1024,'Declared evidence exceeds upload boundary');paths.append(path)
+    return paths
+
+def checkpoint(root,task,worker,actual,client=None):
+    text='\n'.join(i.get('text','') for i in actual.get('items',[]) if i.get('type')=='agentMessage' and i.get('phase')!='commentary')
+    require(len(text.encode())<=100000,'Worker output exceeds bounded checkpoint')
+    normalized=None;error=None
+    if worker['phase'] in {'execute','review'} and actual['status']=='completed':
+        try:
+            raw=text.strip()
+            if raw.startswith('```'):raw=raw.split('\n',1)[1].rsplit('```',1)[0]
+            output=json.loads(raw)
+            if worker['phase']=='execute':
+                require(set(output)=={'summary','artifacts','references'} and isinstance(output['summary'],str) and isinstance(output['references'],list) and len(output['references'])<=32 and all(isinstance(r,str) and len(r)<=2000 for r in output['references']),'Invalid portable worker result contract')
+                paths=declared_files(worker,output['artifacts'])
+            else:
+                require(set(output)=={'verdict','summary','evidence'} and output['verdict'] in {'completed','needs_input','blocked'} and isinstance(output['summary'],str),'Invalid independent review contract')
+                paths=declared_files(worker,output['evidence']);require(output['verdict']!='completed' or bool(paths),'Completion requires inspected evidence')
+        except (PackError,ValueError,TypeError,KeyError) as exc:error=str(exc)
+        else:
+            refs=[{'title':path.name,'artifact':publish(root,task['id'],worker['id']+'-evidence-'+str(n),path.read_bytes(),mimetypes.guess_type(path.name)[0] or 'application/octet-stream',client)} for n,path in enumerate(paths)]
+            normalized={**output,('artifacts' if worker['phase']=='execute' else 'evidence'):refs}
+    payload={'format':'topolo-task-checkpoint-v1','taskId':task['id'],'workerId':worker['id'],'phase':worker['phase'],'nativeReceipt':{'threadId':worker['nativeId'],'turnId':actual['id'],'status':actual['status'],'toolItems':sum(i.get('type') not in {'agentMessage','userMessage','reasoning','plan'} for i in actual.get('items',[]))},'resolution':worker['resolution'],'roleSource':worker.get('roleSource'),'contextRef':task.get('contextRef'),'output':canonical(normalized).decode() if normalized is not None else text,'outputError':error,'nativeHistoryIncluded':False}
+    if actual.get('nativeProof'):
+        payload['nativeReceipt']['producer']=actual['nativeProof']
+    data=canonical(payload);ref=publish(root,task['id'],worker['id']+'-checkpoint',data,client=client)
+    return {'artifact':ref,'sha256':ref['sha256']},payload,normalized
+
+def read_checkpoint(root,proof,task_id,worker_id=None,client=None):
+    from .topolo import read_artifact
+    ref=proof['artifact'];require(proof['sha256']==ref['sha256'] and 0<ref['size']<=200000,'Checkpoint digest or size binding differs');client=client or client_default()
+    with tempfile.TemporaryDirectory(prefix='topolo-one-checkpoint-') as tmp:
+        file=pathlib.Path(tmp)/'checkpoint.json';read_artifact(client,{'input':{'bytesScope':ref['scope'],'bytesWorkspaceId':ref['workspaceId']}},ref['key'],ref,file);payload=json.loads(file.read_text())
+    require(set(payload)=={'format','taskId','workerId','phase','nativeReceipt','resolution','roleSource','contextRef','output','outputError','nativeHistoryIncluded'} and payload.get('format')=='topolo-task-checkpoint-v1' and payload.get('taskId')==task_id and (worker_id is None or payload.get('workerId')==worker_id) and payload.get('nativeHistoryIncluded') is False,'Cloud checkpoint identity differs')
+    return payload
+
+def materialize_result(root,task,cwd,client=None):
+    from .topolo import read_artifact
+    result=task.get('result',{});payload=read_checkpoint(root,result['checkpoint'],task['id'],result['workerId'],client)
+    require(payload['phase']=='execute' and payload['outputError'] is None,'Worker checkpoint is not a qualified result')
+    output=json.loads(payload['output']);require(output=={k:result[k] for k in ['summary','artifacts','references']},'Task result differs from the immutable worker checkpoint')
+    target=pathlib.Path(cwd)/'context';target.mkdir(exist_ok=True);atomic_json(target/'worker-result.json',payload)
+    evidence=target/'evidence';evidence.mkdir(exist_ok=True);mapping=[];client=client or client_default()
+    for n,row in enumerate(result.get('artifacts',[])):
+        ref=row['artifact'];path=evidence/str(n);read_artifact(client,{'input':{'bytesScope':ref['scope'],'bytesWorkspaceId':ref['workspaceId']}},ref['key'],ref,path);mapping.append({'title':row['title'],'path':str(path),'artifact':ref})
+    atomic_json(target/'result-source.json',{'checkpoint':result['checkpoint'],'evidence':mapping})