@topolo/cli 0.13.0 → 0.13.2

package/agent-packs/README.md

@@ -339,3 +339,157 @@ unresolved for explicit reconciliation. An uploaded but unregistered artifact
 remains stored in Bytes and is reported separately. An uncertain connection can
 be retried with the identical immutable connect request. Switching does not
 reset a remote binding or erase Agent memory or Bytes files.
+
+
+## Claude Desktop preview
+
+Claude Code Desktop 2.1.289 is qualified for native session import through
+`--desktop --resume`. Each fresh pack role has its own named sidebar session,
+CLAUDE.md, portable context files and persistent Claude session ID. No old Codex
+conversation is copied and import submits no new task.
+
+```sh
+topolo-agent-pack add topolo-clean --harness claude --import-only
+topolo-agent-pack add topolo-clean --harness claude --group intakes --import-only
+topolo-agent-pack add topolo-clean --harness claude --agent topolo-clean/intakes/engineering --import-only
+topolo-agent-pack status --harness claude
+```
+
+The public CLI source also dispatches `topolo agent-packs add ... --harness claude`;
+this source change has not been published to the registry.
+
+The CLI import handoff does not control outgoing membership, groups or pins.
+Switching through that handoff refuses before changes. The experimental native
+connection below provides a separate source implementation for those operations;
+it still requires independent live and customer installation proof.
+The adapter never edits Claude's live metadata, account state or permissions.
+`recover` reads actual Desktop adoption records and reports incomplete imports;
+repeating `add` resumes pending adoption with the same IDs. Workspaces and
+transcripts live under the selected pack library and Claude config respectively.
+Default Claude auto-cleanup still applies to transcripts; this preview is not a
+portable backup of accumulated Claude history. Existing Codex switching is
+unchanged. Role-identity inference, hosted Agent/Bytes shared memory and clean
+machine installation require separate acceptance.
+
+## Agent execution policy
+
+`topolo agent-packs policy topolo-clean` renders the portable model, reasoning,
+approval and sidebar intent for every role. Use `--group`, `--agent`,
+`--harness codex|claude` and `--output /absolute/path/review.json` to select or
+save a review copy. The command never changes existing sessions or permissions.
+An agent can declare `executionProfile` as `intake`, `analysis`, `review`,
+`build` or `operator`; otherwise the adapter resolves its role default.
+
+The initial Claude policy uses Opus 5.5 for reasoning roles and Sonnet 5.5 for
+execution. Haiku 5.5 is not selected for the qualified 2.1.289 host, because it
+requires 2.1.293 or later. Codex uses GPT-6 Astra for reasoning roles and
+GPT-6.1 Sol for execution. These are desired settings, not proof of account
+availability or live session selection.
+
+Codex sandboxing and Claude permission modes have separate mappings. Claude
+Manual does not enforce a read-only filesystem sandbox. The policy records
+that extra confinement requirement instead of treating the two controls as
+equivalent. Platform mutations still require the existing scoped authorization.
+
+Role context and relevant memory should be loaded on demand, with bounded tool
+results and one evidence-linked handoff. An idle pack should generate no model
+turns or background polling. No token savings are claimed without usage evidence.
+
+Claude session adoption is currently verified independently from complete pack
+activation. The external native import command does not provide live group,
+pin, model or outgoing-roster controls. `activationReady` and
+`modelAndPermissionSettingsVerified` remain false until a qualified backend
+transport applies and reads back those settings. UI automation is not part of
+the adapter. Import status is deliberately separate from native activation proof.
+### Experimental Claude live configuration
+
+The native import is not pack activation. `configure` can preflight and apply
+an already adopted roster through the running Claude main process. This is an
+internal compatibility adapter qualified for **Claude Desktop 2.31226.1** and
+the exact native module hashes in `src/lib/claude-pack-backend.ts`; it refuses
+other builds. It invokes native session-manager APIs and acknowledged sidebar
+commands. It does not automate the UI or edit cached desktop records.
+
+```sh
+topolo agent-packs policy topolo-clean --harness claude --output /absolute/review.json
+topolo agent-packs configure topolo-clean --harness claude \
+  --policy /absolute/review.json --pid <Claude-main-PID> \
+  --endpoint ws://127.0.0.1:<port>/<inspector-UUID>
+# After reviewing the preflight, repeat the same command with --apply.
+```
+
+The endpoint must be enabled separately with the machine owner's explicit
+authorization: a main-process debugger allows local code execution. The
+adapter does not enable debugging, signal/restart Claude, patch its app bundle,
+or leave a background service. Close a temporarily enabled debugger after the
+operation. This experimental connection is not a released customer setup path.
+The inspected 2.31226.1 build disables Electron's `nodeCliInspect` fuse, so
+startup flags and `SIGUSR1` do not enable its inspector. Its native Developer
+Mode setup requires a one-time restart, followed by the Developer menu's
+`Enable Main Process Debugger` setting. Any such setup is separately authorized;
+do not patch fuses or assume a restart flag opens the endpoint.
+
+All selected sessions must be idle, have matching titles/workspaces, and use
+models from the native account catalog. Settings use Manual or Accept edits;
+no bypass permission is accepted. An fsynced journal records the baseline and
+each attempted native effect before dispatch. On a disconnect or failed
+acknowledgement, use the explicit read-only native recovery command below before
+retrying; do not assume failure means no effects. Application independently
+reads back groups, pins, models, effort and permission modes and hashes role
+charters/transcripts before and after. It does not claim an inference test,
+read-only filesystem confinement or hosted memory verification. Those remain
+separate acceptance boundaries.
+
+### Experimental native Claude switching and recovery
+
+First configure and verify the initial adopted pack. Prepare/import the target
+pack independently and render its complete reviewed policy. Then preflight:
+
+```sh
+topolo agent-packs switch personal --harness claude \
+  --policy /absolute/personal-policy.json --pid <Claude-main-PID> \
+  --endpoint ws://127.0.0.1:<port>/<inspector-UUID>
+# Repeat with --apply after reviewing the result.
+topolo agent-packs recover personal --harness claude \
+  --policy /absolute/personal-policy.json --pid <Claude-main-PID> \
+  --endpoint ws://127.0.0.1:<port>/<inspector-UUID>
+```
+
+Switching archives only the explicit previously verified outgoing roster and
+unarchives the existing target identities. It does not delete sessions, clean
+worktrees, create model turns or touch unrelated sessions. Live work, remote or
+linked workspaces and nonempty archive cascades refuse before effects. Role
+files and transcripts are hashed inside the native operation and independently
+by the caller. Python imports and native commands share the same library lock;
+the native manager also fences competing operations across libraries.
+
+An interrupted native operation blocks further imports or native operations.
+Recovery reads the exact sealed operation plan and native state; it never
+replays effects. A completely verified target can finalize an interrupted
+commit. If the journal proves no effect was attempted, recovery releases that
+operation without changing the previous active composition. Partial effects,
+changed context and a still-running operation remain recovery-required; they
+need supported owner reconciliation. No expiry or PID observation clears a
+pending operation. `status --harness claude` distinguishes adoption readback,
+the last verified active roster and pending recovery; cached proof is not
+reported as current native settings. Use explicit native recovery above rather
+than retrying an uncertain apply.
+
+### Managed Codex role execution
+
+New managed compositions carry a closed per-role execution policy. The owned
+proxy qualifies the installed executable's exported protocol offline and reads
+its account model catalog. On native `thread/resume` it supplies the selected
+role's model, effort, approval reviewer and local sandbox without starting a
+turn. An effective-settings mismatch blocks subsequent model work. Conflicting
+frontend overrides are reported; the adapter never silently substitutes models
+or expands permissions. Update reviewed policy explicitly to change it.
+Read-only roles have no command network access; workspace writers are confined
+to their role workspace with temporary-directory roots excluded. Platform tool
+authorization remains separate from local command sandboxing.
+
+Managed bridge status reports requested policy and which resumes have current
+native readback. It does not claim an inference test or independent app-tool
+approval readback. Existing runtimes without this policy report not-configured
+until explicitly rebuilt. Source fixtures do not establish live desktop or
+three-environment shared-memory acceptance.

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

@@ -0,0 +1,265 @@
+"""Versioned Claude Code Desktop session import. Never rewrites live app records.
+
+Fresh role files and CLI transcripts are owned by this adapter. Desktop adopts
+them through its native resume handoff. There is no external archive API in
+that handoff; full roster replacement is therefore refused, not simulated.
+"""
+import argparse
+import hashlib
+import json
+import os
+import pathlib
+import pty
+import select as io_select
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+
+from .storage import Library, PackError, atomic_json, canonical, now, safe_id, select
+
+
+def find_binary():
+    root = pathlib.Path.home() / 'Library/Application Support/Claude/claude-code'
+    candidates = list(root.glob('*/*/claude.app/Contents/MacOS/claude'))
+    if candidates:
+        return str(max(candidates, key=lambda p: tuple(int(x) for x in p.relative_to(root).parts[0].split('.'))))
+    return shutil.which('claude')
+
+
+def handoff(binary, directory, session_id):
+    """Native --desktop requires a TTY. No prompt, model call or shell is used."""
+    if not binary:
+        raise PackError('Claude Code 2.1.285+ is required; install Claude Desktop or Claude Code.')
+    version = subprocess.run([binary, '--version'], capture_output=True, text=True, timeout=10)
+    if version.returncode or not version.stdout.startswith('2.1.289 '):
+        raise PackError('This native import adapter is qualified for Claude Code 2.1.289; selected binary: ' + version.stdout.strip())
+    master, slave = pty.openpty()
+    process = None
+    output = bytearray()
+    try:
+        process = subprocess.Popen([binary, '--desktop', '--resume', session_id],
+                                   cwd=directory, stdin=slave, stdout=slave, stderr=slave)
+        os.close(slave)
+        slave = None
+        deadline = time.monotonic() + 20
+        while process.poll() is None:
+            if time.monotonic() >= deadline:
+                raise PackError('Claude Desktop handoff timed out; run recover to reconcile imports.')
+            if io_select.select([master], [], [], .1)[0]:
+                try:
+                    chunk = os.read(master, 65536)
+                except OSError:
+                    break
+                output.extend(chunk)
+                if len(output) > 65536:
+                    raise PackError('Claude Desktop handoff exceeded its output limit.')
+        process.wait(timeout=2)
+        if process.returncode or ('Opening session ' + session_id) not in output.decode(errors='replace'):
+            raise PackError('Claude refused the native Desktop handoff: ' + output.decode(errors='replace')[-2000:])
+    finally:
+        if process is not None and process.poll() is None:
+            process.terminate()
+            process.wait(timeout=5)
+        if slave is not None:
+            os.close(slave)
+        os.close(master)
+
+
+def project_directory(config, directory):
+    # The native CLI's current path-key codec. A versioned compatibility boundary.
+    import re
+    key = re.sub(r'[^a-zA-Z0-9]', '-', str(directory))
+    if len(key) > 200:
+        raise PackError('Claude project path exceeds the qualified path-key boundary (200 characters).')
+    return config / 'projects' / key
+
+
+def write_new(path, data):
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    if path.exists() or path.is_symlink():
+        if path.is_symlink() or not path.is_file() or path.read_bytes() != data:
+            raise PackError('Refusing to overwrite existing context or transcript: ' + str(path))
+        return
+    with path.open('xb') as stream:
+        stream.write(data)
+        stream.flush()
+        os.fsync(stream.fileno())
+    path.chmod(0o600)
+
+
+def materialize(lib, name, selected, config):
+    manifest, revision = lib.load(name)
+    if manifest.get('startingContext', {}).get('kind') != 'fresh':
+        raise PackError('Claude import requires a fresh pack with reviewed role files; old Codex history is not translated.')
+    records = []
+    root = lib.root / 'claude'
+    for agent in selected:
+        safe_id(agent['set'])
+        safe_id(agent['id'])
+        key = name + '/' + agent['set'] + '/' + agent['id']
+        identity = root / 'identities' / (hashlib.sha256(key.encode()).hexdigest() + '.json')
+        if identity.exists():
+            record = json.loads(identity.read_text())
+            if record['sourceRevision'] != revision:
+                raise PackError('Existing Claude agent uses a different revision; build a new named pack to preserve its context.')
+            if record['importState'] != 'preparing':
+                records.append(record)
+                continue
+        else:
+            session_id = str(uuid.uuid4())
+            workspace = root / 'workspaces' / name / agent['set'] / agent['id']
+            record = {'key': key, 'pack': name, 'set': agent['set'], 'agent': agent['id'],
+                      'title': agent['title'], 'pinnedRequested': agent.get('pinned', False),
+                      'sourceRevision': revision, 'sourceCodexThreadId': agent['threadId'],
+                      'cliSessionId': session_id, 'desktopSessionId': 'local_' + session_id,
+                      'workspace': str(workspace),
+                      'transcript': str(project_directory(config, workspace) / (session_id + '.jsonl')),
+                      'importState': 'preparing', 'createdAt': now(), 'bootstrapUuid': str(uuid.uuid4())}
+            # Save allocation before any workspace/transcript write. Retrying a
+            # interrupted preparation uses the same IDs and compares old bytes.
+            atomic_json(identity, record)
+        original = pathlib.Path(manifest['threads'][agent['threadId']]['cwd'])
+        workspace = pathlib.Path(record['workspace'])
+        if workspace.is_symlink():
+            raise PackError('Claude workspace must not be a symlink')
+        workspace.mkdir(parents=True, exist_ok=True, mode=0o700)
+        resources = [r for r in manifest['resources'] if pathlib.Path(r['original']).is_relative_to(original)]
+        instructions = next((r for r in resources if pathlib.Path(r['original']).relative_to(original).as_posix() == 'AGENTS.md'), None)
+        if instructions is None:
+            raise PackError('Missing reviewed role instructions for ' + key)
+        for resource in resources:
+            relative = pathlib.Path(resource['original']).relative_to(original)
+            if '..' in relative.parts or any(p.is_symlink() for p in (workspace / relative).parents if p != lib.root.parent):
+                raise PackError('Unsafe context path: ' + str(relative))
+            # Never copy runtime state, prior tasks, scripts or credentials into a role.
+            if relative.suffix != '.md' or relative.as_posix() == 'context/TEAM.md':
+                continue
+            if relative.as_posix() == 'AGENTS.md':
+                relative = pathlib.Path('CLAUDE.md')
+            write_new(workspace / relative, lib.object(resource['content']).read_bytes())
+        session_id = record['cliSessionId']
+        transcript = pathlib.Path(record['transcript'])
+        note = (agent['title'] + '. You are this Topolo Agent Pack role in Claude Desktop. '
+                'Read CLAUDE.md and relevant context/ files before work. '
+                'This is starting context only; no assignment, claim or prior conversation is inherited. '
+                'Await a new human request. Coordination requires human authorization.')
+        rows = [{'parentUuid': None, 'isSidechain': False, 'userType': 'external',
+                 'cwd': str(workspace), 'sessionId': session_id, 'version': '2.1.289',
+                 'type': 'user', 'message': {'role': 'user', 'content': note},
+                 'uuid': record['bootstrapUuid'], 'timestamp': record['createdAt']},
+                {'type': 'custom-title', 'sessionId': session_id, 'customTitle': agent['title']}]
+        write_new(transcript, b''.join(canonical(row) + b'\n' for row in rows))
+        record['importState'] = 'prepared'
+        atomic_json(identity, record)
+        records.append(record)
+    team = ('# Claude pack roster\n\nThese are Claude Desktop session identities. '
+            'No task, claim, messaging authorization or hosted connection is granted by this roster.\n\n' +
+            '\n'.join('- ' + a['key'] + ' | ' + a['title'] + ' | ' + a['desktopSessionId'] for a in records) + '\n')
+    for record in records:
+        context = pathlib.Path(record['workspace']) / 'context'
+        write_new(context / ('TEAM-' + hashlib.sha256(team.encode()).hexdigest()[:16] + '.md'), team.encode())
+        pointer = context / 'TEAM.md'
+        if not pointer.exists():
+            write_new(pointer, b'# Claude team identities\n\nRead TEAM-*.md for immutable Claude roster snapshots. Use topolo-agent-pack status --harness claude for current membership. Only human-authorized coordination is permitted.\n')
+    return records
+
+
+def readback(records, app_data):
+    results = []
+    for record in records:
+        files = list((app_data / 'claude-code-sessions').glob('*/*/' + record['desktopSessionId'] + '.json'))
+        if len(files) != 1:
+            results.append({'key': record['key'], 'verified': False, 'reason': 'unique Desktop adoption record missing'})
+            continue
+        state = json.loads(files[0].read_text())
+        ok = (state.get('cliSessionId') == record['cliSessionId'] and
+              state.get('title') == record['title'] and
+              state.get('cwd') == record['workspace'] and not state.get('isArchived'))
+        results.append({'key': record['key'], 'desktopSessionId': record['desktopSessionId'],
+                        'verified': ok, 'completedTurns': state.get('completedTurns') or 0,
+                        'record': str(files[0])})
+    return results
+
+
+def parser():
+    p = argparse.ArgumentParser(description='Claude Code Desktop pack sessions (native sidebar import; full switch is not yet supported).')
+    p.add_argument('--store', default=os.environ.get('CODEX_PACK_HOME', str(pathlib.Path.home() / 'AgentPacks')))
+    p.add_argument('--claude-config', default=str(pathlib.Path.home() / '.claude'))
+    p.add_argument('--claude-data', default=str(pathlib.Path.home() / 'Library/Application Support/Claude'))
+    sub = p.add_subparsers(dest='command', required=True)
+    for action in ['add', 'switch', 'replace']:
+        q = sub.add_parser(action)
+        q.add_argument('source')
+        q.add_argument('--set', '--group', dest='sets', action='append')
+        q.add_argument('--agent', dest='agents', action='append')
+        q.add_argument('--catalog', action='store_true')
+        q.add_argument('--no-open', action='store_true')
+        q.add_argument('--import-only', action='store_true', help='Explicit incomplete native session import; does not activate pack settings')
+        q.add_argument('--claude-bin', default=find_binary())
+    for action in ['status', 'doctor', 'recover', 'list']:
+        sub.add_parser(action)
+    return p
+
+
+def main(argv):
+    args = parser().parse_args(argv)
+    try:
+        lib = Library(args.store)
+        app_data = pathlib.Path(args.claude_data).expanduser().resolve()
+        state_path = lib.root / 'claude/state.json'
+        with lib.lock():
+            state = json.loads(state_path.read_text()) if state_path.exists() else {'schemaVersion': 1, 'harness': 'claude', 'agents': []}
+            if args.command in {'status', 'doctor', 'recover', 'list'}:
+                proof = readback(state['agents'], app_data)
+                active_path = lib.root / 'claude/active.json'
+                pending_path = lib.root / 'claude/native-operation.json'
+                result = {**state, 'adoptionProof': proof, 'verifiedAgents': sum(p['verified'] for p in proof),
+                          'fullPackSwitchSupported': False, 'sidebarGroupsAndPinsVerified': False,
+                          'nativeRecordsRewritten': False, 'modelIdentityResponseVerified': False,
+                          'activationReady': False, 'modelAndPermissionSettingsVerified': False,
+                          'lastVerifiedActiveRoster': json.loads(active_path.read_text()) if active_path.exists() else None,
+                          'nativeRecoveryRequired': pending_path.exists(),
+                          'nativeRecoveryReplayed': False,
+                          'verificationBoundary': 'read-only adoption records; use the explicit native connection for current settings or recovery'}
+            else:
+                if (lib.root / 'claude/native-operation.json').exists():
+                    raise PackError('An unresolved native Claude operation blocks imports and preparation. Use topolo agent-packs recover with the explicit native connection; no effects are replayed.')
+                manifest, revision = lib.load(args.source)
+                chosen = select(manifest, args.sets, args.agents)
+                keys = {args.source + '/' + a['set'] + '/' + a['id'] for a in chosen}
+                outgoing = {a['key'] for a in state['agents']} - keys
+                if args.command in {'switch', 'replace'} and outgoing:
+                    raise PackError('Claude full-pack replacement is not qualified: native --desktop --resume cannot archive the outgoing roster. No changes were made. Use add for sidebar import.')
+                if not args.no_open and not args.import_only:
+                    raise PackError('Claude pack activation requires a qualified live backend for groups, pins, model and permission settings. No changes were made. --no-open prepares context; --import-only explicitly imports sessions without completing pack activation.')
+                records = materialize(lib, args.source, chosen, pathlib.Path(args.claude_config).expanduser().resolve())
+                combined = {a['key']: a for a in state['agents']}
+                combined.update({a['key']: a for a in records})
+                state = {**state, 'agents': list(combined.values()), 'updatedAt': now()}
+                # Durable recovery plan before asking Desktop to adopt a session.
+                atomic_json(state_path, state)
+                if not args.no_open:
+                    for record in records:
+                        if not readback([record], app_data)[0]['verified']:
+                            handoff(args.claude_bin, record['workspace'], record['cliSessionId'])
+                            deadline = time.monotonic() + 15
+                            while not readback([record], app_data)[0]['verified']:
+                                if time.monotonic() > deadline:
+                                    raise PackError('Desktop adoption not verified for ' + record['key'] + '; run recover.')
+                                time.sleep(.1)
+                        record['importState'] = 'desktop-adopted'
+                        atomic_json(state_path, state)
+                proof = readback(records, app_data)
+                result = {'harness': 'claude', 'state': 'prepared' if args.no_open else 'desktop-adopted',
+                          'selectedAgents': len(records), 'verifiedAgents': sum(p['verified'] for p in proof),
+                          'adoptionProof': proof, 'fullPackSwitchSupported': False,
+                          'previousCodexHistoryCopied': False, 'nativeRecordsRewritten': False,
+                          'sidebarGroupsAndPinsVerified': False, 'activationReady': False,
+                          'modelAndPermissionSettingsVerified': False}
+        print(json.dumps(result, indent=2))
+        return 0
+    except (PackError, OSError, ValueError, KeyError, subprocess.SubprocessError) as exc:
+        print('topolo-agent-pack (Claude): ' + str(exc), file=sys.stderr)
+        return 2

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

@@ -15,7 +15,7 @@ import time
 import uuid
 
 from . import __version__
-from . import native, live, fresh, blueprint
+from . import native, live, fresh, blueprint, execution
 from .storage import Library, PackError, atomic_json, canonical, component_key, now, read_json, references, safe_id, select, sync_tree
 
 def emit(value):
@@ -234,6 +234,7 @@ def apply_plan(lib,plan,args):
             if local_config.exists():
                 shutil.copyfile(local_config,runtime/'home'/'config.toml');(runtime/'home'/'config.toml').chmod(0o600)
         if old_runtime and old_runtime!=runtime and (old_runtime/'desktop-view.json').exists():shutil.copyfile(old_runtime/'desktop-view.json',runtime/'desktop-view.json')
+        execution.compile_runtime(lib, target_components, runtime)
         journal['phase']='staged';atomic_json(jpath,journal)
         if old_runtime and old_runtime!=runtime and (old_runtime/'home/auth.json').exists():
             shutil.copyfile(old_runtime/'home/auth.json',runtime/'home/auth.json');(runtime/'home/auth.json').chmod(0o600)
@@ -313,6 +314,8 @@ def parser():
         if action=='replace': q.add_argument('--target')
         if action=='switch': q.add_argument('--fresh',action='store_true',help='Use the captured source instead of resuming a previously saved workbench')
     q=sub.add_parser('plan');q.add_argument('action',choices=['add','replace','switch']);q.add_argument('source');selection(q);q.add_argument('--target');q.add_argument('--fresh',action='store_true')
+    q=sub.add_parser('policy',help='Render portable role settings for review; never changes live sessions')
+    q.add_argument('source');selection(q);q.add_argument('--output')
     for command in ['connect','remote-context','remember','artifact','artifact-get','remote-recover']:
         q=sub.add_parser(command,help='Use public Topolo Agent continuity and Bytes artifact contracts')
         q.add_argument('name');q.add_argument('--environment',choices=['development','staging','production'],required=True)
@@ -335,6 +338,22 @@ def parser():
     return p
 
 def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    harness = 'codex'
+    explicit_harness = '--harness' in argv
+    if '--harness' in argv:
+        at = argv.index('--harness')
+        if at + 1 >= len(argv):
+            parser().error('--harness requires codex or claude')
+        harness = argv[at + 1]
+        del argv[at:at + 2]
+    policy_command = 'policy' in argv
+    if harness == 'claude' and not policy_command:
+        from . import claude
+        return claude.main(argv)
+    if harness not in {'codex', 'claude'}:
+        print('topolo-agent-pack: Unsupported harness: ' + harness, file=sys.stderr)
+        return 2
     args=parser().parse_args(argv)
     try:
         lib=Library(args.store)
@@ -344,7 +363,15 @@ def main(argv=None):
             emit(result)
             return 0
         with lib.lock():
-            if args.command=='capture':
+            if args.command=='policy':
+                from . import policy
+                manifest,revision=lib.load(args.source)
+                result=policy.render(manifest,revision,select(manifest,args.sets,args.agents),
+                                     (harness,) if explicit_harness else ('codex','claude'))
+                if args.output:
+                    from .claude import write_new
+                    write_new(pathlib.Path(args.output).expanduser().absolute(), canonical(result)+b'\n')
+            elif args.command=='capture':
                 safe_id(args.name)
                 active=lib.active();template=None
                 if args.source_home: home=pathlib.Path(args.source_home)

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

@@ -0,0 +1,154 @@
+"""Per-role defaults for the owned Codex proxy, with explicit native read-back.
+
+No model turns are created here. A manifest is intent, never activation proof.
+Conflicting frontend settings are rejected instead of silently broadening the
+reviewed role. Changing that intent requires rebuilding the selected policy.
+"""
+import copy
+import hashlib
+import json
+import pathlib
+import sqlite3
+import subprocess
+import tempfile
+from contextlib import closing
+
+from . import policy
+from .storage import PackError, atomic_json, component_key, read_json
+
+
+def compile_runtime(lib, components, runtime):
+    runtime = pathlib.Path(runtime)
+    with closing(sqlite3.connect('file:' + str(runtime / 'home/state_5.sqlite') + '?mode=ro', uri=True)) as db:
+        cwds = dict(db.execute('SELECT id,cwd FROM threads'))
+    rows = []
+    for component in components:
+        manifest, revision = lib.load(component['sourcePack'], component['revision'])
+        matches = [a for a in manifest['agents'] if component_key(a) == component['key'] and a['threadId'] == component['threadId']]
+        if len(matches) != 1 or component['threadId'] not in cwds:
+            raise PackError('Execution policy has no unique owned role: ' + component['key'])
+        rows.append({'key': component['key'], 'threadId': component['threadId'],
+                     'sourceRevision': revision, 'cwd': cwds[component['threadId']],
+                     'settings': policy.settings(matches[0], 'codex')['nativeSettings']})
+    document = {'format': 'topolo-codex-runtime-execution', 'schemaVersion': 1,
+                'roles': rows, 'applied': False, 'modelTurnsStarted': False}
+    # Construct/validate fully before installing intent in a staged runtime.
+    ExecutionGate(document)
+    atomic_json(runtime / 'execution-policy.json', document)
+    return document
+
+
+class ExecutionGate:
+    def __init__(self, document):
+        if document.get('format') != 'topolo-codex-runtime-execution' or document.get('schemaVersion') != 1:
+            raise PackError('Unqualified runtime execution policy')
+        self.roles = {}; self.pending = {}; self.verified = set(); self.catalog = {}
+        for role in document['roles']:
+            tid = role['threadId']; spec = role['settings']
+            if tid in self.roles or not pathlib.Path(role['cwd']).is_absolute():
+                raise PackError('Duplicate thread or non-absolute role workspace')
+            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['approval_policy'] != 'on-request' or spec['approvals_reviewer'] != 'user' or
+                    spec['sandbox_mode'] not in {'read-only', 'workspace-write'} or
+                    spec['sandbox_workspace_write'] != {'network_access': False, 'writable_roots': [],
+                                                       'exclude_slash_tmp': True, 'exclude_tmpdir_env_var': True} or
+                    spec['apps'] != {'_default': {'default_tools_approval_mode': 'writes'}}):
+                raise PackError('Unqualified role execution settings')
+            self.roles[tid] = copy.deepcopy(role)
+
+    def set_catalog(self, result):
+        self.catalog = {row['model']: {e['reasoningEffort'] for e in row['supportedReasoningEfforts']}
+                        for row in result['data']}
+
+    def sandbox(self, role):
+        if role['settings']['sandbox_mode'] == 'read-only':
+            return {'type': 'readOnly', 'networkAccess': False}
+        return {'type': 'workspaceWrite', 'networkAccess': False, 'writableRoots': [role['cwd']],
+                'excludeSlashTmp': True, 'excludeTmpdirEnvVar': True}
+
+    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 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 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 method == 'thread/resume':
+            wanted['sandbox'] = spec['sandbox_mode']
+            wanted['config'] = {'model_reasoning_effort': spec['model_reasoning_effort'],
+                                'sandbox_workspace_write': spec['sandbox_workspace_write'], 'apps': spec['apps']}
+            self.verified.discard(tid)
+        else:
+            if tid not in self.verified:
+                raise PackError('Role needs a verified native resume before starting a turn')
+            wanted.update(effort=spec['model_reasoning_effort'], sandboxPolicy=self.sandbox(role))
+        for key, expected in wanted.items():
+            if params.get(key) is not None and params[key] != expected:
+                raise PackError('Frontend ' + key + ' conflicts with the reviewed role policy')
+            params[key] = copy.deepcopy(expected)
+        value['params'] = params
+        if method == 'thread/resume': self.pending[str(value['id'])] = tid
+        return value
+
+    def reply(self, value):
+        tid = self.pending.pop(str(value.get('id')), None)
+        if tid is None: return value
+        self.verified.discard(tid)
+        if 'error' in value: return value
+        role = self.roles[tid]; spec = role['settings']; result = value.get('result', {})
+        expected = {'model': spec['model'], 'cwd': role['cwd'], 'approvalPolicy': spec['approval_policy'],
+                    'approvalsReviewer': spec['approvals_reviewer'], 'reasoningEffort': spec['model_reasoning_effort'],
+                    'sandbox': self.sandbox(role)}
+        sandbox = result.get('sandbox', {})
+        # Native responses can omit false read-only networkAccess defaults.
+        actual = copy.deepcopy(result)
+        if sandbox.get('type') == 'readOnly': actual['sandbox'] = {'type': 'readOnly', 'networkAccess': sandbox.get('networkAccess', False)}
+        if result.get('thread', {}).get('id') != tid or any(actual.get(k) != v for k, v in expected.items()):
+            return {'id': value['id'], 'error': {'code': -32000,
+                    'message': 'Native role settings differ from the reviewed policy; model work is blocked'}}
+        self.verified.add(tid)
+        return value
+
+    def status(self):
+        return {'configuredRoles': len(self.roles), 'nativeResumeVerifiedRoles': sorted(self.verified),
+                'requested': [{'key': r['key'], 'threadId': tid, 'settings': r['settings']} for tid, r in self.roles.items()],
+                'appToolApprovalReadbackVerified': False, 'modelIdentityResponseVerified': False}
+
+
+def load_gate(runtime):
+    path = pathlib.Path(runtime) / 'execution-policy.json'
+    return ExecutionGate(read_json(path)) if path.exists() else None
+
+
+def qualify_protocol(binary, run=subprocess.run):
+    """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'}}
+    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)
+        if result.returncode:
+            raise PackError('Installed Codex protocol export refused; no backend started')
+        hashes = {}
+        for name, fields in required.items():
+            matches = list(pathlib.Path(temp).rglob(name + '.json'))
+            if len(matches) != 1:
+                raise PackError('Installed Codex protocol has no unique ' + name)
+            data = matches[0].read_bytes(); schema = json.loads(data)
+            if not fields <= set(schema.get('properties', {})):
+                raise PackError('Installed Codex protocol settings are incompatible: ' + name)
+            hashes[name] = hashlib.sha256(data).hexdigest()
+    return {'boundary': 'offline installed executable protocol export', 'schemas': hashes,
+            'modelTurnsStarted': False}