@topolo/cli 0.13.8 → 0.13.10

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

@@ -0,0 +1,749 @@
+"""Bounded dynamic-lane intent and durable, fenced lifecycle records.
+
+Native creation belongs to the host. A creation receipt is independently read
+back before adoption; a registry entry is never a permission or execution ACK.
+"""
+import copy
+import fcntl
+import hashlib
+import os
+import pathlib
+import stat
+from contextlib import contextmanager
+
+from .storage import PackError, atomic_json, canonical, read_json, safe_id
+from . import task_models
+
+
+STATES = {'planned', 'adopted-unconfigured', 'configured-settings-ACK', 'loaded-context-ACK',
+          'permission-request-pending', 'permission-decision-forwarded', 'executed-outcome-verified',
+          'settled', 'retired', 'uncertain-effect-hold'}
+IDENTITY_FIELDS = ('packId', 'packRevision', 'contextKey', 'organizationId', 'environment', 'installationId')
+ROLE_FIELDS = {'key', 'harness', 'nativeId', 'cwd', 'contextDigest', 'settings',
+               'AgentLogicalId', 'AgentVersionId', 'AgentWorkspaceId', 'BytesWorkspaceId',
+               'privateMCPDescriptorHash', *IDENTITY_FIELDS}
+
+
+def digest(value):
+    return hashlib.sha256(canonical(value)).hexdigest()
+
+
+def _identity(value, label):
+    if not isinstance(value, str) or not value or len(value) > 256 or any(ord(c) < 32 for c in value):
+        raise PackError('Missing or invalid exact ' + label)
+    return value
+
+
+def _role(value, harness):
+    if not isinstance(value, dict) or set(value) != ROLE_FIELDS or value['harness'] != harness:
+        raise PackError('Current owned role descriptor is missing or unsupported')
+    for key in ROLE_FIELDS - {'settings'}:
+        _identity(value[key], key)
+    if not pathlib.Path(value['cwd']).is_absolute() or not isinstance(value['settings'], dict):
+        raise PackError('Role workspace and settings are unqualified')
+    settings = value['settings']
+    expected = ({'model', 'model_reasoning_effort', 'approval_policy', 'approvals_reviewer',
+                 'sandbox_mode', 'sandbox_workspace_write', 'apps'} if harness == 'codex'
+                else {'model', 'effortLevel', 'permissions'})
+    if set(settings) != expected:
+        raise PackError('Role settings contain unsupported or credential-bearing fields')
+
+
+def plan(request, role, intake, resolution, ceiling):
+    if (not isinstance(request, dict) or not {'laneId','logicalOriginThreadId','sourceRoleKey','task'}<=set(request) or
+            set(request)-{'laneId','logicalOriginThreadId','sourceRoleKey','task','verificationProfile'}):
+        raise PackError('Dynamic lane request has unsupported fields')
+    if request.get('verificationProfile') not in {None,'manual'}:
+        raise PackError('Only a separately bound narrower manual verification profile is supported')
+    safe_id(request['laneId']); _identity(request['logicalOriginThreadId'], 'logical origin')
+    harness = resolution['harness']; _role(role, harness); _role(intake, harness)
+    if request['sourceRoleKey'] != role['key'] or '/intakes/' not in intake['key']:
+        raise PackError('Dynamic lane has no exact source role and original intake')
+    if any(role[key] != intake[key] for key in IDENTITY_FIELDS):
+        raise PackError('Dynamic lane intake is outside the role pack, installation or organization context')
+    if resolution['task'] != request['task'] or resolution.get('nativeACK') is not None:
+        raise PackError('Dynamic task resolution does not match the creation request')
+    if (not isinstance(ceiling, dict) or set(ceiling) != {'policyRevision', 'policyDigest', 'profile', 'intakeKey'} or
+            ceiling['intakeKey'] != intake['key']):
+        raise PackError('Dynamic lane has no exact current policy ceiling and intake route')
+    for key in ['policyRevision', 'policyDigest', 'profile']:
+        _identity(ceiling[key], key)
+    return {'format': 'topolo-dynamic-lane-plan', 'schemaVersion': 1,
+            'laneId': request['laneId'], 'harness': harness,
+            'logicalOriginThreadId': request['logicalOriginThreadId'],
+            'role': copy.deepcopy(role), 'intake': copy.deepcopy(intake),
+            'resolution': copy.deepcopy(resolution), 'ceiling': copy.deepcopy(ceiling),
+            'verificationProfile': request.get('verificationProfile'),
+            'verificationProfileAuthority': 'Backlog bound two-fresh-worker verification only' if request.get('verificationProfile') else None,
+            'nativeParentId': intake['nativeId'] if harness == 'claude' else None,
+            'nativeParentAvailability': 'actual-harness-intake' if harness == 'claude' else 'UNAVAILABLE',
+            'state': 'planned', 'executionAuthorized': False}
+
+
+def adopt(planned, receipt, native, current):
+    """Adopt one actual created identity after current source/native readback.
+
+    ``current`` is collected by the owned connection, never trusted from the
+    caller's receipt. Codex logical origin is deliberately not native ancestry.
+    """
+    if current != {'role': planned['role'], 'intake': planned['intake'], 'ceiling': planned['ceiling']}:
+        raise PackError('Role context, intake, installation or policy changed before adoption')
+    fields = {'format', 'schemaVersion', 'state', 'planDigest', 'harness', 'nativeId',
+              'logicalOriginThreadId', 'cwd', 'model', 'effort', 'nativeParentId', 'fresh', 'creationSource'}
+    if (not isinstance(receipt, dict) or set(receipt) != fields or
+            receipt['format'] != 'topolo-native-lane-created' or receipt['schemaVersion'] != 1 or
+            receipt['state'] != 'ready' or receipt['creationSource'] != 'supported-native-host-tool' or
+            receipt['fresh'] is not True or receipt['planDigest'] != digest(planned) or
+            receipt['harness'] != planned['harness'] or
+            receipt['logicalOriginThreadId'] != planned['logicalOriginThreadId']):
+        raise PackError('Created native identity has no matching fresh host receipt')
+    _identity(receipt['nativeId'], 'created native identity')
+    if receipt['nativeId'] in {planned['role']['nativeId'], planned['intake']['nativeId']}:
+        raise PackError('A dynamic lane cannot adopt its source role or intake')
+    expected = {'nativeId': receipt['nativeId'], 'cwd': receipt['cwd'], 'nativeParentId': planned['nativeParentId']}
+    if (not isinstance(native, dict) or any(native.get(k) != v for k, v in expected.items()) or
+            receipt['nativeParentId'] != planned['nativeParentId'] or
+            any(k in native and native[k] != receipt[k] for k in ['model','effort']) or native.get('archived') is not False or
+            native.get('backend') != 'local' or native.get('foreignWorkspace') is not False):
+        raise PackError('Actual native child ownership or parent descriptor does not match')
+    if planned['harness']=='claude':
+        _identity(native.get('title'),'actual child title')
+    if not pathlib.Path(receipt['cwd']).is_absolute():
+        raise PackError('Created lane requires its exact absolute owned workspace')
+    return {'format': 'topolo-dynamic-lane', 'schemaVersion': 1,
+            'laneId': planned['laneId'], 'harness': planned['harness'], 'nativeId': receipt['nativeId'],
+            'plan': copy.deepcopy(planned), 'planDigest': digest(planned),
+            'creationReceipt': copy.deepcopy(receipt), 'creationReceiptDigest': digest(receipt),
+            'nativeTitle': native.get('title'),
+            'frontendVisibility': 'UNVERIFIED_MANAGED_APP_READ_REQUIRED' if planned['harness']=='codex' else 'native-manager-read-verified',
+            'state': 'adopted-unconfigured', 'nativeSettingsACK': None, 'contextACK': None,
+            'permissionRequest': None, 'permissionDecision': None, 'outcome': None,
+            'nativeConnectionGeneration': None, 'executionAuthorized': False}
+
+
+def acknowledge_settings(record, native, resolution, generation):
+    if record['state'] != 'adopted-unconfigured' or resolution['nativeACK'] != native:
+        raise PackError('Dynamic lane settings need their exact native model and effort ACK')
+    if ({**resolution, 'nativeACK': None} != record['plan']['resolution'] or
+            native != record['plan']['resolution']['resolved']):
+        raise PackError('Dynamic lane model choice changed after creation planning')
+    _identity(generation, 'native connection generation')
+    return {**copy.deepcopy(record), 'state': 'configured-settings-ACK',
+            'nativeSettingsACK': copy.deepcopy(native), 'nativeConnectionGeneration': generation}
+
+
+def acknowledge_context(record, context_digest):
+    if record['state'] != 'configured-settings-ACK' or context_digest != record['plan']['role']['contextDigest']:
+        raise PackError('Dynamic lane needs actual loaded role context acknowledgement')
+    return {**copy.deepcopy(record), 'state': 'loaded-context-ACK', 'contextACK': context_digest}
+
+
+def request_permission(record, request_fingerprint, request_id, generation):
+    if record['state'] != 'loaded-context-ACK' or generation != record['nativeConnectionGeneration']:
+        raise PackError('Dynamic permission request has no current configured connection')
+    _identity(request_fingerprint, 'native request fingerprint'); _identity(request_id, 'native request identity')
+    return {**copy.deepcopy(record), 'state': 'permission-request-pending',
+            'permissionRequest': {'fingerprint': request_fingerprint, 'requestId': request_id,
+                                  'generation': generation, 'intakeKey': record['plan']['intake']['key']}}
+
+
+def record_decision(record, decision, intake_key, fingerprint, generation):
+    request = record.get('permissionRequest')
+    if (record['state'] != 'permission-request-pending' or not request or
+            intake_key != request['intakeKey'] or fingerprint != request['fingerprint'] or
+            generation != request['generation'] or decision not in {'approved', 'denied'}):
+        raise PackError('Dynamic permission decision differs from the original intake request')
+    return {**copy.deepcopy(record), 'state': 'permission-decision-forwarded',
+            'permissionDecision': decision, 'executionAuthorized': decision == 'approved'}
+
+
+def record_outcome(record, native_outcome):
+    if (record['state'] != 'permission-decision-forwarded' or not isinstance(native_outcome, dict) or
+            set(native_outcome) != {'nativeId', 'requestFingerprint', 'state', 'verificationDigest'} or
+            native_outcome['nativeId'] != record['nativeId'] or
+            native_outcome['requestFingerprint'] != record['permissionRequest']['fingerprint'] or
+            native_outcome['state'] not in {'completed', 'denied', 'failed'} or
+            (record['permissionDecision'] == 'denied' and native_outcome['state'] != 'denied')):
+        raise PackError('Forwarded approval is not an attributable native operation outcome')
+    _identity(native_outcome['verificationDigest'], 'operation verification digest')
+    return {**copy.deepcopy(record), 'state': 'executed-outcome-verified',
+            'outcome': copy.deepcopy(native_outcome), 'executionAuthorized': False}
+
+
+def settle(record, native):
+    if (record['state'] != 'executed-outcome-verified' or not isinstance(native, dict) or native.get('nativeId') != record['nativeId'] or
+            native.get('busy') is not False or native.get('pendingApprovals') != 0):
+        raise PackError('Dynamic lane has active work or pending native approval')
+    return {**copy.deepcopy(record), 'state': 'settled', 'executionAuthorized': False}
+
+
+def retire(record, native):
+    if (record['state'] != 'settled' or not isinstance(native, dict) or native.get('nativeId') != record['nativeId'] or
+            native.get('busy') is not False or native.get('pendingApprovals') != 0 or
+            native.get('archived') is not True or native.get('historyPreserved') is not True):
+        raise PackError('Only the settled own lane with actual preserved-history archive ACK may retire')
+    return {**copy.deepcopy(record), 'state': 'retired', 'executionAuthorized': False}
+
+
+def execution_role(record):
+    """A gate row, retaining the source role key instead of inventing a new grant."""
+    if record['state'] not in {'adopted-unconfigured', 'configured-settings-ACK', 'loaded-context-ACK', 'permission-request-pending',
+                                'permission-decision-forwarded', 'executed-outcome-verified', 'settled'}:
+        raise PackError('Dynamic lane is not configured on a qualified native connection')
+    plan = record['plan']; source = plan['role']; settings = copy.deepcopy(source['settings'])
+    choice = record['nativeSettingsACK'] or (plan['resolution']['resolved'] if record['state'] == 'adopted-unconfigured' else None)
+    if not choice or choice != plan['resolution']['resolved']:
+        raise PackError('Dynamic native settings have no exact model resolution acknowledgement')
+    if plan.get('verificationProfile')=='manual':
+        from . import permissions
+        agent={'pack':source['packId'],'set':source['key'].split('/')[1],'id':source['key'].split('/')[2]}
+        settings=permissions.apply_settings(agent,record['harness'],settings,
+            {'profile':'manual','overrides':{},'intakeRoutes':{source['key']:plan['intake']['key']}})
+    settings['model'] = choice['model']
+    settings['model_reasoning_effort' if record['harness'] == 'codex' else 'effortLevel'] = choice['effort']
+    return {'key': source['key'] + '/dynamic/' + record['laneId'], 'threadId': record['nativeId'],
+            'sourceRoleKey': source['key'], 'sourceRevision': source['packRevision'],
+            'sourceRoleNativeId': source['nativeId'], 'dynamicIntakeNativeId': plan['intake']['nativeId'],
+            'cwd': record['creationReceipt']['cwd'], 'intakeKey': plan['intake']['key'],
+            'contextKey': source['contextKey'], 'installationConsent': None,
+            'settings': settings, 'dynamicLaneId': record['laneId'],
+            'dynamicPlanDigest': record['planDigest'], 'dynamicContextDigest': source['contextDigest'],
+            'dynamicConnectionGeneration': record['nativeConnectionGeneration'],
+            'dynamicModelResolution': copy.deepcopy(plan['resolution']), 'dynamicVerificationProfile': plan.get('verificationProfile'), 'dynamicCeiling': copy.deepcopy(plan['ceiling'])}
+
+
+class Registry:
+    def __init__(self, root, harness):
+        if harness not in {'codex', 'claude'}:
+            raise PackError('Unsupported native lane harness')
+        self.root = pathlib.Path(root); self.harness = harness
+        self.directory = self.root / 'dynamic-lanes' / harness
+
+    def save_plan(self, planned):
+        lane_id=planned['laneId']
+        if planned.get('format')!='topolo-dynamic-lane-plan' or planned.get('harness')!=self.harness:
+            raise PackError('Unqualified native lane plan')
+        with self.mutation():
+            directory=self.directory/'plans'
+            if not directory.exists():
+                directory.mkdir(mode=0o700)
+            self._owned(directory,True)
+            path=directory/(safe_id(lane_id)+'.json')
+            # A plan is a one-use immutable native snapshot, never a caller assertion.
+            fd=os.open(path,os.O_WRONLY|os.O_CREAT|os.O_EXCL|os.O_NOFOLLOW,0o600)
+            with os.fdopen(fd,'wb') as stream:
+                stream.write(canonical(planned)+b'\n');stream.flush();os.fsync(stream.fileno())
+        return copy.deepcopy(planned)
+
+    def read_plan(self, lane_id):
+        directory=self.directory/'plans';self._owned(directory,True)
+        path=directory/(safe_id(lane_id)+'.json');self._owned(path)
+        if path.stat().st_size>131072:
+            raise PackError('Native lane plan exceeds its schema bound')
+        return read_json(path)
+
+    def path(self, lane_id):
+        return self.directory / (safe_id(lane_id) + '.json')
+
+    def _owned(self, path, directory=False):
+        info = path.lstat()
+        if (stat.S_ISLNK(info.st_mode) or info.st_uid != os.getuid() or
+                (not directory and (not stat.S_ISREG(info.st_mode) or info.st_nlink != 1)) or
+                (directory and not stat.S_ISDIR(info.st_mode))):
+            raise PackError('Dynamic registry requires regular exclusively owned paths')
+
+    def read(self, lane_id):
+        path = self.path(lane_id)
+        if not path.exists():
+            if path.is_symlink():
+                raise PackError('Dynamic registry refuses a symlink')
+            return None
+        self._owned(self.root, True); self._owned(self.directory.parent, True); self._owned(self.directory, True)
+        self._owned(path)
+        if path.stat().st_size > 131072:
+            raise PackError('Dynamic lane record exceeds its bounded schema')
+        record = read_json(path)
+        if (record.get('format') != 'topolo-dynamic-lane' or record.get('schemaVersion') != 1 or
+                record.get('laneId') != lane_id or record.get('harness') != self.harness or
+                record.get('state') not in STATES or
+                digest(record.get('plan')) != record.get('planDigest') or
+                digest(record.get('creationReceipt')) != record.get('creationReceiptDigest')):
+            raise PackError('Dynamic registry identity or lifecycle schema differs')
+        return record
+
+    def records(self):
+        if not self.directory.exists():
+            return []
+        self._owned(self.directory, True)
+        return [self.read(p.stem) for p in sorted(self.directory.glob('*.json'))]
+
+    @contextmanager
+    def mutation(self):
+        self._owned(self.root, True)
+        for path in [self.directory.parent, self.directory]:
+            if not path.exists():
+                path.mkdir(mode=0o700)
+            self._owned(path, True)
+        path = self.directory / 'registry.lock'
+        fd = os.open(path, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+        try:
+            self._owned(path)
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            yield
+        except BlockingIOError as exc:
+            raise PackError('An owned dynamic registry writer is already active') from exc
+        finally:
+            fcntl.flock(fd, fcntl.LOCK_UN); os.close(fd)
+
+    def write(self, record, before_digest):
+        lane_id = record['laneId']
+        if (record.get('format') != 'topolo-dynamic-lane' or record.get('schemaVersion') != 1 or
+                record['harness'] != self.harness or record['state'] not in STATES or
+                digest(record['plan']) != record['planDigest'] or
+                digest(record['creationReceipt']) != record['creationReceiptDigest']):
+            raise PackError('Cannot write an unqualified dynamic lifecycle identity')
+        with self.mutation():
+            current = self.read(lane_id)
+            actual = digest(current) if current is not None else None
+            if actual != before_digest:
+                raise PackError('Dynamic lane beforeimage changed; no overwrite or replay')
+            others = [row for row in self.records() if row['laneId'] != lane_id]
+            if any(row['nativeId'] == record['nativeId'] for row in others):
+                raise PackError('Native identity is already registered to a different dynamic lane')
+            if current and (current['nativeId'] != record['nativeId'] or current['planDigest'] != record['planDigest']):
+                raise PackError('Dynamic registration conflicts with its durable owned identity')
+            atomic_json(self.path(lane_id), record)
+            if self.read(lane_id) != record:
+                raise PackError('Dynamic registry write acknowledgement differs; reconcile without replay')
+        return copy.deepcopy(record)
+
+
+class ClaudeLifecycle:
+    """Typed helper for one new native child; no host effects or cached grants."""
+    def __init__(self,lib,pack,policy_path):
+        self.lib=lib;self.pack=safe_id(pack);self.policy_path=pathlib.Path(policy_path)
+        self.store=Registry(lib.root,'claude')
+
+    def current(self,source_key,models):
+        from . import permissions,topolo
+        for path in [self.lib.root/'claude/state.json',self.policy_path]:self.store._owned(path)
+        state=read_json(self.lib.root/'claude/state.json');policy=read_json(self.policy_path)
+        manifest,revision=self.lib.load(self.pack);consent=permissions.load(self.lib,self.pack,manifest['agents'])
+        if (state.get('harness')!='claude' or policy.get('format')!='topolo-agent-execution-policy' or
+                policy.get('pack')!=self.pack or policy.get('sourceRevision')!=revision or
+                not consent or policy.get('installationConsent')!=consent):
+            raise PackError('Current adopted Claude source and installation policy differ')
+        intake_key=consent['intakeRoutes'].get(source_key)
+        if not intake_key or '/intakes/' not in intake_key:
+            raise PackError('Original same-context intake is unavailable')
+        remote,proof=topolo.organization_execution_policy(topolo.Client(consent['environment'],consent['contextKey']),
+            consent,manifest['agents'],consent.get('agentWorkspaceId'))
+        permissions.authorize_native_scope(proof)
+        self._manual_profile_allowed='manual' in remote['allowedProfiles']
+        binding_file=topolo.binding_path(self.lib,self.pack,consent['environment'],consent['contextKey']);self.store._owned(binding_file)
+        binding=read_json(binding_file)
+        def role(key):
+            rows=[r for r in state['agents'] if r['key']==key and r['pack']==self.pack and r['sourceRevision']==revision and r['importState']=='desktop-adopted']
+            entries=[r for r in policy['agents'] if r['key']==key]
+            if len(rows)!=1 or len(entries)!=1:
+                raise PackError('Exact currently adopted source role missing')
+            row=rows[0];cwd=pathlib.Path(row['workspace'])
+            if not cwd.resolve().is_relative_to((self.lib.root/'claude/workspaces'/self.pack).resolve()):
+                raise PackError('Role context is outside the owned pack')
+            files=[cwd/'CLAUDE.md',cwd/'topolo-connection.json',cwd/'.mcp.json']
+            for file in files:self.store._owned(file)
+            hashes={str(f):hashlib.sha256(f.read_bytes()).hexdigest() for f in files}
+            descriptor=read_json(files[1]);logical='/'.join(key.split('/')[1:]);refs=[r for r in binding['input']['roles'] if r['logicalId']==logical]
+            if len(refs)!=1:
+                raise PackError('Source Agent role has no unique connection')
+            expected={'harness':'claude','pack':self.pack,'packRevision':revision,'role':logical,'nativeThreadId':row['desktopSessionId'],
+                'environment':consent['environment'],'contextKey':consent['contextKey'],'instanceId':binding['input']['instanceId'],
+                'agentId':refs[0]['agentId'],'agentVersionId':refs[0]['agentVersionId'],'agentWorkspaceId':binding['agentWorkspaceId'],
+                'bytesWorkspaceId':binding['input']['bytesWorkspaceId'],'identity':binding['identity']}
+            if any(descriptor.get(k)!=v for k,v in expected.items()) or binding['identity']['organizationId']!=consent['contextKey'][4:]:
+                raise PackError('Current Agent/Bytes/organization/native role descriptor differs')
+            return {'key':key,'harness':'claude','nativeId':row['desktopSessionId'],'cwd':str(cwd),
+                'contextDigest':digest(hashes),'settings':entries[0]['harnesses']['claude']['nativeSettings'],
+                'AgentLogicalId':refs[0]['agentId'],'AgentVersionId':refs[0]['agentVersionId'],'AgentWorkspaceId':binding['agentWorkspaceId'],
+                'BytesWorkspaceId':binding['input']['bytesWorkspaceId'],'privateMCPDescriptorHash':hashes[str(files[2])],
+                'packId':self.pack,'packRevision':revision,'contextKey':consent['contextKey'],'organizationId':binding['identity']['organizationId'],
+                'environment':consent['environment'],'installationId':binding['input']['instanceId']}
+        source=role(source_key);intake=role(intake_key)
+        config_path=self.lib.root/'dynamic-models'/(self.pack+'.json');self.store._owned(config_path);config=read_json(config_path)
+        if (set(config)!={'format','schemaVersion','sourceRevision','configuration','constraints','authorizedOverrides'} or
+                config['format']!='topolo-pack-dynamic-models' or config['schemaVersion']!=1 or config['sourceRevision']!=revision):
+            raise PackError('Explicit current versioned pack task-model configuration required')
+        constraints=task_models.role_constraints(config['constraints'],source_key)
+        ceiling={'policyRevision':proof['revision'],'policyDigest':proof['policyDigest'],
+            'profile':consent.get('overrides',{}).get(source_key,consent['profile']),'intakeKey':intake_key}
+        return {'role':source,'intake':intake,'ceiling':ceiling},config,constraints
+
+    def qualified(self,record,models):
+        current,config,constraints=self.current(record['plan']['role']['key'],models)
+        if record['plan'].get('verificationProfile')=='manual' and not self._manual_profile_allowed:
+            raise PackError('Fresh organization policy prohibits the narrower child-only manual test profile')
+        task=record['plan']['resolution']['task']
+        choice=task_models.resolve_intent(config['configuration'],task,'claude',models,constraints,
+            override_authorized=digest(task) in config['authorizedOverrides'])
+        if current!={k:record['plan'][k] for k in ['role','intake','ceiling']} or choice!=record['plan']['resolution']:
+            raise PackError('Dynamic task/source/intake/configuration/native model observation is stale')
+        return current,config,constraints
+
+    def prepare(self,request,models,native_ids):
+        if not isinstance(native_ids,list) or len(native_ids)>1000 or len(set(native_ids))!=len(native_ids):
+            raise PackError('Exact native ID-only precreation inventory required')
+        current,config,constraints=self.current(request['sourceRoleKey'],models)
+        choice=task_models.resolve_intent(config['configuration'],request['task'],'claude',models,constraints,
+            override_authorized=digest(request['task']) in config['authorizedOverrides'])
+        if request.get('verificationProfile')=='manual' and not self._manual_profile_allowed:
+            raise PackError('Fresh organization policy does not allow the bound manual verification profile')
+        if any(r['nativeId'] not in native_ids for r in [current['role'],current['intake']]):
+            raise PackError('Source role and intake are not in the actual native precreation inventory')
+        planned=plan(request,current['role'],current['intake'],choice,current['ceiling'])
+        planned['nativeIdsBeforeCreation']=sorted(native_ids)
+        return self.store.save_plan(planned)
+
+    def adopt(self,planned,receipt,native,models):
+        if self.store.read_plan(planned['laneId'])!=planned or receipt['nativeId'] in planned['nativeIdsBeforeCreation']:
+            raise PackError('Fresh host creation differs from the immutable owned native snapshot')
+        if receipt['cwd']!=planned['role']['cwd'] or native.get('busy') is not False or native.get('pendingApprovals')!=0:
+            raise PackError('Fresh child is outside its reviewed role workspace or not idle')
+        current,_,_=self.qualified({'plan':planned},models)
+        return self.store.write(adopt(planned,receipt,native,current),None)
+
+    def creation(self,lane_id,models,begin=False,generation=None,native_id=None):
+        planned=self.store.read_plan(lane_id)
+        self.qualified({'plan':planned},models)
+        with self.store.mutation():
+            directory=self.store.directory/'creation'
+            if not directory.exists():
+                directory.mkdir(mode=0o700)
+            self.store._owned(directory,True)
+            path=directory/(safe_id(lane_id)+'.json')
+            if begin:
+                if self.store.read(lane_id) or path.exists() or path.is_symlink():
+                    raise PackError('Native creation is already reserved; reconcile without replay')
+                _identity(generation,'creation generation')
+                record={'format':'topolo-owned-native-creation','schemaVersion':1,'laneId':lane_id,
+                    'planDigest':digest(planned),'generation':generation,'state':'may-have-effects','nativeId':None}
+                fd=os.open(path,os.O_WRONLY|os.O_CREAT|os.O_EXCL|os.O_NOFOLLOW,0o600)
+                with os.fdopen(fd,'wb') as stream:
+                    stream.write(canonical(record)+b'\n');stream.flush();os.fsync(stream.fileno())
+            else:
+                self.store._owned(path)
+                record=read_json(path)
+                if (set(record)!={'format','schemaVersion','laneId','planDigest','generation','state','nativeId'} or
+                        record['format']!='topolo-owned-native-creation' or record['schemaVersion']!=1 or
+                        record['laneId']!=lane_id or record['planDigest']!=digest(planned) or
+                        record['state'] not in {'may-have-effects','created-initializing'}):
+                    raise PackError('Exact own native creation marker differs')
+                if native_id is not None:
+                    _identity(native_id,'actual created native identity')
+                    if (record['state']!='may-have-effects' or record['nativeId'] is not None or
+                            generation!=record['generation'] or native_id in planned['nativeIdsBeforeCreation']):
+                        raise PackError('Native creation identity/generation conflicts; no replay')
+                    record={**record,'state':'created-initializing','nativeId':native_id}
+                    atomic_json(path,record)
+                if read_json(path)!=record:
+                    raise PackError('Native creation marker readback differs')
+        return {'plan':planned,'creation':record}
+
+    def configuration_begin(self,lane_id,models,generation):
+        record=self.store.read(lane_id)
+        if not record or record['state']!='adopted-unconfigured':
+            raise PackError('Fresh adopted child required; no retry after possible effects')
+        self.qualified(record,models)
+        hold={**record,'state':'uncertain-effect-hold','configurationGeneration':generation}
+        self.store.write(hold,digest(record))
+        return {'record':record,'holdDigest':digest(hold),'generation':generation}
+
+    def configuration_ack(self,operation,models,native):
+        record=operation['record'];held=self.store.read(record['laneId'])
+        if digest(held)!=operation['holdDigest'] or held.get('configurationGeneration')!=operation['generation']:
+            raise PackError('Child settings effect owner/beforeimage differs')
+        _,config,constraints=self.qualified(record,models)
+        if native.get('nativeId')!=record['nativeId'] or native.get('settingsACK') is not True or native.get('busy') is not False:
+            raise PackError('Actual idle native child settings ACK is missing')
+        expected_mode='default' if record['plan'].get('verificationProfile')=='manual' else record['plan']['role']['settings']['permissions']['defaultMode']
+        if native.get('permissionMode')!=expected_mode:
+            raise PackError('Actual child native permission mode differs from the bound intent')
+        actual={'model':native['model'],'effort':native['effort']}
+        resolution=task_models.acknowledge(record['plan']['resolution'],actual,configuration=config['configuration'],catalog=models,constraints=constraints)
+        updated=acknowledge_settings(record,actual,resolution,operation['generation'])
+        updated['nativeProcessSettingsProof']={'generation':operation['generation'],'model':native['model'],'effort':native['effort'],
+            'classification':'exact live child process tuple; not a general effort capability catalogue'}
+        return self.store.write(updated,digest(held))
+
+    def context_prepare(self,lane_id,nonce,models):
+        import uuid
+        if str(uuid.UUID(nonce))!=nonce:
+            raise PackError('Exact context probe UUID required')
+        record=self.store.read(lane_id)
+        if not record or record['state']!='configured-settings-ACK' or record.get('contextProbe'):
+            raise PackError('Context probe requires a current configured child and one fresh operation')
+        self.qualified(record,models);source=record['plan']['role'];cwd=pathlib.Path(source['cwd'])
+        files=[cwd/'CLAUDE.md',cwd/'topolo-connection.json'];hashes={str(p):hashlib.sha256(p.read_bytes()).hexdigest() for p in files}
+        expected={'operationId':nonce,'nativeId':record['nativeId'],'AgentLogicalId':source['AgentLogicalId'],
+            'AgentVersionId':source['AgentVersionId'],'AgentWorkspaceId':source['AgentWorkspaceId'],'BytesWorkspaceId':source['BytesWorkspaceId']}
+        text=('Topolo bounded context bootstrap '+nonce+'. Read only your own '+str(files[0])+' and '+str(files[1])+'. '
+              'Use the Read tool on each file. Load the role charter and current connected Agent/Bytes identity. '
+              'Do not read credentials, MCP configuration, other sessions or business records. Do not write or run commands. '
+              'Return one JSON object with exactly operationId, nativeId, AgentLogicalId, AgentVersionId, AgentWorkspaceId, BytesWorkspaceId. '
+              'operationId is '+nonce+'; nativeId is '+record['nativeId']+'. Obtain the four identity references from the actual connection file. '
+              'Do not start assigned task work until this context acknowledgement has been checked through the original intake.')
+        probe={'operationId':nonce,'state':'prepared','expected':expected,'fileHashes':hashes,'text':text,'generation':record['nativeConnectionGeneration']}
+        updated={**record,'contextProbe':probe};self.store.write(updated,digest(record));return probe
+
+    def context_mark(self,lane_id,nonce,state,models,history_count=None,history_digest=None):
+        record=self.store.read(lane_id);self.qualified(record,models);probe=record.get('contextProbe')
+        transitions={'prepared':{'start-may-have-effects'},'start-may-have-effects':{'native-delivered','uncertain','native-refused'}}
+        if not probe or probe['operationId']!=nonce or state not in transitions.get(probe['state'],set()):
+            raise PackError('Context probe custody differs or delivery cannot be replayed')
+        update={**probe,'state':state}
+        if state=='start-may-have-effects':
+            if type(history_count)is not int or history_count<0 or not isinstance(history_digest,str) or len(history_digest)!=64:
+                raise PackError('Exact own-child native history prefix required before bootstrap')
+            update.update(historyCount=history_count,historyDigest=history_digest)
+        result={**record,'contextProbe':update};return self.store.write(result,digest(record))
+
+    def context_ack(self,lane_id,nonce,models,messages):
+        record=self.store.read(lane_id);self.qualified(record,models);probe=record.get('contextProbe')
+        if (not probe or probe['operationId']!=nonce or probe['state']!='native-delivered' or
+                not isinstance(messages,list) or digest(messages[:probe['historyCount']])!=probe['historyDigest']):
+            raise PackError('Exact native child bootstrap history is missing or changed')
+        indices=[i for i,m in enumerate(messages) if m.get('uuid')==nonce and m.get('type')=='user']
+        if len(indices)!=1 or indices[0]!=probe['historyCount'] or messages[indices[0]].get('message',{}).get('content')!=probe['text']:
+            raise PackError('Real bootstrap native request identity or text differs')
+        tail=messages[indices[0]+1:];stop=next((i for i,m in enumerate(tail) if m.get('type')=='user' and isinstance(m.get('message',{}).get('content'),str)),len(tail));tail=tail[:stop]
+        reads={};results=set();assistant=None
+        for message in tail:
+            blocks=message.get('message',{}).get('content',[])
+            if not isinstance(blocks,list):
+                continue
+            for block in blocks:
+                if block.get('type')=='tool_use' and block.get('name')=='Read' and block.get('input',{}).get('file_path') in probe['fileHashes']:
+                    reads[block['id']]=block['input']['file_path']
+                if block.get('type')=='tool_result' and block.get('is_error') is not True:
+                    results.add(block.get('tool_use_id'))
+            if message.get('type')=='assistant':
+                assistant=message
+        if {path for identity,path in reads.items() if identity in results}!=set(probe['fileHashes']) or not assistant:
+            raise PackError('Same-child native file reads have no matching successful tool results')
+        text=''.join(b.get('text','') for b in assistant['message']['content'] if b.get('type')=='text')
+        if len(text)>2048:
+            raise PackError('Context bootstrap reply exceeds its closed schema')
+        try:actual=__import__('json').loads(text)
+        except ValueError as error:raise PackError('Context bootstrap has no exact structured reply') from error
+        if actual!=probe['expected'] or not assistant.get('uuid'):
+            raise PackError('Same-child context attestation differs from the actual connected role')
+        if any(hashlib.sha256(pathlib.Path(file).read_bytes()).hexdigest()!=sha for file,sha in probe['fileHashes'].items()):
+            raise PackError('Role context changed during actual bootstrap')
+        updated=acknowledge_context(record,record['plan']['role']['contextDigest'])
+        updated['contextProbe']={k:v for k,v in probe.items() if k!='text'}|{'state':'loaded-context-ACK','replyMessageId':assistant['uuid'],
+            'proofDigest':digest({'requestMessageId':nonce,'replyMessageId':assistant['uuid'],'readToolUseIds':sorted(reads),'attestation':actual})}
+        return self.store.write(updated,digest(record))
+
+    def permission_request(self,lane_id,models,request):
+        record=self.store.read(lane_id);self.qualified(record,models)
+        required={'nativeId','fingerprint','requestId','generation','intakeKey','intakeNativeId','toolUseId'}
+        if (not isinstance(request,dict) or set(request)!=required or request['nativeId']!=record['nativeId'] or
+                request['intakeKey']!=record['plan']['intake']['key'] or request['intakeNativeId']!=record['plan']['intake']['nativeId']):
+            raise PackError('Native permission request is outside the original child/intake scope')
+        prior=record.get('permissionRequest')
+        if prior and prior['requestId']==request['requestId'] and prior['fingerprint']==request['fingerprint']:
+            return record
+        _identity(request['toolUseId'],'native approved tool-use identity')
+        updated=request_permission(record,request['fingerprint'],request['requestId'],request['generation'])
+        updated['permissionRequest']['toolUseId']=request['toolUseId']
+        return self.store.write(updated,digest(record))
+
+    def permission_decision(self,lane_id,models,decision,intake_key,fingerprint,generation):
+        record=self.store.read(lane_id);self.qualified(record,models)
+        updated=record_decision(record,decision,intake_key,fingerprint,generation)
+        return self.store.write(updated,digest(record))
+
+    def fixture_plan(self,lane_id,nonce,models):
+        import uuid
+        if str(uuid.UUID(nonce))!=nonce:
+            raise PackError('Exact fixture verification UUID required')
+        record=self.store.read(lane_id);self.qualified(record,models)
+        if record['state']!='loaded-context-ACK' or record.get('fixtureVerification'):
+            raise PackError('Own fixture requires verified loaded context and one fresh bounded operation')
+        role=record['plan']['role'];path=pathlib.Path(record['creationReceipt']['cwd'])/('.topolo-dynamic-'+lane_id+'-'+nonce+'.json')
+        if path.exists() or path.is_symlink():
+            raise PackError('Own native fixture target already exists; never overwrite')
+        expected={'operationId':nonce,'laneId':lane_id,'nativeId':record['nativeId'],'AgentVersionId':role['AgentVersionId'],
+            'AgentWorkspaceId':role['AgentWorkspaceId'],'BytesWorkspaceId':role['BytesWorkspaceId']}
+        text=('Topolo bounded own-worker verification '+nonce+'. You have acknowledged the current role and Agent/Bytes context. '
+            'Write exactly one new fixture file '+str(path)+' with the JSON object '+__import__('json').dumps(expected,separators=(',',':'))+'. '
+            'Use the native Write tool for this file. Request any required native permission through your original intake; do not auto-approve or bypass policy. '
+            'Read back only that file and return one JSON object with operationId and status (ok, denied or failed). '
+            'No other source, business content, credentials, external messages, provider or policy changes are authorized.')
+        fixture={'operationId':nonce,'path':str(path),'expected':expected,'text':text,'state':'prepared','generation':record['nativeConnectionGeneration']}
+        updated={**record,'fixtureVerification':fixture};self.store.write(updated,digest(record));return fixture
+
+    def fixture_mark(self,lane_id,nonce,state,models):
+        record=self.store.read(lane_id);self.qualified(record,models);fixture=record.get('fixtureVerification')
+        transitions={'prepared':{'start-may-have-effects'},'start-may-have-effects':{'native-delivered','uncertain','native-refused'}}
+        if not fixture or fixture['operationId']!=nonce or state not in transitions.get(fixture['state'],set()):
+            raise PackError('Own fixture delivery identity differs or cannot be replayed')
+        result={**record,'fixtureVerification':{**fixture,'state':state}};return self.store.write(result,digest(record))
+
+    def fixture_outcome(self,lane_id,models,messages,native):
+        record=self.store.read(lane_id);self.qualified(record,models);fixture=record.get('fixtureVerification');request=record.get('permissionRequest')
+        if (record['state']!='permission-decision-forwarded' or not fixture or fixture['state']!='native-delivered' or not request or
+                request['generation']!=record['nativeConnectionGeneration'] or native.get('nativeId')!=record['nativeId'] or
+                native.get('busy') is not False or native.get('pendingApprovals')!=0 or not isinstance(messages,list)):
+            raise PackError('Native request/decision/idle child/fixture outcome are not all attributable')
+        tool_uses=[];tool_results=[]
+        for message in messages:
+            blocks=message.get('message',{}).get('content',[])
+            if not isinstance(blocks,list):
+                continue
+            for block in blocks:
+                if block.get('type')=='tool_use' and block.get('id')==request['toolUseId']:
+                    tool_uses.append((message,block))
+                if block.get('type')=='tool_result' and block.get('tool_use_id')==request['toolUseId']:
+                    tool_results.append((message,block))
+        if len(tool_uses)!=1 or len(tool_results)!=1 or tool_uses[0][1].get('name')!='Write' or tool_uses[0][1].get('input',{}).get('file_path')!=fixture['path']:
+            raise PackError('Exact native approved Write/tool-result identity is unavailable')
+        path=pathlib.Path(fixture['path']);failed=tool_results[0][1].get('is_error') is True
+        if record['permissionDecision']=='denied':
+            if not failed or path.exists():
+                raise PackError('Denied native operation has no matching refusal/absent-fixture outcome')
+            outcome='denied';fixture_sha=None
+        elif failed:
+            outcome='failed';fixture_sha=None
+        else:
+            self.store._owned(path)
+            if read_json(path)!=fixture['expected']:
+                raise PackError('Native tool result is not the exact own fixture write/readback')
+            outcome='completed';fixture_sha=hashlib.sha256(path.read_bytes()).hexdigest()
+        proof={'requestFingerprint':request['fingerprint'],'toolUseId':request['toolUseId'],
+            'useMessageId':tool_uses[0][0].get('uuid'),'resultMessageId':tool_results[0][0].get('uuid'),
+            'fixtureSHA256':fixture_sha,'fixtureOperationId':fixture['operationId'],'state':outcome}
+        if not proof['useMessageId'] or not proof['resultMessageId']:
+            raise PackError('Native operation message IDs are missing')
+        updated=record_outcome(record,{'nativeId':record['nativeId'],'requestFingerprint':request['fingerprint'],'state':outcome,'verificationDigest':digest(proof)})
+        updated=settle(updated,native);updated['fixtureVerification']={k:v for k,v in fixture.items() if k!='text'}|{'state':'outcome-verified','proof':proof}
+        return self.store.write(updated,digest(record))
+
+    def retirement_begin(self,lane_id,models):
+        record=self.store.read(lane_id);self.qualified(record,models)
+        if record['state']!='settled':
+            raise PackError('Only the verified settled own child can retire')
+        hold={**record,'state':'uncertain-effect-hold','retirementBeforeDigest':digest(record)}
+        self.store.write(hold,digest(record));return {'record':record,'holdDigest':digest(hold)}
+
+    def retirement_ack(self,operation,models,native):
+        record=operation['record'];held=self.store.read(record['laneId'])
+        if digest(held)!=operation['holdDigest']:
+            raise PackError('Retirement effect owner or beforeimage changed')
+        self.qualified(record,models)
+        result=retire(record,native)
+        return self.store.write(result,digest(held))
+
+
+    def dispatch(self,action,payload):
+        if not isinstance(payload,dict):
+            raise PackError('Closed native helper object required')
+        base={'models'}
+        shapes={
+            'peek':{'sourceRoleKey'},'plan':{'request','nativeIds'},'adopt':{'plan','receipt','native'},
+            'creation-begin':{'laneId','generation'},'creation-record':{'laneId','generation','nativeId'},'creation-read':{'laneId'},
+            'configure-begin':{'laneId','generation'},'configure-ack':{'operation','native'},
+            'context-prepare':{'laneId','operationId'},'context-mark':{'laneId','operationId','state','historyCount','historyDigest'},
+            'context-ack':{'laneId','operationId','messages'},'fixture-prepare':{'laneId','operationId'},
+            'fixture-mark':{'laneId','operationId','state'},'fixture-outcome':{'laneId','messages','native'},
+            'permission-request':{'laneId','request'},'permission-decision':{'laneId','decision','intakeKey','fingerprint','generation'},
+            'retire-begin':{'laneId'},'retire-ack':{'operation','native'},'read':{'laneId'},
+        }
+        if action not in shapes or set(payload)!=base|shapes[action]:
+            raise PackError('Unsupported native lifecycle helper fields/action')
+        p=payload;models=p['models']
+        if action=='peek':
+            current,_,_=self.current(p['sourceRoleKey'],models)
+            state=read_json(self.lib.root/'claude/state.json');titles={}
+            for role in [current['role'],current['intake']]:
+                rows=[r for r in state['agents'] if r['desktopSessionId']==role['nativeId'] and r['key']==role['key']]
+                if len(rows)!=1:
+                    raise PackError('Exact fixed source/intake native title missing')
+                titles[role['nativeId']]=rows[0]['title']
+            return {**current,'nativeTitles':titles}
+        if action=='plan':
+            return self.prepare(p['request'],models,p['nativeIds'])
+        if action=='adopt':
+            return self.adopt(p['plan'],p['receipt'],p['native'],models)
+        if action=='creation-begin':
+            return self.creation(p['laneId'],models,True,p['generation'])
+        if action=='creation-record':
+            return self.creation(p['laneId'],models,generation=p['generation'],native_id=p['nativeId'])
+        if action=='creation-read':
+            return self.creation(p['laneId'],models)
+        if action=='configure-begin':
+            return self.configuration_begin(p['laneId'],models,p['generation'])
+        if action=='configure-ack':
+            return self.configuration_ack(p['operation'],models,p['native'])
+        if action=='context-prepare':
+            return self.context_prepare(p['laneId'],p['operationId'],models)
+        if action=='context-mark':
+            return self.context_mark(p['laneId'],p['operationId'],p['state'],models,p['historyCount'],p['historyDigest'])
+        if action=='context-ack':
+            return self.context_ack(p['laneId'],p['operationId'],models,p['messages'])
+        if action=='fixture-prepare':
+            return self.fixture_plan(p['laneId'],p['operationId'],models)
+        if action=='fixture-mark':
+            return self.fixture_mark(p['laneId'],p['operationId'],p['state'],models)
+        if action=='fixture-outcome':
+            return self.fixture_outcome(p['laneId'],models,p['messages'],p['native'])
+        if action=='permission-request':
+            return self.permission_request(p['laneId'],models,p['request'])
+        if action=='permission-decision':
+            return self.permission_decision(p['laneId'],models,p['decision'],p['intakeKey'],p['fingerprint'],p['generation'])
+        if action=='retire-begin':
+            return self.retirement_begin(p['laneId'],models)
+        if action=='retire-ack':
+            return self.retirement_ack(p['operation'],models,p['native'])
+        record=self.store.read(p['laneId'])
+        if not record:
+            raise PackError('Exact own dynamic lane record missing')
+        self.qualified(record,models);return record
+
+
+def model_configuration_template(manifest,revision):
+    """Reviewable new-lane configuration only; no native availability claim."""
+    configuration=task_models.default_configuration()
+    models=sorted({model for host in configuration['harnesses'].values() for model in host['tiers'].values()})
+    layer={'allowedModels':models,'allowedEfforts':['low','medium','high']}
+    groups=sorted({a['set'] for a in manifest['agents']})
+    roles=sorted('/'.join([a['pack'],a['set'],a['id']]) for a in manifest['agents'])
+    return {'format':'topolo-pack-dynamic-models','schemaVersion':1,'sourceRevision':revision,'configuration':configuration,
+        'constraints':{'pack':copy.deepcopy(layer),'groups':{key:copy.deepcopy(layer) for key in groups},
+            'roles':{key:copy.deepcopy(layer) for key in roles}},'authorizedOverrides':[]}
+
+
+def install_model_configuration(lib,pack,document,before_digest):
+    manifest,revision=lib.load(pack)
+    expected={'format','schemaVersion','sourceRevision','configuration','constraints','authorizedOverrides'}
+    if (not isinstance(document,dict) or set(document)!=expected or document['format']!='topolo-pack-dynamic-models' or
+        document['schemaVersion']!=1 or document['sourceRevision']!=revision or not isinstance(document['authorizedOverrides'],list) or
+        any(not isinstance(v,str) or len(v)!=64 for v in document['authorizedOverrides'])):
+        raise PackError('Explicit current reviewable dynamic model configuration required')
+    template=model_configuration_template(manifest,revision)
+    if set(document['constraints'].get('roles',{}))!=set(template['constraints']['roles']) or set(document['constraints'].get('groups',{}))!=set(template['constraints']['groups']):
+        raise PackError('Dynamic model constraints must explicitly cover the exact source pack roles/groups')
+    for key in template['constraints']['roles']:task_models.role_constraints(document['constraints'],key)
+    directory=lib.root/'dynamic-models';registry=Registry(lib.root,'codex');registry._owned(lib.root,True)
+    if not directory.exists():
+        directory.mkdir(mode=0o700)
+    registry._owned(directory,True);path=directory/(safe_id(pack)+'.json')
+    current=None
+    if path.exists() or path.is_symlink():
+        registry._owned(path);current=read_json(path)
+    if (digest(current) if current is not None else None)!=before_digest:
+        raise PackError('Current dynamic configuration beforeimage differs; no overwrite')
+    atomic_json(path,document)
+    if read_json(path)!=document:
+        raise PackError('Dynamic configuration readback differs')
+    return {'state':'dynamic-task-model-intent-installed','pack':pack,'configurationDigest':digest(document),
+        'nativeAvailabilityVerified':False,'existingRoleSettingsChanged':False,'modelTurnsStarted':False}