@topolo/cli 0.13.8 → 0.13.10

package/README.md

@@ -366,11 +366,11 @@ transient refresh failures.
 ## Topolo Agent Packs
 
 `topolo agent-packs` is the public entry point for portable business agent packs.
-The CLI bundles the Codex adapter; Python 3.11+ and the supported Codex desktop
-installation are required for native local switching. No separate pack CLI
-installation is needed. Claude and Cursor adapters are planned and currently
-refused before any mutation. MCP setup for those apps is separate from pack
-switching and does not establish pack adapter support.
+The CLI bundles the Codex adapter and the qualified Claude Desktop Code preview.
+Python 3.11+ and a supported native host are required for local operations. No
+separate pack CLI installation is needed. The adapter README describes each
+host's current qualification and live-operation requirements. Cursor pack
+operations remain unsupported. MCP setup and pack adoption have separate proof.
 
 ```sh
 topolo agent-packs add founder --harness codex
@@ -378,6 +378,7 @@ topolo agent-packs add founder --group specialists
 topolo agent-packs add founder --agent strategy
 topolo agent-packs switch founder
 topolo agent-packs status
+topolo agent-packs open --adapter-help
 ```
 
 A first add builds the bundled template into a fresh installed instance. Later
@@ -385,6 +386,9 @@ adds and switches resume that instance. `--group` selects the template's set;
 `--agent` selects an unambiguous logical agent. Use `list` to inspect installed
 names. Pack templates retain operating rules, rather than earlier work history.
 The underlying `topolo-agent-pack` adapter contains native switching and recovery.
+`topolo agent-packs open` exposes that adapter's existing managed Codex desktop
+route, including `--app` and `--codex-bin`. It uses the library's selected runtime
+and stable desktop profile; it does not select a new native home.
 
 Cloud continuity uses explicit environment and authenticated context pins:
 
@@ -402,8 +406,33 @@ released in the selected environment first. The CLI does not create grants,
 choose another customer, invoke model work or silently publish agent versions.
 See the bundled adapter README for memory, artifact and recovery commands.
 
+Native child helpers require an explicitly selected private profile reference
+on the existing connection. Use `connect --private-profile` with a nonempty
+`TOPOLO_CONFIG_PATH` pointing to the already authenticated protected profile.
+The producer checks file ownership and modes, authenticates the selected
+environment/context, and verifies the connection before recording public
+profile metadata. Helpers build a child-only environment from that binding.
+Credential contents and inherited token overrides are excluded from the pack.
+Profile metadata does not establish native MCP configuration or runtime health.
+
+Task-specific lane model intent is available through `lane models-template`
+and `lane models-install`; `lane status` reads durable state. Native settings,
+context, original-intake approval, operation outcome and retirement each require
+their own current acknowledgement. See [the adapter guide](agent-packs/README.md)
+for the closed inputs and lifecycle boundaries.
+
 The source quality gate covers the CLI dispatcher and the Python continuity
 adapter separately. `pnpm coverage` creates a local test environment under
 `node_modules/.cache`, installs the pinned test-only coverage tool and requires
 100% line and branch coverage for the cloud connection/recovery adapter.
 These tests use scoped fixtures and do not invoke models or mutate cloud data.
+
+
+Claude dynamic private startup currently refuses with
+`native_private_query_prestart_contract_unqualified`. The installed desktop
+contract has not qualified private query MCP configuration, exclusion of other
+Topolo connections, and the owned shutdown lifecycle. Create, configure,
+context start, fixture start, retirement, and positive permission forwarding
+remain closed before native access. A valid private profile reference does not
+lift this boundary. Source fixtures and descriptor reads do not establish
+private MCP adoption or actual task completion.

package/agent-packs/README.md

@@ -201,6 +201,18 @@ scrub conversations. Bundles are private files and are not encrypted.
 
 ## Desktop moving parts and recovery
 
+The existing desktop entry is exposed through the public CLI:
+
+```sh
+topolo agent-packs --store /absolute/AgentPacks open --adapter-help
+topolo agent-packs --store /absolute/AgentPacks open \
+  --app /Applications/ChatGPT.app --codex-bin /absolute/qualified/codex
+```
+
+The second command performs the normal managed desktop open/reconnect operation.
+It retains the selected runtime and stable desktop profile described below.
+Its usual ownership, idle-work and recovery checks still apply.
+
 ```
 objects/           immutable content addressed by SHA-256
 packs/             immutable captures and revision heads
@@ -571,3 +583,89 @@ exact PID/roster identity and current module qualification. No independent
 daemon, polling loop, arbitrary evaluation endpoint or UI pack fix is used.
 Audit failures refuse further broker operation. Cached reports and source
 fixtures are not live native settings or shared Agent/Bytes acceptance proof.
+
+
+## Private profiles for native child helpers
+
+A native helper uses an explicit private credential profile from the existing
+Topolo connection binding. First authenticate and qualify that profile through
+the supported CLI. Add `--private-profile` to the normal `connect` request and
+select its protected store for that process with `TOPOLO_CONFIG_PATH`:
+
+```sh
+TOPOLO_CONFIG_PATH=/absolute/private-profile/config.json \
+topolo --env production agent-packs connect founder --harness claude \
+  --environment production --context-key org:DISCOVERED_ORGANIZATION_ID \
+  --agent-workspace DISCOVERED_AGENT_WORKSPACE \
+  --bytes-workspace DISCOVERED_BYTES_WORKSPACE \
+  --ownership user --bytes-scope private --roles roles.json \
+  --private-profile --confirm
+```
+
+The profile must be a regular, same-owner, single-link file with mode `0600` in
+an owned `0700` directory. Credential contents are never copied into a pack or
+hashed for this reference. The producer checks the selected client environment
+and context, obtains the actual principal, and verifies the connection read-back
+before recording `privateCredentialProfile` metadata on the existing binding.
+Requalifying that private connection requires the explicit flag again.
+
+Before launching a helper, the native adapter checks the current binding,
+installation consent, source revision, original intake, public role descriptors,
+and Agent/Bytes workspace references. It constructs only the child process's
+OS runtime environment plus the bound `TOPOLO_CONFIG_PATH`, `TOPOLO_ENV` and
+`TOPOLO_CONTEXT`. Host token overrides and unrelated environment variables are
+excluded. Missing or stale private metadata refuses before client startup.
+The native app's environment and the other sessions remain unchanged.
+
+This private helper reference and an authenticated CLI are separate from the
+native child's applied MCP configuration. Native creation and activation still
+require the qualified host startup contract, actual same-process MCP status and
+principal proof. A profile path, descriptor hash or helper success supplies none
+of those acknowledgements by itself.
+
+## Dynamic lane task-model intent
+
+A lane has one immutable task resolution and its original intake route. The
+versioned configuration includes explicit pack, group and role model/effort
+constraints. `models-template` takes a JSON input containing only the installed
+`pack` name and returns a reviewable configuration tied to its current source
+revision. `models-install` takes exactly `pack`, `configuration` and
+`beforeDigest`; use `null` only for the first installation.
+
+```sh
+topolo agent-packs lane models-template --input /absolute/pack-name.json
+topolo agent-packs lane models-install --input /absolute/reviewed-model-install.json
+topolo agent-packs lane status
+```
+
+Installation records intent and preserves existing role settings. Resolution
+intersects that configuration with the current native account catalog; no
+unavailable model or effort falls back to a parent setting. For Claude, a
+native model-ID observation is only an intent input. The actual fresh process
+must acknowledge the exact model and effort before work. Explicit task overrides
+also require their recorded intake authorization.
+
+Each later operation rechecks current source, intake, context and policy. Native
+creation/adoption, settings acknowledgement, own-file context bootstrap, original
+intake permission decision, native operation outcome, fixture read-back,
+settlement, preserved-history retirement and own-control closure are distinct
+states. `lane status` reads durable state; `lane read` performs the qualified
+current native read. Codex uses an explicit foreground `lane serve` connection
+to the existing managed window. Its child creation and approval responses stay
+on that captured native owner, without another app-server process.
+
+A lost acknowledgement retains its possible-effect state and blocks replay.
+Retirement requires the actual own child to be idle with no pending approvals,
+and verifies native history preservation. Closing a connection removes only its
+owned controls and subscriptions. Existing fixed lanes and their original
+intake settings are preserved throughout.
+
+
+Claude dynamic private startup currently refuses with
+`native_private_query_prestart_contract_unqualified`. The installed desktop
+contract has not qualified private query MCP configuration, exclusion of other
+Topolo connections, and the owned shutdown lifecycle. Create, configure,
+context start, fixture start, retirement, and positive permission forwarding
+remain closed before native access. A valid private profile reference does not
+lift this boundary. Source fixtures and descriptor reads do not establish
+private MCP adoption or actual task completion.

package/agent-packs/coverage_changed.py

@@ -15,7 +15,7 @@ from coverage.parser import PythonParser
 
 RELEASE_BASE = '6a13ada56844712aae58738ba01dbbdf90718bef'
 SOURCE = pathlib.Path('agent-packs/src/topolo_agent_pack')
-MODULES = {'topolo', 'claude', 'policy', 'permissions', 'approvals', 'execution', 'live', 'cli'}
+MODULES = {'topolo', 'claude', 'policy', 'permissions', 'approvals', 'execution', 'live', 'cli', 'lanes', 'task_models'}
 
 
 class CoverageRefused(RuntimeError):

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

@@ -29,6 +29,28 @@ class ApprovalRouter:
                         intake.get('contextKey') != role['contextKey']):
                     raise PackError('Approval route has no same-context owned intake')
 
+    def register_dynamic(self, role):
+        """Append one route without replacing the connection or pending requests."""
+        intake = self.by_key.get(role.get('intakeKey'))
+        if (not role.get('dynamicLaneId') or not intake or '/intakes/' not in intake['key'] or
+                role.get('contextKey') != intake.get('contextKey') or
+                role.get('dynamicIntakeNativeId') != intake['threadId']):
+            raise PackError('Dynamic approval route has no exact same-context original intake')
+        old = self.roles.get(role['threadId'])
+        if old and old.get('dynamicPlanDigest') != role.get('dynamicPlanDigest'):
+            raise PackError('Dynamic approval identity conflicts with a current role')
+        if role['key'] in self.by_key and self.by_key[role['key']]['threadId'] != role['threadId']:
+            raise PackError('Dynamic approval role key is already owned')
+        self.roles[role['threadId']] = copy.deepcopy(role)
+        self.by_key[role['key']] = self.roles[role['threadId']]
+
+    def retire_dynamic(self, thread_id):
+        role = self.roles.get(thread_id)
+        if (not role or not role.get('dynamicLaneId') or
+                any(entry['record']['sourceThreadId'] == thread_id for entry in self.pending.values())):
+            raise PackError('Dynamic lane retains a pending native approval or is not an owned child')
+        self.roles.pop(thread_id); self.by_key.pop(role['key'])
+
     def capture(self, message):
         if message.get('method') not in METHODS or 'id' not in message:
             return None

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

@@ -325,8 +325,12 @@ def parser():
     q.add_argument('--apply',action='store_true',help='Configure the existing idle owned Codex backend; no new app server or model turn')
     q=sub.add_parser('approvals',help='Read and relay exact live native decisions through the owning intake')
     q.add_argument('operation',choices=['list','details','respond']);q.add_argument('key',nargs='?')
-    q.add_argument('--intake');q.add_argument('--fingerprint');q.add_argument('--response')
+    q.add_argument('--connection');q.add_argument('--intake');q.add_argument('--fingerprint');q.add_argument('--response')
     q.add_argument('--human-decision-recorded',action='store_true')
+    q=sub.add_parser('lane',help='Plan, adopt and verify one pack-managed native child through its original intake')
+    q.add_argument('operation',choices=['plan','adopt','configure','status','read','settle','retire','serve','close','create','context-start','context-read','fixture-start','fixture-read','models-template','models-install'])
+    q.add_argument('--connection',help='Exact explicit foreground owned lane connection ID')
+    q.add_argument('--input',help='Closed operation JSON; never arbitrary native RPC or task prompts')
     q=sub.add_parser('smoke',help='Start or read one closed, bound native acceptance case; never arbitrary prompts')
     q.add_argument('operation',choices=['start','read']);q.add_argument('identity')
     q.add_argument('--case',choices=sorted(live.SMOKE_CASES));q.add_argument('--operation-id')
@@ -339,6 +343,7 @@ def parser():
             q.add_argument('--roles',required=True);q.add_argument('--agent-workspace',required=True);q.add_argument('--bytes-workspace',required=True)
             q.add_argument('--ownership',choices=['user','organization'],required=True);q.add_argument('--bytes-scope',choices=['private','org'],required=True);q.add_argument('--instance')
             q.add_argument('--reconcile-local-context',action='store_true',help='Explicitly reconcile a recorded partial context attachment; never replays cloud writes')
+            q.add_argument('--private-profile',action='store_true',help='Bind the explicitly selected protected profile metadata for native child helpers')
         if command=='remember':
             q.add_argument('--content',required=True);q.add_argument('--kind',choices=['instruction','knowledge','durable'],required=True)
             q.add_argument('--provenance',required=True);q.add_argument('--visibility',choices=['private','shared'],default='private')
@@ -366,8 +371,9 @@ def main(argv=None):
     command_args=list(argv)
     if command_args and command_args[0]=='--store':command_args=command_args[2:]
     elif command_args and command_args[0].startswith('--store='):command_args=command_args[1:]
+    lane_command=bool(command_args and command_args[0]=='lane')
     cloud_command=bool(command_args and command_args[0] in {'connect','remote-context','remember','artifact','artifact-get','remote-recover'})
-    if harness == 'claude' and not policy_command and not cloud_command:
+    if harness == 'claude' and not policy_command and not cloud_command and not lane_command:
         from . import claude
         return claude.main(argv)
     if harness not in {'codex', 'claude'}:
@@ -382,8 +388,35 @@ def main(argv=None):
             with topolo.connection_lock(lib,args):result=topolo.dispatch(lib,args)
             emit(result)
             return 0
+        if args.command=='lane' and args.operation=='serve':
+            if harness!='codex' or not args.connection or not args.input:
+                raise PackError('Explicit Codex connection ID and reviewed input binding required')
+            import asyncio
+            asyncio.run(live.OwnedLaneConnection(lib,args.connection,read_json(args.input)).run());return 0
         with lib.lock():
-            if args.command=='smoke':
+            if args.command=='lane':
+                from .lanes import Registry
+                params=read_json(args.input) if args.input else {}
+                if not isinstance(params,dict):
+                    raise PackError('Closed native lane input object required')
+                if args.operation in {'models-template','models-install'}:
+                    from . import lanes
+                    if args.operation=='models-template':
+                        if set(params)!={'pack'}:
+                            raise PackError('Exact source pack required')
+                        manifest,revision=lib.load(params['pack']);result=lanes.model_configuration_template(manifest,revision)
+                    else:
+                        if set(params)!={'pack','configuration','beforeDigest'}:
+                            raise PackError('Exact model configuration and beforeimage required')
+                        result=lanes.install_model_configuration(lib,params['pack'],params['configuration'],params['beforeDigest'])
+                elif args.operation=='status':
+                    if params:
+                        raise PackError('Lane status accepts no overrides')
+                    result={'harness':harness,'lanes':Registry(lib.root,harness).records(), 'proof':'durable intent; native connection must requalify'}
+                elif harness!='codex':
+                    raise PackError('Use the native Claude lane adapter with its qualified connection')
+                else: result=(live.request_lane(lib,args.connection,'lane-'+args.operation,params) if args.connection else live.request(lib,'lane-'+args.operation,params))
+            elif args.command=='smoke':
                 if args.operation=='start':
                     if not args.case or not args.operation_id:
                         raise PackError('Exact smoke case and operation ID required')
@@ -401,7 +434,7 @@ def main(argv=None):
                     if not args.response or not args.human_decision_recorded:
                         raise PackError('Response file and recorded human decision required')
                     params.update(result=read_json(args.response),humanDecisionRecorded=True)
-                result=live.request(lib,'approval-'+args.operation,params)
+                result=live.request_lane(lib,args.connection,'approval-'+args.operation,params) if args.connection else live.request(lib,'approval-'+args.operation,params)
             elif args.command=='permissions':
                 from . import permissions, topolo
                 if args.apply and harness!='codex':

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

@@ -62,7 +62,9 @@ class ExecutionGate:
             required = {'model', 'model_reasoning_effort', 'approval_policy', 'approvals_reviewer',
                         'sandbox_mode', 'sandbox_workspace_write', 'apps'}
             if (set(spec) != required or not isinstance(spec['model'], str) or not spec['model'] or
-                    spec['model_reasoning_effort'] not in {'medium', 'high'} or
+                    (spec['model_reasoning_effort'] not in {'medium', 'high'} and not
+                     (role.get('dynamicLaneId') and role.get('dynamicModelResolution', {}).get('resolved') ==
+                      {'model': spec['model'], 'effort': spec['model_reasoning_effort']})) or
                     spec['approval_policy'] not in {'on-request', 'never'} or spec['approvals_reviewer'] != 'user' or
                     spec['sandbox_mode'] not in {'read-only', 'workspace-write', 'danger-full-access'} or
                     (spec['sandbox_mode'] == 'danger-full-access') != (spec['approval_policy'] == 'never') or
@@ -74,6 +76,59 @@ class ExecutionGate:
                      (spec['apps'] != {'_default': {'default_tools_approval_mode': 'approve'}} or not role.get('contextKey') or not role.get('intakeKey')))):
                 raise PackError('Unqualified role execution settings')
             self.roles[tid] = copy.deepcopy(role)
+            if role.get('dynamicLaneId'):
+                # Persisted intent cannot reinstate native proof after reconnect.
+                self.roles[tid]['dynamicCurrentQualified'] = False
+                self.roles[tid]['dynamicContextVerified'] = False
+
+    def register_dynamic(self, record):
+        from .lanes import execution_role
+        row = execution_role(record)
+        parent = self.roles.get(row['sourceRoleNativeId'])
+        intake = self.roles.get(row['dynamicIntakeNativeId'])
+        if (not parent or not intake or parent['key'] != row['sourceRoleKey'] or
+                intake['key'] != row['intakeKey'] or parent.get('intakeKey') != row['intakeKey'] or
+                parent.get('contextKey') != row['contextKey'] or intake.get('contextKey') != row['contextKey'] or
+                parent['sourceRevision'] != row['sourceRevision']):
+            raise PackError('Dynamic execution has no current same-context source role and original intake')
+        existing = self.roles.get(row['threadId'])
+        if existing is not None:
+            if existing.get('dynamicPlanDigest') != row['dynamicPlanDigest']:
+                raise PackError('Dynamic native identity conflicts with an existing managed role')
+            return copy.deepcopy(existing)
+        row['installationConsent'] = copy.deepcopy(parent.get('installationConsent'))
+        candidate = ExecutionGate({'format': 'topolo-codex-runtime-execution', 'schemaVersion': 1, 'roles': list({r['threadId']: r for r in [parent, intake, row]}.values())})
+        choice = row['dynamicModelResolution']['resolved']
+        if choice['effort'] not in self.catalog.get(choice['model'], set()):
+            raise PackError('Dynamic task model is unavailable in the current native account catalog')
+        self.roles[row['threadId']] = candidate.roles[row['threadId']]
+        self.verified.discard(row['threadId'])
+        return copy.deepcopy(row)
+
+    def prepare_dynamic_configuration(self, record, current):
+        if record['state'] != 'adopted-unconfigured' or current != {
+                'role': record['plan']['role'], 'intake': record['plan']['intake'], 'ceiling': record['plan']['ceiling']}:
+            raise PackError('Dynamic configuration requires fresh adopted source and policy inputs')
+        self.register_dynamic(record)
+        self.roles[record['nativeId']]['dynamicCurrentQualified'] = True
+        # Only resume is allowed until the native settings and loaded context ACK.
+        self.roles[record['nativeId']]['dynamicContextVerified'] = False
+
+    def qualify_dynamic(self, record, current):
+        role = self.roles.get(record['nativeId'])
+        plan = record['plan']
+        if (not role or role.get('dynamicPlanDigest') != record['planDigest'] or
+                current != {'role': plan['role'], 'intake': plan['intake'], 'ceiling': plan['ceiling']} or
+                record.get('nativeSettingsACK') != plan['resolution']['resolved']):
+            raise PackError('Dynamic role, intake or policy input is stale or unqualified')
+        role['dynamicCurrentQualified'] = True
+        role['dynamicContextVerified'] = record.get('contextACK') == plan['role']['contextDigest']
+
+    def retire_dynamic(self, thread_id):
+        role = self.roles.get(thread_id)
+        if (not role or not role.get('dynamicLaneId') or thread_id in self.pending.values()):
+            raise PackError('Only an idle owned dynamic execution row may retire')
+        self.roles.pop(thread_id); self.verified.discard(thread_id)
 
     def set_catalog(self, result):
         self.catalog = {row['model']: {e['reasoningEffort'] for e in row['supportedReasoningEfforts']}
@@ -90,17 +145,24 @@ class ExecutionGate:
     def prepare(self, message):
         value = copy.deepcopy(message); method = value.get('method'); params = value.get('params') or {}
         tid = params.get('threadId'); role = self.roles.get(tid)
+        if role and role.get('dynamicLaneId') and method == 'thread/settings/update':
+            raise PackError('Dynamic settings changes require a new reviewed task resolution and native ACK')
         if not role or method not in {'thread/resume', 'turn/start'}:
             return value
         if 'id' not in value or str(value['id']) in self.pending:
             raise PackError('Managed execution requires a unique request identity')
         spec = role['settings']
+        if role.get('dynamicLaneId') and not role.get('dynamicCurrentQualified'):
+            raise PackError('Dynamic lane needs fresh source, intake and policy qualification on this connection')
+        if role.get('dynamicLaneId') and not role.get('dynamicContextVerified') and method == 'turn/start':
+            raise PackError('Dynamic lane needs actual loaded role context before task execution')
         if spec['model_reasoning_effort'] not in self.catalog.get(spec['model'], set()):
             raise PackError('Role model/effort is absent from the native account catalog; no fallback selected')
         if any(params.get(key) is not None for key in ['permissions', 'path', 'history', 'collaborationMode', 'environments', 'runtimeWorkspaceRoots']):
             raise PackError('Frontend supplied unreviewed permission, identity or execution overrides')
         wanted = {'cwd': role['cwd'], 'model': spec['model'], 'approvalPolicy': spec['approval_policy'],
                   'approvalsReviewer': spec['approvals_reviewer']}
+        if role.get('dynamicLaneId') and method=='thread/resume':wanted['allowProviderModelFallback']=False
         if method == 'thread/resume':
             wanted['sandbox'] = spec['sandbox_mode']
             wanted['config'] = {'model_reasoning_effort': spec['model_reasoning_effort'],
@@ -148,12 +210,18 @@ def load_gate(runtime):
     return ExecutionGate(read_json(path)) if path.exists() else None
 
 
-def qualify_protocol(binary, run=subprocess.run):
+def qualify_protocol(binary, run=subprocess.run, *, lane_creation=False):
     """Generate schema offline from this executable; never initialize an app server."""
     required = {'ThreadResumeParams': {'threadId', 'model', 'approvalPolicy', 'approvalsReviewer', 'sandbox', 'config'},
                 'ThreadResumeResponse': {'thread', 'model', 'cwd', 'reasoningEffort', 'approvalPolicy', 'approvalsReviewer', 'sandbox'},
                 'TurnStartParams': {'threadId', 'model', 'effort', 'approvalPolicy', 'approvalsReviewer', 'sandboxPolicy'},
                 'ModelListParams': {'includeHidden', 'cursor'}, 'ModelListResponse': {'data', 'nextCursor'}}
+    if lane_creation:
+        required.update({'ThreadStartParams':{'cwd','model','config','developerInstructions','approvalPolicy','sandbox','allowProviderModelFallback'},
+            'ThreadStartResponse':{'thread','model','cwd','reasoningEffort','instructionSources'},
+            'ThreadReadParams':{'threadId','includeTurns'},'ThreadReadResponse':{'thread'},'ThreadArchiveParams':{'threadId'},
+            'ConfigReadParams':{'cwd','includeLayers'},'ConfigReadResponse':{'config','layers','origins'}})
+        required['ThreadResumeParams'].add('allowProviderModelFallback')
     with tempfile.TemporaryDirectory(prefix='topolo-codex-protocol-') as temp:
         result = run([binary, 'app-server', 'generate-json-schema', '--experimental', '--out', temp],
                      capture_output=True, timeout=20, check=False)