agent-collab: add reliable shared-HOME governance

.claude-plugin/marketplace.base.json

@@ -9,7 +9,7 @@
   "plugins": [],
   "metadata": {
     "description": "Agent collaboration plugin marketplace",
-    "version": "3.2.0",
+    "version": "3.3.0",
     "repository": "https://github.com/sumitake/agent-collab"
   }
 }

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "agent-collab",
       "description": "Unified dynamic-host collaboration package. Centralized skills and async coordination work without legacy packages; every model-execution route requires the verified signed plugin artifact.",
-      "version": "3.2.0",
+      "version": "3.3.0",
       "author": {
         "name": "John Osumi"
       },
@@ -32,7 +32,7 @@
   ],
   "metadata": {
     "description": "Agent collaboration plugin marketplace",
-    "version": "3.2.0",
+    "version": "3.3.0",
     "repository": "https://github.com/sumitake/agent-collab"
   }
 }

AGENTS.md

@@ -12,8 +12,8 @@ post-install hook, or provider executor source.
   client behavior, migration, and release-safety checks.
 - Native runtime implementation and build/sign credentials stay in a separate
   private producer that contributors do not need to access.
-- This repository may receive only final signed native artifacts and their
-  size/hash/signature manifest metadata.
+- This repository may receive only final signed native standalone bundles and
+  their closed per-member/whole-bundle manifest metadata.
 - Never place executor source, bytecode, private absolute paths, or retired
   package trees in the active source or release archive.
 
@@ -49,10 +49,11 @@ requires explicit configuration and fails closed; non-governance use carries an
 independence warning. Policy-only safe mode preserves only validated async
 inbox/coordination seams and returns typed unavailable for every model route.
 
-The native client accepts no path override, resolves only the manifest-selected
-artifact beneath the plugin root, rejects symlinks and traversal, verifies
-platform/architecture/size/hash and macOS signing/notarization, scrubs the
-environment, and uses only the fixed protocol.
+The native client accepts no path or member override, resolves only the
+manifest-selected closed bundle beneath the plugin root, rejects links,
+aliases, traversal, writable or unknown members, verifies per-member
+architecture/type/size/hash/signing plus whole-bundle identity and macOS
+notarization, scrubs the environment, and uses only the fixed protocols.
 
 ## Clean public repository invariant
 

README.md

@@ -1,6 +1,6 @@
 # agent-collab
 
-This repository distributes one package: **agent-collab** (v3.2.0). It gives
+This repository distributes one package: **agent-collab** (v3.3.0). It gives
 Claude, Codex, Antigravity, OpenCode, ZCode, and custom primary hosts the same
 dynamic collaboration surface without publishing provider executors or
 maintaining host-specific plugin copies.
@@ -10,7 +10,8 @@ skills, migration tooling, fail-closed client, contribution governance, and
 release-safety checks. Provider runtime implementation, build credentials, and
 signing infrastructure remain in a separate private build/sign system. A
 policy-only release contains no native runtime; an activation release may import
-only the final signed and notarized artifact plus verification metadata. No
+only the final signed and notarized standalone bundle plus its closed manifest
+and verification metadata. No
 downloader, post-install hook, runtime cache, raw provider recipe, or executable
 source copy is shipped here.
 
@@ -23,9 +24,26 @@ Contributors need no access to the private build/sign system. See
 
 | Package | Version | Role |
 |---|---:|---|
-| `agent-collab` | 3.2.0 | Unified skills, dynamic host policy, migration preflight, and verified native-runtime client |
-
-## What's new - v3.2.0
+| `agent-collab` | 3.3.0 | Unified skills, dynamic host policy, migration preflight, and verified native-runtime client |
+
+## What's new - v3.3.0
+
+- Add a distinct broker-only `gemini/governance` contract using exact Gemini
+  3.1 Pro/high selection and complete artifact-bound proof validation. Gemini
+  advisory and long-context remain ordinary read-only actions and cannot emit
+  governance evidence.
+- Advance the native runtime to manifest schema 2, contract 3, and broker
+  transport 2. Bind the public coordinator, closed standalone-bundle identity,
+  lifecycle state, release gates, generated skills, and response parser to the
+  same route matrix while the provider protocol remains version 1.
+- Adopt canonical passwd HOME as the managed-provider reliability policy while
+  retaining closed environments, family exclusion, route authority, provider
+  state serialization, bounded lifecycle, and no raw CLI fallback.
+- Move Codex advisory behind the same broker, guardian, acknowledged gate, and
+  cancellation lifecycle as every other provider route; only local runtime
+  management remains a direct exact-artifact operation.
+
+The v3.2.0 provider-broker changes remain in force:
 
 - Add explicit zero-idle launchd socket activation for managed Gemini,
   OpenCode, Grok, and Composer routes, with digest-bound state and no direct
@@ -112,52 +130,64 @@ flowchart LR
     S --> N["Observed non-model seam<br/>host async-inbox readiness only"]
     S --> C["Verified plugin-relative native runtime client"]
     C --> B["Per-user launchd socket<br/>zero idle process"]
-    B --> X1["Managed Gemini, OpenCode,<br/>Grok 4.5, and Composer"]
-    C --> X2["Managed Codex and<br/>runtime management"]
-    W["Private build/sign system"] -. "signed and notarized artifact" .-> C
+    B --> Q["Signed guardian + acknowledged gate"]
+    Q --> X1["Managed Codex, Gemini, OpenCode,<br/>Grok 4.5, and Composer"]
+    C --> X2["Local runtime management"]
+    W["Private build/sign system"] -. "signed and notarized bundle" .-> C
     W -. "same exact digest" .-> B
 ```
 
-The plugin runtime client accepts no binary override. It selects only the
-platform/architecture entry in `runtime-manifest.json`, requires the fixed
-plugin-relative path, rejects symlinks and parent traversal, verifies exact
-size and SHA-256, and on macOS verifies the declared signing team plus
-notarization assessment. It then launches a fixed versioned JSON protocol with
-a scrubbed environment. Every artifact advertises its exact route/action contracts;
+The plugin runtime client accepts no binary or member override. It selects only
+the Darwin-arm64 standalone-bundle entry in `runtime-manifest.json`, requires
+the fixed plugin-relative bundle and entrypoint, rejects links, path aliases,
+unknown members, writable modes, and parent traversal, then verifies every
+member's size, SHA-256, Mach-O type, architecture, minimum macOS, signing
+profile, and the domain-separated whole-bundle identity. Production also
+requires the pinned Developer ID team and notarization assessment. It then uses
+the fixed broker/provider protocols with a scrubbed environment. Every artifact
+advertises its exact route/action contracts;
 the client rejects unadvertised rows, mismatched route/authority combinations,
 and author-family provenance drift. Missing, blocked, unsigned, mismatched, or
 unsupported artifacts fail closed with typed status.
 
-Gemini, OpenCode, Grok, and Composer use a digest-bound, per-user launchd Unix socket. Launchd
+Codex, Gemini, OpenCode, Grok, and Composer use a digest-bound, per-user launchd Unix socket. Launchd
 owns the mode-`0600` socket and starts the exact signed runtime only when a
 request arrives. The broker accepts one bounded request, runs it through the
 managed backend, returns one bounded response, and exits; there is no
 `KeepAlive`, `RunAtLoad`, polling loop, interval, calendar trigger, or resident
-agent process. Codex and runtime-management calls retain the fixed direct
-exact-artifact path. Missing, stale, or mismatched broker state is a typed
+agent process. At idle, launchd retains only the job registration and one
+mode-`0600` Unix listening socket; the installed immutable bundle consumes disk
+but no provider process, polling CPU, provider memory, or network traffic. Only
+local runtime-management calls retain the fixed direct exact-entrypoint path.
+Missing, stale, or mismatched broker state is a typed
 failure and never falls back to direct execution for any broker-only route.
 The broker removes the Codex Desktop outer-Seatbelt marker before backend
 dispatch because socket activation does not inherit the client's Seatbelt.
 Every brokered Grok and Composer attempt must therefore build and validate its
-own nested read-only sandbox. Provider children receive closed,
-backend-specific environment allowlists rooted in fresh private call
-directories rather than the broker's ambient environment. Broker frames cannot
+own nested read-only sandbox. Provider children receive closed backend-specific
+environment allowlists with canonical passwd HOME for reliable authenticated
+state plus fresh private temporary/cwd roots rather than the broker's ambient
+environment. Grok uses real serialized `~/.grok`; OpenCode keeps private XDG
+roots and selected-provider auth; Codex keeps a sealed per-call `CODEX_HOME`,
+SQLite, and XDG overlay. Provider-specific policy overlays may narrow
+credentials or tools without replacing process HOME. Broker frames cannot
 invoke local runtime-management actions.
-If the client disconnects, the broker propagates cancellation through managed
-OpenCode, Grok, and Composer execution/readiness, reaps provider child groups,
+If the client disconnects, the broker propagates cancellation through every
+managed provider route, reaps provider child groups,
 and discards partial output. Disconnect-driven cancellation is never retried;
 when too little deadline remains to establish the managed boundary, the route
 returns typed `timeout` before provider setup.
-The current signed facade still returns typed `containment_error` for Gemini
-before Google provider setup because no completion-only Google transport is
-proven; socket activation establishes the safe transport boundary but does not
-silently activate an agentic CLI.
+Gemini uses the managed agy backend with canonical passwd HOME, mandatory PTY,
+serialized state, and write containment. `gemini/governance` is distinct from
+advisory/long-context and emits complete artifact-bound broker proof; ordinary
+Gemini output cannot be presented as governance evidence.
 
 The broker rejects cross-UID, stale/replayed, substituted-artifact, and
 connecting-process mismatches. It does not claim to protect provider
 credentials from arbitrary malicious code already running as the same operator
-UID, which can already read that user's auth state. The exact immutable runtime
-path and digest are revalidated for each request.
+UID, which can already read that user's auth state. The exact immutable bundle,
+entrypoint path, member inventory, and identity are revalidated for each
+request.
 
 The expected Apple Developer ID Team ID is pinned in the public
 `plugins/agent-collab/signing_policy.py` policy source, independently of the
@@ -173,11 +203,11 @@ client decodes and verifies the representation before launch; neither the
 coordinator nor the native runtime may reconstruct the artifact from a prompt
 copy.
 
-The repository intentionally contains no native runtime artifact yet. Native
+The repository intentionally contains no native runtime bundle yet. Native
 Gemini, Codex, OpenCode, Grok 4.5, and Composer routes remain unavailable until
-the private build/sign integration supplies the real artifact, manifest digest,
+the private build/sign integration supplies the real bundle, manifest digest,
 and complete contract declaration. Deterministic tests use temporary fixture
-executables only. The release gate requires every platform artifact to expose
+bundles only. The release gate requires every platform artifact to expose
 the complete required contract matrix. Retirement and a policy-only release may
 land before native parity, but an activation release cannot launch any provider
 until the signed runtime exposes the complete matrix, including Composer.
@@ -188,29 +218,32 @@ until the signed runtime exposes the complete matrix, including Composer.
    repository; private runtime changes remain inside the build/sign system.
 2. The private producer runs its containment, provenance, and
    authority-boundary tests without exporting implementation source.
-3. The private producer builds the Darwin-arm64 binary, signs it with hardened
-   runtime, notarizes it, and records size/hash/team metadata.
+3. The private producer builds one Darwin-arm64 standalone bundle, signs every
+   nested Mach-O before the entrypoint with hardened runtime, notarizes the
+   closed bundle, and records whole-bundle plus per-member evidence.
 4. A policy-only plugin release omits the runtime and keeps every native route
-   typed unavailable. An activation release imports only the final binary and
-   manifest metadata plus the exact third-party notice/license tree; no private
-   source implementation crosses the boundary.
+   typed unavailable. An activation release imports only the final bundle,
+   closed manifest metadata, and exact third-party notice/license tree; no
+   private source implementation crosses the boundary.
 5. Plugin CI validates both Claude and Codex manifests/marketplaces, schemas,
    skills, migration behavior, runtime fixtures, the dependency-free secret
    scan, CodeQL security analysis, release consistency, and public-export
    safety.
 6. A policy-only signed-tag release proves the runtime manifest is empty and
    the archive contains no runtime. For activation, a macOS verification job
-   binds codesign, notarization, manifest, artifact digest, and commit SHA into
-   release evidence before the publish job may include the binary. SPDX 2.3
+   binds every member's codesign/Mach-O evidence, entrypoint notarization,
+   manifest digest, whole-bundle identity, and commit SHA before the publish job
+   may include the bundle. SPDX 2.3
    evidence distinguishes project-owned PolyForm material from the embedded
    CPython, Nuitka, and incorporated third-party components.
 7. Hosts update one package, run the migration doctor, restart, and verify the
    resolved profile plus eligible routes. Activation hosts run the co-packaged
    `runtime_setup.py status` and `prepare` commands, then explicitly run
-   `install-broker` before enabling Gemini, OpenCode, Grok, or Composer. Managed Grok device
+   `install-broker` before enabling Codex, Gemini, OpenCode, Grok, or Composer. Managed Grok device
    login is exposed only as `runtime_setup.py login-grok`.
-8. Broker updates copy the verified artifact and manifest into an immutable
-   artifact-plus-manifest digest directory, atomically replace the closed
+8. Broker updates copy only the manifest-listed regular bundle members and
+   manifest into an immutable artifact-plus-manifest digest directory,
+   atomically replace the closed
    launchd plist/state, verify the exact job and socket, activate one
    protocol-only request, and prove the broker process exits. Failed updates
    restore the complete prior verified state, including its rollback target,
@@ -350,8 +383,8 @@ report managed independent visual review unavailable; they never invent a
 path-based attachment or raw-provider fallback.
 
 Explicit `target=gemini`, `target=codex`, and `target=opencode` requests are
-fail-closed and never silently substituted. Gemini is read-only
-advisory/long-context; Codex advisory and OpenCode plan/workspace-write authority are
+fail-closed and never silently substituted. Gemini has separate read-only
+advisory, governance, and long-context actions; Codex advisory and OpenCode plan/workspace-write authority are
 sealed separately and never promote or demote into one another. Codex build is
 a resolvable mutation-capable request but returns typed unavailable until a
 hardened mutation backend exists; it never widens advisory.
@@ -361,7 +394,7 @@ architecture, governance, and huge-context actions; `target=composer` is
 constrained output-only code generation. Composer has no file, shell, test,
 worktree, PR, or merge authority. Both remain deterministically temporarily
 unavailable until the signed runtime advertises their exact route/action contracts.
-Grok/Composer requests are broker-only and never fall back to direct runtime
+Codex, Gemini, OpenCode, Grok, and Composer requests are broker-only and never fall back to direct runtime
 execution. Grok prose accepts only an explicit `EndTurn` terminal; exact
 `Cancelled` is a named non-success with no retained assistant text and may be
 retried once only when more than ten seconds remain under the original

changelog.d/2026-07-13-gemini-governance.md

@@ -0,0 +1,17 @@
+### agent-collab 3.3.0 — managed Gemini governance and reliable provider state
+
+- Add a distinct broker-only `gemini/governance` action with exact Gemini 3.1
+  Pro/high selection, immutable artifact binding, shared-HOME/PTY containment
+  evidence, response hashing, and public-client proof-digest validation.
+- Keep Gemini advisory and long-context separate and explicitly ineligible as
+  governance evidence; automatic governance now maps Gemini and Grok to their
+  explicit governance actions while Codex remains advisory.
+- Advance the signed-runtime route contract to version 2 across policy,
+  manifests, schemas, archive/release verification, generated skills, and
+  deterministic tests.
+- Document canonical passwd HOME as the managed-provider reliability policy
+  without relaxing family exclusion, authority separation, bounded lifecycle,
+  or the prohibition on raw provider fallbacks.
+- Make Codex, Gemini, OpenCode, Grok, and Composer uniformly broker-only and
+  bind provider startup to the signed guardian's acknowledged pre-exec gate;
+  only local runtime management retains direct exact-artifact execution.

changelog.d/2026-07-13-provider-broker.md

@@ -1,9 +1,15 @@
-### agent-collab 3.2.0 — zero-idle provider broker
+### agent-collab 3.3.0 — closed standalone provider bundle
 
 - Route managed Gemini, OpenCode, Grok, and Composer requests through an explicit, digest-bound
   launchd socket broker that starts for one request and returns to zero idle
   processes. Add closed install, status, rollback, and uninstall lifecycle
   commands with transactional prior-version restoration and no direct fallback.
+- Replace the failed onefile launch path with manifest schema 2, native contract
+  3, and broker transport 2 over one closed standalone bundle. Bind its identity
+  to the sorted role/mode/size/digest/Mach-O facts of every member; publish only
+  exact immutable `0500` files; verify the kernel-reported entrypoint and the
+  complete lifecycle state before provider dispatch. Provider protocol 1 and
+  all existing route-authority boundaries remain unchanged.
 - Resolve the OpenCode model per request from live OpenCode/ZCode observation,
   explicit central configuration, or the fixed `opencode/glm-5.2` preset while
   ignoring ambient and row-level model fallbacks.