@aiwg/cockpit 2026.7.21 → 2026.7.24

package/README.md

@@ -8,8 +8,21 @@ Observe live agent work, attach to sessions, handle approvals, launch runtime
 targets, and coordinate AIWG actions from one local operator surface. Cockpit
 fronts the AIWG CLI and the agentic-sandbox executor; it does not replace either.
 
+If AIWG is not already connected to your project, paste this into your
+supported provider first:
+
+```text
+Install or repair AIWG for this project by following
+https://raw.githubusercontent.com/jmagly/aiwg/main/setup.aiwg.yaml
+Explain the plan before changing anything, preserve my existing work, and ask
+me only for choices you cannot safely determine.
+```
+
 ```bash
 npm i -g aiwg        # install the base AIWG CLI
+aiwg use all --provider <provider>
+aiwg index build --all
+aiwg regenerate --provider <provider>
 aiwg use cockpit     # install the opt-in Cockpit package, version-locked to AIWG
 aiwg cockpit         # launch the local Bridge + web UI
 ```
@@ -34,6 +47,9 @@ version to the installed AIWG version.
 
 ```bash
 npm i -g aiwg
+aiwg use all --provider <provider>
+aiwg index build --all
+aiwg regenerate --provider <provider>
 aiwg use cockpit
 aiwg cockpit --status
 aiwg cockpit
@@ -259,6 +275,33 @@ QEMU/VM launches. Cockpit does not replace attached sessions when provisioning;
 it refreshes inventory and leaves concurrency and resource admission to
 agentic-sandbox.
 
+For VM rows, Inventory renders provider-aware fast-start actions only when the
+executor advertises the matching instance capability. Cloud Hypervisor rows can
+offer snapshot, restore, fork, and warm-pool handoff. Libvirt rows can offer
+checkpoint, restore, and warm-pool handoff when advertised. Cockpit sends
+restore, fork, and warm-pool requests through the unified sandbox
+`runtime_options` launch intent, polls the async operation resource to terminal
+state, and records request/terminal audit evidence through the Bridge. VFIO
+constraint exclusions keep unsafe fast-start actions disabled with the
+executor-provided reason.
+
+### VM provider and GPU/VFIO posture
+
+The Launch instance modal uses sandbox loadout compatibility metadata instead
+of assuming every VM provider supports every launch mode. Operators can select
+an advertised VM provider and GPU/VFIO posture. Required GPU passthrough sends
+`required_capabilities: ['device.vfio']`, excludes fast-start capabilities, and
+sets `fallback_mode: 'fail'` so Cockpit requests a cold VM launch rather than a
+snapshot/checkpoint path that would be unsafe for assigned devices. Inventory
+then displays assigned VFIO devices and executor-provided incompatibility
+reasons; it does not make VFIO generally available on hosts or loadouts that
+cannot provide it.
+
+The Apple Silicon validation path is preview-only. The sandbox `v2026.7.14`
+macOS artifact is an unsigned, unnotarized developer package, and native macOS
+is expected to lack Linux VM, Cloud Hypervisor, VFIO/GPU, vsock, and systemd
+capabilities unless the executor reports otherwise.
+
 ### Recover stale agents
 
 When a container, Docker, or VM runtime is still running but its agent
@@ -271,18 +314,25 @@ resolve an agent id.
 The Bridge handles recovery through:
 
 1. executor-owned reconnect endpoints when the sandbox exposes one, then
-2. local Docker fallback: `docker exec <container> agent-reconnect`, or
+2. local Docker fallback, only when
+   `AIWG_COCKPIT_LOCAL_DOCKER_FALLBACK=1`: `docker exec <container> agent-reconnect`,
+   or
 3. VM fallback (#1778): the same reconnect SIGHUP delivered through the libvirt
    qemu-guest-agent channel (`virsh qemu-agent-command <domain> guest-exec
-   pkill -HUP -x agent-client`). Sessions survive reconnect on agentic-sandbox
+   pkill -HUP -x agent-client`). The libvirt fallback is automatic on Linux;
+   on non-Linux hosts set `AIWG_COCKPIT_LOCAL_LIBVIRT_FALLBACK=1` for explicit
+   local-development use. Sessions survive reconnect on agentic-sandbox
    2026.7.8+ agents; older agents preserve only detached tmux sessions
    (agentic-sandbox#634).
 
 The Docker fallback requires sandbox images that include the `agent-reconnect`
 helper (agentic-sandbox v2026.7.5+ images); the VM fallback requires virsh
-access to the domain from the Bridge host. If **Reconnect** reports that no
-reconnect path is available, rebuild or repull the sandbox image, then start the
-instance again. For host targets, prefer starting Cockpit with the host daemon:
+access to the domain from the Bridge host. If **Reconnect** reports
+`local_docker_fallback_disabled` or `local_libvirt_fallback_disabled`, either
+let the sandbox handle reconnect through its own endpoint or enable the matching
+local-development fallback intentionally. If no reconnect path is available,
+rebuild or repull the sandbox image, then start the instance again. For host
+targets, prefer starting Cockpit with the host daemon:
 
 ```bash
 AIWG_COCKPIT_START_HOST_DAEMON=1 npm run cockpit:up
@@ -317,6 +367,7 @@ Tests run **at stages** — committed harnesses, never `/tmp` rigs (#1635):
 | **Dev e2e** (full control-plane chain: health→inventory→create session→attach) | `npm run e2e:cockpit-dev` | **real**, safe-skip when absent | non-blocking |
 | **Daily Linux operator gate** (protected auth + host/container + recovery + upgrade/rollback, #1842) | `npm run uat:cockpit-daily` | **real**, required/fail-closed | operator-scheduled |
 | **Release matrix** (host/docker/vm + provider workload, #1621) | `npm run uat:cockpit-live:matrix` | **real**, all three families | release gate |
+| **Provider-aware VM fast start** (#1843) | `npm --prefix apps/cockpit/web run test -- Inventory.test.tsx` · `node apps/cockpit/bridge/src/smoke.mjs` | **mock** plus live executor for release signoff | required before enabling new VM controls |
 
 ```bash
 npm --prefix apps/cockpit run check     # build web + typecheck + render/a11y tests + smokes + PoCs
@@ -333,7 +384,10 @@ host/container working-directory expectations, cleanup boundary, and report
 schema are documented in
 [Cockpit Daily Linux Operator Gate](../../docs/cockpit/daily-operator-gate.md).
 VM and Apple remain reported preview tiers and do not block the first Linux
-supported result.
+supported result. Apple preview evidence is based on the agentic-sandbox
+developer package, `darwin/arm64` host runtime discovery, and Docker Desktop
+runtime posture; production signing/notarization is tracked separately and is
+not required to pass the Cockpit Linux gate.
 
 The React UI is also browser-verified per surface (see `.playwright-mcp/cockpit-*.png`).
 Conformance (`agentic-sandbox-conformance`) was 33 pass / 0 fail / 17 skip; the