vmware-pilot 2.3.0__tar.gz → 2.4.1__tar.gz

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-pilot",
   "displayName": "VMware Pilot",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Multi-step workflow orchestration for VMware MCP skills with approval gates and rollback.",
   "author": {
     "name": "Wei Zhou",

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-pilot==2.3.0",
+        "vmware-pilot==2.4.1",
         "vmware-pilot-mcp"
       ]
     }

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-pilot
-Version: 2.3.0
+Version: 2.4.1
 Summary: VMware workflow orchestration — multi-step state machine with approval gates
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Pilot
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Pilot
@@ -9,7 +9,7 @@ Project-URL: Changelog, https://github.com/vmware-skills/VMware-Pilot/blob/main/
 Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
 License-Expression: MIT
 Requires-Python: >=3.10
-Requires-Dist: mcp[cli]<2.0,>=1.28
+Requires-Dist: mcp[cli]<2.0,>=1.30
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: typer<1.0,>=0.12
 Requires-Dist: vmware-policy<2.0,>=1.21.0
@@ -19,6 +19,8 @@ Description-Content-Type: text/markdown
 
 # VMware Pilot
 
+For a read-only check of this skill with your model and agent host, use the shared [model-fit self-test](https://github.com/vmware-skills/marketplace/blob/main/MODEL_FIT_SELF_TEST.md) in the marketplace root.
+
 > **Author**: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com
 > This is a community-driven project by a VMware engineer, not an official VMware product.
 > For official VMware developer tools see [developer.broadcom.com](https://developer.broadcom.com).
@@ -89,20 +91,21 @@ pip install --no-index --find-links dist vmware-pilot
 | `create_workflow` | Create custom workflow from step list (refused if a destructive step has no approval gate before it) |
 | `run_workflow` | Execute workflow, pauses at approval gates |
 | `get_workflow_status` | Query state + diff report + audit log |
-| `approve` | Human approval, continue execution |
+| `approve` | Human approval, continue execution. Refused while steps before the gate are `not_executed`, until `acknowledge_not_executed=True` says you ran them |
 | `rollback` | Explicit, best-effort undo of steps pilot recorded as succeeded — never automatic. Previews (`blast_radius`) unless `confirm=True` |
 | `cancel_workflow` | Cancel a workflow — move it to the terminal CANCELLED state. Previews (`blast_radius`) unless `confirm=True` |
 
 ## Built-in Templates (15)
 
 `n` is the number of VMs (or drift items); ranges depend on which optional parameters are set.
-`clone_and_test` has 7 steps when `change_spec` is a guest command (an extra gate before it runs
+`clone_and_test` needs `snapshot_name` (the snapshot to clone from), resizes staging while it is
+powered off, and has 8 steps when `change_spec` is a guest command (an extra gate before it runs
 in staging). `investigate_alert`'s approvals are synthesis checkpoints; its steps are all reads.
 See `skills/vmware-pilot/references/templates.md` for parameters and steps.
 
 | Template | Steps | Approval | Skills Used |
 |----------|:-----:|:--------:|-------------|
-| `clone_and_test` | 6-7 | Yes | aiops, monitor |
+| `clone_and_test` | 7-8 | Yes | aiops, monitor |
 | `incident_response` | 4 | Yes | monitor, aiops |
 | `investigate_alert` | 4 (8 with `deep_dive`) | Yes | monitor, aria |
 | `plan_and_approve` | 3 | Yes | aiops |
@@ -146,6 +149,24 @@ update it. Requires vmware-policy ≥ 1.19.0. Details: [RELEASE_NOTES.md](RELEAS
 > corporate proxy (`invalid peer certificate: UnknownIssuer`). The installed entry point above
 > touches the network zero times; set `UV_NATIVE_TLS=true` if you must use `uvx`.
 
+### Pilot runs the steps itself: `--dispatch`
+
+By default pilot executes nothing: `run_workflow` returns each step in `pending_dispatch` and your agent performs it.
+Add `--dispatch` (or set `VMWARE_PILOT_DISPATCH=stdio`) and pilot runs each step itself, in that skill's own MCP
+server (`vmware-<skill>-mcp`, which must be installed), so the skill's policy rules, confirmation gate and audit
+apply as usual. Nothing after an approval gate runs before `approve`, and workflows reach `completed`.
+
+```json
+{"mcpServers": {"vmware-pilot": {"command": "vmware-pilot", "args": ["mcp", "--dispatch"]}}}
+```
+
+stdio only: pilot refuses to start with `--dispatch` and `--transport https`/`http` (the skill servers it starts would
+have no caller identity, so roles could not apply). A step that takes longer than `VMWARE_PILOT_DISPATCH_TIMEOUT`
+seconds (default 1800) is recorded `interrupted` — its effect is unknown — and rollback waits for you to check it.
+`run_workflow` and `approve` take as long as the steps they run: set your MCP client's tool timeout above your
+longest step. If a call does time out, Pilot carries on and answers nothing else until the step ends; then
+`get_workflow_status` shows the outcome. Never perform those steps yourself.
+
 <!-- usage: remote-and-exposure -->
 ## Remote access (HTTPS) and limiting tools
 

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/README-CN.md

@@ -1,6 +1,8 @@
 <!-- mcp-name: io.github.vmware-skills/vmware-pilot -->
 # VMware Pilot
 
+要用自己的模型和 Agent 平台进行只读自测，请看 marketplace 根目录的[共享模型适配自测任务](https://github.com/vmware-skills/marketplace/blob/main/MODEL_FIT_SELF_TEST.md)。
+
 > **作者**: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com
 > 本项目由 VMware 工程师维护的社区项目，非 VMware 官方产品。
 > VMware 官方开发者工具请访问 [developer.broadcom.com](https://developer.broadcom.com)。
@@ -43,19 +45,19 @@ vmware-pilot mcp          # 启动 MCP server（stdio）
 | `create_workflow` | 从步骤列表直接创建自定义工作流（若破坏性步骤之前没有审批门控则拒绝） |
 | `run_workflow` | 执行工作流，在审批门控处暂停 |
 | `get_workflow_status` | 查询状态 + 差异报告 + 审计日志 |
-| `approve` | 人工审批，继续执行 |
+| `approve` | 人工审批，继续执行。审批点之前仍有 `not_executed` 步骤时拒绝，直到 `acknowledge_not_executed=True` 表明这些步骤已由你执行 |
 | `rollback` | 显式、尽力而为地逆序撤销 pilot 记录为成功的步骤——从不自动执行。不带 `confirm=True` 时只预览（`blast_radius`） |
 | `cancel_workflow` | 取消工作流，置为终态 CANCELLED。不带 `confirm=True` 时只预览（`blast_radius`） |
 
 ## 内置模板（15 个）
 
-`n` 为虚拟机（或漂移项）数量；区间取决于设置了哪些可选参数。`change_spec` 为 guest 命令时
-`clone_and_test` 有 7 步（在 staging 中执行命令前多一道审批）。`investigate_alert` 的审批是综合
-判断检查点，其步骤全部为只读。参数与步骤详见 `skills/vmware-pilot/references/templates.md`。
+`n` 为虚拟机（或漂移项）数量；区间取决于设置了哪些可选参数。`clone_and_test` 需要
+`snapshot_name`（克隆所用的快照），在 staging 关机状态下调整规格；`change_spec` 为 guest 命令时
+有 8 步（在 staging 中执行命令前多一道审批）。`investigate_alert` 的审批是综合判断检查点，其步骤全部为只读。参数与步骤详见 `skills/vmware-pilot/references/templates.md`。
 
 | 模板 | 步骤数 | 审批 | 使用的技能 |
 |------|:------:|:----:|-----------|
-| `clone_and_test` | 6-7 | 是 | aiops, monitor |
+| `clone_and_test` | 7-8 | 是 | aiops, monitor |
 | `incident_response` | 4 | 是 | monitor, aiops |
 | `investigate_alert` | 4（`deep_dive` 时 8） | 是 | monitor, aria |
 | `plan_and_approve` | 3 | 是 | aiops |
@@ -97,6 +99,23 @@ CLI 命令也不变。技能目录同时跟随 vmware-vks 的改名（`get_super
 > （`invalid peer certificate: UnknownIssuer`）。上面的入口点走 PATH，完全不联网；
 > 若必须用 `uvx`，请设置 `UV_NATIVE_TLS=true`。
 
+### 由 Pilot 自己执行步骤：`--dispatch`
+
+默认情况下 Pilot 不执行任何步骤：`run_workflow` 把每一步放在 `pending_dispatch` 里返回，由你的 agent 去执行。
+加上 `--dispatch`（或设置 `VMWARE_PILOT_DISPATCH=stdio`）后，Pilot 会在对应 skill 自己的 MCP server
+（`vmware-<skill>-mcp`，需已安装）里执行每一步，因此该 skill 的策略规则、确认门和审计照常生效。审批点之后的步骤
+在 `approve` 之前不会执行，工作流可以走到 `completed`。
+
+```json
+{"mcpServers": {"vmware-pilot": {"command": "vmware-pilot", "args": ["mcp", "--dispatch"]}}}
+```
+
+仅限 stdio：`--dispatch` 与 `--transport https`/`http` 同时使用时 Pilot 拒绝启动（它启动的 skill server 没有调用者
+身份，角色无法生效）。超过 `VMWARE_PILOT_DISPATCH_TIMEOUT` 秒（默认 1800）的步骤记为 `interrupted`——效果未知——
+回滚会等你确认后再进行。
+`run_workflow` 和 `approve` 的耗时等于它们执行的步骤：请把 MCP 客户端的工具超时设得比最长的步骤更长；万一调用超时，
+Pilot 会继续执行，并在该步骤结束前不响应其他调用；之后用 `get_workflow_status` 查看结果——不要自己去执行这些步骤。
+
 ## 审计与安全
 
 所有操作通过 vmware-policy（`@vmware_tool` 装饰器）自动审计：

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/README.md

@@ -2,6 +2,8 @@
 
 # VMware Pilot
 
+For a read-only check of this skill with your model and agent host, use the shared [model-fit self-test](https://github.com/vmware-skills/marketplace/blob/main/MODEL_FIT_SELF_TEST.md) in the marketplace root.
+
 > **Author**: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com
 > This is a community-driven project by a VMware engineer, not an official VMware product.
 > For official VMware developer tools see [developer.broadcom.com](https://developer.broadcom.com).
@@ -72,20 +74,21 @@ pip install --no-index --find-links dist vmware-pilot
 | `create_workflow` | Create custom workflow from step list (refused if a destructive step has no approval gate before it) |
 | `run_workflow` | Execute workflow, pauses at approval gates |
 | `get_workflow_status` | Query state + diff report + audit log |
-| `approve` | Human approval, continue execution |
+| `approve` | Human approval, continue execution. Refused while steps before the gate are `not_executed`, until `acknowledge_not_executed=True` says you ran them |
 | `rollback` | Explicit, best-effort undo of steps pilot recorded as succeeded — never automatic. Previews (`blast_radius`) unless `confirm=True` |
 | `cancel_workflow` | Cancel a workflow — move it to the terminal CANCELLED state. Previews (`blast_radius`) unless `confirm=True` |
 
 ## Built-in Templates (15)
 
 `n` is the number of VMs (or drift items); ranges depend on which optional parameters are set.
-`clone_and_test` has 7 steps when `change_spec` is a guest command (an extra gate before it runs
+`clone_and_test` needs `snapshot_name` (the snapshot to clone from), resizes staging while it is
+powered off, and has 8 steps when `change_spec` is a guest command (an extra gate before it runs
 in staging). `investigate_alert`'s approvals are synthesis checkpoints; its steps are all reads.
 See `skills/vmware-pilot/references/templates.md` for parameters and steps.
 
 | Template | Steps | Approval | Skills Used |
 |----------|:-----:|:--------:|-------------|
-| `clone_and_test` | 6-7 | Yes | aiops, monitor |
+| `clone_and_test` | 7-8 | Yes | aiops, monitor |
 | `incident_response` | 4 | Yes | monitor, aiops |
 | `investigate_alert` | 4 (8 with `deep_dive`) | Yes | monitor, aria |
 | `plan_and_approve` | 3 | Yes | aiops |
@@ -129,6 +132,24 @@ update it. Requires vmware-policy ≥ 1.19.0. Details: [RELEASE_NOTES.md](RELEAS
 > corporate proxy (`invalid peer certificate: UnknownIssuer`). The installed entry point above
 > touches the network zero times; set `UV_NATIVE_TLS=true` if you must use `uvx`.
 
+### Pilot runs the steps itself: `--dispatch`
+
+By default pilot executes nothing: `run_workflow` returns each step in `pending_dispatch` and your agent performs it.
+Add `--dispatch` (or set `VMWARE_PILOT_DISPATCH=stdio`) and pilot runs each step itself, in that skill's own MCP
+server (`vmware-<skill>-mcp`, which must be installed), so the skill's policy rules, confirmation gate and audit
+apply as usual. Nothing after an approval gate runs before `approve`, and workflows reach `completed`.
+
+```json
+{"mcpServers": {"vmware-pilot": {"command": "vmware-pilot", "args": ["mcp", "--dispatch"]}}}
+```
+
+stdio only: pilot refuses to start with `--dispatch` and `--transport https`/`http` (the skill servers it starts would
+have no caller identity, so roles could not apply). A step that takes longer than `VMWARE_PILOT_DISPATCH_TIMEOUT`
+seconds (default 1800) is recorded `interrupted` — its effect is unknown — and rollback waits for you to check it.
+`run_workflow` and `approve` take as long as the steps they run: set your MCP client's tool timeout above your
+longest step. If a call does time out, Pilot carries on and answers nothing else until the step ends; then
+`get_workflow_status` shows the outcome. Never perform those steps yourself.
+
 <!-- usage: remote-and-exposure -->
 ## Remote access (HTTPS) and limiting tools
 

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/RELEASE_NOTES.md

@@ -1,3 +1,88 @@
+## v2.4.1 — VKS 9.1 upgrade risk in the companion catalog (2026-11-01)
+
+* The companion-tool snapshot now includes VKS 3.5.0's read-only `get_supervisor_upgrade_risk` tool. The documented VKS and family tool counts match the live registries. Pilot's workflow execution behavior is unchanged.
+* Install VMware-VKS 3.5.0 or later to use that tool. Its advisory report does not measure VUMDB schema or establish upgrade clearance.
+
+## v2.4.0 — runs its own steps on request; honest gates and rollback (first real-vSphere run)
+
+### Behaviour changes for existing callers
+
+* `approve` refuses a gate whose earlier steps were handed out (`not_executed`) until
+  `acknowledge_not_executed=True` — this applies to the default MCP server and to workflows saved by 2.3.0 that are
+  already awaiting approval. An automated `approve` caller must pass the flag after performing the steps.
+* `clone_and_test` requires `snapshot_name` (it used to clone from a snapshot literally named `current`).
+* Rollback reports a step without an undo as `not_reversible` (was `skipped`); approval gates and catalog reads are no
+  longer listed. A rollback whose undo failed or whose effect is unknown returns `action: "rollback_incomplete"` with
+  `outcome: "failed"` and an `error` naming them (it said `rolled_back`).
+* `cancel_workflow` keeps handed-out steps `not_executed` (was rewritten to `skipped`).
+* With vmware-policy 1.24.2, Pilot's own refusals and failed outcomes (`run_workflow`/`approve` ending
+  `outcome: "failed"`, refusals carrying `error`, an incomplete rollback) are `isError` frames; previews,
+  `awaiting_approval` and `dispatch_required` are not.
+
+### Details
+
+* A step result's `kubeconfig` (a bearer token from VKS `issue_*_kubeconfig` under `--dispatch`) is masked in
+  `workflows.db` like a password. With `--dispatch`, a skill's failed call keeps its own error envelope (`hint`
+  included) instead of a flattened JSON string.
+
+Found running Pilot workflows on vCenter 8.0.3 for the first time, through the MCP server and through an embedder
+that dispatched steps to the 2.4.0 skill servers.
+
+* **`clone_and_test` works on real vSphere.** It cloned from a snapshot literally named `current` (almost no VM
+  has one) and resized the clone after powering it on, which vCenter refuses (`MemoryHotPlugNotSupported`) on any
+  VM without hot-add. Now `snapshot_name` is **required** (no default; the error names `list_vm_snapshots`), the
+  clone is made powered off, staging is resized while off and then powered on, and the check is vmware-monitor
+  `investigate_vm` on the staging VM instead of `get_alarms` for the whole vCenter. A guest command runs after
+  power-on. 7 steps (8 for a guest command). Pilot still does not wait `monitor_minutes`: the approval message
+  asks the approver to, says a running production VM is resized in place (needs hot-add), and that the production
+  change is not rolled back. The clone step no longer claims a rollback (powering a clone off does not remove it).
+* **`approve` refuses a gate whose earlier steps nobody ran.** Through the MCP server (no dispatcher) every step
+  before the gate is `not_executed`, and the gate used to pass under "Staging VM … tested". It now refuses and
+  lists them in `not_executed_before_gate`; `acknowledge_not_executed=True` records them as `reported_done`
+  (performed outside Pilot) and they are not handed out again. Pilot never saw their results: through MCP a later
+  step that references one is handed out with the reference unresolved (fill it from that step's result), and
+  an embedder that dispatches it refuses it. An embedder with a dispatcher is unaffected unless it resumes a workflow
+  that was first run without one — then the same refusal applies. The acknowledgement is the caller's
+  statement, not a check: Pilot records who sent it, not what the steps returned.
+  SKILL.md now says plainly who executes steps: through MCP the agent does, and a workflow never reaches
+  `completed` that way.
+* **Rollback says what it cannot undo.** A step with no rollback is reported `not_reversible` (it was `skipped`,
+  "no rollback defined"); a rollback that does not remove what the step created — a clone powered off — is
+  `partial` with `left_behind`, and the step is `partially_rolled_back`. The preview carries the same:
+  `leaves_behind` on such entries and `left_in_place_note`. Approval gates are no longer listed as skipped.
+* **Failure is read from the frame, not from prose.** Besides `isError` and a top-level `error` on a plain
+  dict, a top-level `error` in an MCP result's structured content and a one-row `[{"error": ...}]` list now fail
+  the step, the last step included. A string is never read as failure, even one starting `Error: ` — decided,
+  as in vmware-policy, because tools return console text that can start that way. A skill must set `isError`;
+  AIops's linked clone returned its failure as prose in 2.4.0 and is fixed there (it now raises).
+* **Pilot can run the steps itself: `vmware-pilot mcp --dispatch`** (or `VMWARE_PILOT_DISPATCH=stdio`), off by
+  default (HLD §19, D-26). Each step runs in that skill's own MCP server (`vmware-<skill>-mcp`), so its policy,
+  confirmation gate and audit apply; nothing after an approval gate runs before `approve`; workflows reach
+  `completed`. stdio only — refused with `--transport https`/`http`, and a call with a network caller is refused.
+  Only the family's skills (not `pilot`) are started, without a shell. A step that exceeds
+  `VMWARE_PILOT_DISPATCH_TIMEOUT` (default 1800 s) is recorded `interrupted` (effect unknown), as is a step whose
+  skill server died after the call was sent; a server that never starts fails the step with its reason. Every
+  step's skill is resolved before step 0 runs; settings are checked at start (`VMWARE_PILOT_DISPATCH` must be
+  `stdio` or unset). A step already handed out in `pending_dispatch` is never run again by a `--dispatch` Pilot.
+  Results are stored as the tool's own data, so `__from_step_N__:key` works; a reference to a key the step did
+  not return is refused (it used to send the whole result in its place). Failure is read from the frame:
+  skills' failed calls arrive as `isError` once they run vmware-policy with `vmware_policy.frame` (vmware-policy
+  1.24.2). With an older Policy, 13 of 14 skills sent failures with `isError: false`; Pilot catches the
+  `{"error": ...}` envelope itself, but a string-shaped failure (mostly AVI's) reads as success.
+  Pilot's tools are synchronous: set the MCP client's tool timeout above the longest step.
+* A guest command (`run_vm_guest_command`, `_with_output`) that exits non-zero now fails the step (it was recorded
+  as success); one that timed out or whose process vanished (`exit_code` -1) is `interrupted` — it may still be
+  running. A clone left `partially_rolled_back` is still listed by a second rollback; an undo whose effect is
+  unknown marks its step `interrupted`. The rollback preview lists a rollback attached to a read step.
+* `investigate_vm` added to the design catalog (101 tools).
+* Two new step statuses, `reported_done` and `partially_rolled_back`. Pilot 2.3.0 does not know them: reading a
+  workflow that has them, its `rollback` / `cancel_workflow` refuse ("unrecognised status") rather than guess.
+* The rollback preview gains `not_reversible_outside_pilot` (steps handed to the caller with no undo — a clone,
+  a production resize; tools the catalog marks read-only left out) with a note; through MCP those used to appear nowhere in the
+  preview. The cancel preview gains `handed_out_to_caller`: steps already in `pending_dispatch`, which cancel
+  can neither stop nor undo — they used to be listed as `would_skip`, and cancel now keeps them `not_executed`
+  on the record instead of rewriting them to `skipped`.
+
 ## v2.3.0 — roles for network callers (HLD §18)
 
 * Workflows record their creator (`created_by`: the network caller `token:<name>`, or the OS user). Workflows saved
@@ -998,4 +1083,4 @@ Initial release. Multi-step workflow orchestration with approval gates for VMwar
 - Rollback: reverse completed steps in order on failure
 - Skill catalog: 7 skills, 162 tools available for workflow composition
 - blocked_by_policy state: mid-workflow policy denial without auto-rollback
-- 32 unit tests
+- 32 unit tests

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/SECURITY.md

@@ -32,14 +32,15 @@ A workflow pauses at each `require_approval` step until `approve()` is called wi
 1. **Review before every run** — `run_workflow` reviews the plan and refuses one whose destructive step (skill-catalog risk high/critical, or a destructive name) or unclassifiable step has no gate before it
 2. **Custom workflows are rejected, not warned** — for a custom YAML, `create_workflow`, or AI-designed workflow, that same finding makes `create_workflow_from_template`, `create_workflow` and `confirm_draft` refuse to save it and `run_workflow` refuse it even with `force=True`; only built-in templates keep the audited `force=True` override
 3. **Credentials and guest commands count as destructive** — `vks issue_tkc_kubeconfig` and `issue_supervisor_kubeconfig` return a live Supervisor credential, and the aiops guest tools (`run_vm_guest_command`, `run_vm_guest_command_with_output`, `upload_vm_guest_file`, `provision_vm_guest`) run arbitrary commands or write files inside a VM as the account the caller names; all are gated like a delete
-4. **The gate is in pilot's workflow, not in the target skill** — on the MCP server pilot executes nothing itself; the calling agent performs each step through the companion skill, which applies its own policy rules
+4. **The gate is in pilot's workflow, not in the target skill** — by default pilot executes nothing itself; the calling agent performs each step through the companion skill, which applies its own policy rules
+5. **`--dispatch` makes the gate hold for workflows run through pilot** — pilot then runs each step in that skill's own MCP server (same policy, confirmation gate and audit) and nothing after a gate runs before `approve`. It does not stop an agent from calling a skill directly. stdio only: refused with a network transport, because the skill servers it starts would have no caller identity and roles could not apply
 
 ### Rollback (explicit, best-effort — never automatic)
 
 - A failed step stops the workflow (`failed`); remaining steps are marked `skipped` and nothing is undone automatically
 - `rollback()` and `cancel_workflow()` preview by default: without `confirm=True` they return `blast_radius` (steps undone, left applied, or skipped) and change nothing; `confirm=True` refuses when the state does not allow the transition, a step status is unrecognised, the record cannot be read, or a step was left `running`/`interrupted` (unknown effect) — the last only lifts with an explicit `acknowledge_unknown_effects=True` after the step is checked in the target system
-- `rollback()` must be called deliberately. It reverses, last first, only the steps pilot recorded as `success`, dispatching each step's `rollback_tool` — which only happens when an embedder supplied a dispatcher. On the MCP server (no dispatcher) the steps the agent performed are recorded `not_executed`, so `rollback()` reverses nothing but approval gates; the agent must call each performed step's `rollback_tool` itself
-- Steps without a `rollback_tool` are reported `skipped`; a failed undo does not stop the rest and sets `blocked_reason: rollback_failed`
+- `rollback()` must be called deliberately. It reverses, last first, only the steps pilot recorded as `success`, dispatching each step's `rollback_tool` — which only happens when pilot runs with `--dispatch` (or an embedder supplied a dispatcher). On the MCP server without `--dispatch` the steps the agent performed are recorded `not_executed`, so `rollback()` reverses nothing but approval gates; the agent must call each performed step's `rollback_tool` itself
+- Steps without a `rollback_tool` are reported `not_reversible` (their change stays); an undo that does not remove what the step created is `partial`; a failed undo does not stop the rest and sets `blocked_reason: rollback_failed`
 - Rollback results are kept on the workflow record and each `rollback` call is audited to `~/.vmware/audit.db`
 - A dispatched step or undo that returns a top-level `action: preview` (a companion tool called without `confirm=True`) is recorded `failed`, never `success`; built-in templates pass `confirm=True` to those tools only in steps that come after an approval gate (a test fails any template that does so earlier)
 

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-pilot==2.3.0",
+        "vmware-pilot==2.4.1",
         "vmware-pilot-mcp"
       ]
     }

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-pilot",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Multi-step workflow orchestration for VMware MCP skills with approval gates and rollback.",
   "private": true,
   "license": "MIT",

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-pilot"
-version = "2.3.0"
+version = "2.4.1"
 description = "VMware workflow orchestration — multi-step state machine with approval gates"
 readme = "README.md"
 license = "MIT"
@@ -12,7 +12,7 @@ requires-python = ">=3.10"
 authors = [{ name = "Wei Zhou", email = "wei-wz.zhou@broadcom.com" }]
 dependencies = [
     "vmware-policy>=1.21.0,<2.0",
-    "mcp[cli]>=1.28,<2.0",
+    "mcp[cli]>=1.30,<2.0",
     "pyyaml>=6.0,<7.0",
     "typer>=0.12,<1.0",
 ]

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-Pilot",
     "source": "github"
   },
-  "version": "2.3.0",
+  "version": "2.4.1",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-pilot",
-      "version": "2.3.0",
+      "version": "2.4.1",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/skills/vmware-pilot/SKILL.md

@@ -22,6 +22,8 @@ compatibility: >
 
 # VMware Pilot
 
+> Self-test: [guide](https://github.com/vmware-skills/marketplace/blob/main/MODEL_FIT_SELF_TEST.md).
+
 > **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" is a trademark of Broadcom. Source code is publicly auditable at [github.com/vmware-skills/VMware-Pilot](https://github.com/vmware-skills/VMware-Pilot) under the MIT license.
 
 Multi-step workflow orchestration for VMware MCP skills — design, approve, execute, rollback.
@@ -32,7 +34,7 @@ Multi-step workflow orchestration for VMware MCP skills — design, approve, exe
 
 | Capability | Description |
 |---|---|
-| Workflow Design | Natural language goal → AI designs steps from the `get_skill_catalog` building-block list (100 curated tools across 13 skills) |
+| Workflow Design | Natural language goal → AI designs steps from the `get_skill_catalog` building-block list (101 curated tools across 13 skills) |
 | Approval Gates | Pause execution for human review before destructive operations |
 | State Persistence | SQLite-backed, survives restarts, supports resume from checkpoint |
 | Rollback | Explicit, best-effort undo of completed steps in reverse order — never automatic (see Troubleshooting) |
@@ -42,7 +44,7 @@ Multi-step workflow orchestration for VMware MCP skills — design, approve, exe
 ## Quick Install
 
 ```bash
-uv tool install vmware-pilot==2.3.0
+uv tool install vmware-pilot==2.4.1
 vmware-pilot mcp          # start the MCP server (stdio)
 ```
 
@@ -96,10 +98,11 @@ AI calls: run_workflow(id)             → execute with approval gates
 AI calls: create_workflow_from_template("clone_and_test", {
     target_vm: "db01",
     change_spec: {memory_mb: 32768},
+    snapshot_name: "pre-change",   # required: list_vm_snapshots (monitor)
     target: "vcenter-prod"
 })
 AI calls: run_workflow(workflow_id)
-→ Clone → Apply → Monitor → [Approval Gate] → Commit → Cleanup
+→ Clone (off) → Resize → Power on → Check → [Approval Gate] → Production → Power off staging
 ```
 
 ### 3. Batch Operations with Approval
@@ -143,11 +146,14 @@ Deploy a backend VM, create a K8s namespace, and wire up AKO Ingress to the AVI
 
 ## Dispatch Contract (Important)
 
-**Pilot is a Dispatcher, not an Executor.** It generates plans, tracks state, gates on approvals — it does NOT call companion skills' MCP tools itself. The calling AI agent is responsible for invoking `vmware-aiops::clone_vm` etc. when pilot's `run_workflow` returns a step description.
+**Who executes steps depends on how pilot was started.**
+
+- **`vmware-pilot mcp --dispatch`** (or `VMWARE_PILOT_DISPATCH=stdio`): pilot runs each step itself, in that skill's own MCP server (its policy, confirmation gate and audit apply), and stops at every approval gate — nothing after a gate runs before `approve`. Workflows reach `completed`. stdio only: refused with `--transport https`/`http`.
+- **Default (no `--dispatch`): you do.** Every step is recorded `not_executed` and returned in `pending_dispatch`; perform them in order. At a gate, `approve` refuses while earlier steps are `not_executed` — show the user what they returned, then `approve(..., acknowledge_not_executed=True)`; they become `reported_done`. The workflow ends `dispatch_required`, never `completed`.
 
-This is intentional v2-style architecture: pilot's context stays small, state is always on disk, and there are no persistent agent threads. Full contract details: see [`references/integration-patterns.md`](references/integration-patterns.md#the-dispatch-contract).
+Without `--dispatch` this is the v2-style architecture: pilot's context stays small, state is always on disk, and there are no persistent agent threads. Full contract details: see [`references/integration-patterns.md`](references/integration-patterns.md#the-dispatch-contract).
 
-**`get_skill_catalog` is a curated design aid, not a whitelist.** It surfaces 100 hand-picked building blocks across 13 skills — a deliberate subset of what those skills expose (aiops alone has 61 tools; the catalog lists 19). A step's `skill` field is a free-form string handed to the calling agent, so a workflow may name any companion skill, including ones the catalog does not list — pilot itself (`pilot`) is used that way by built-in templates for approval gates. Use the catalog for inspiration; consult the target skill's own SKILL.md for its full tool surface.
+**`get_skill_catalog` is a curated design aid, not a whitelist.** It surfaces 101 hand-picked building blocks across 13 skills — a deliberate subset of what those skills expose (aiops alone has 61 tools; the catalog lists 19). A step's `skill` handed to the calling agent may name any companion skill, including ones the catalog does not list; with `--dispatch` only catalog skills run (`pilot` is for approval gates). Use the catalog for inspiration; consult the target skill's own SKILL.md for its full tool surface.
 
 ## MCP Tools (13 — 4 read, 9 write/control)
 
@@ -177,7 +183,7 @@ The five most-used:
 
 | Template | Steps | Approval | Skills Used |
 |---|---|---|---|
-| `clone_and_test` | 6 (7 for a guest command) | Yes | aiops + monitor |
+| `clone_and_test` | 7 (8 for a guest command) | Yes | aiops + monitor |
 | `incident_response` | 4 | Yes | monitor + aiops |
 | `investigate_alert` | 4 / 8 | Yes | monitor + aria (parallel-group gather + 4-criteria checkpoint, optional `deep_dive`) |
 | `plan_and_approve` | 3 | Yes | aiops |
@@ -280,7 +286,7 @@ The template name is case-sensitive. Use `list_workflows()` to see all available
 4. A file that lists but will not plan is missing an approval gate -- the `create_workflow_from_template` error names the step and the file
 
 ### Rollback did nothing, or fails on some steps
-Rollback never happens on its own: a failed step leaves the workflow `failed` and stops. A bare `rollback(workflow_id)` only previews; `confirm=True` acts. It only reverses steps pilot recorded as `success`, and on the MCP server (no dispatcher) the steps you performed from `pending_dispatch` stay `not_executed` — so `rollback` there reverses nothing but approval gates. Undo them yourself: call each performed step's `rollback_tool` with its `rollback_params`, last step first, after confirming with the user. Steps without a `rollback_tool` cannot be undone. When pilot does dispatch (an embedder supplied a dispatcher), rollback is best-effort: a failed undo does not stop the rest, and the result reports each one.
+Rollback never happens on its own: a failed step leaves the workflow `failed` and stops. A bare `rollback(workflow_id)` only previews; `confirm=True` acts. It only reverses steps pilot recorded as `success`, and on the MCP server (no dispatcher) the steps you performed from `pending_dispatch` stay `not_executed` — so `rollback` there reverses nothing. Undo them yourself: call each performed step's `rollback_tool` with its `rollback_params`, last step first, after confirming with the user. Steps without a `rollback_tool` cannot be undone: rollback reports them `not_reversible`, and the preview lists steps handed to you that have none under `not_reversible_outside_pilot` — if you performed them (a clone, a production resize) they stay. An undo that does not remove what the step created is `partial` — a clone that was only powered off stays; delete it by hand. When pilot dispatches (`--dispatch`), rollback is best-effort: a failed undo does not stop the rest, and the result reports each one.
 
 ### "Workflow cannot be run" state error
 A workflow can only be run from `pending` or `running` states. If it is in `draft`, call `confirm_draft()` first. If it is in `completed` or `failed`, create a new workflow -- completed workflows cannot be re-run.
@@ -303,7 +309,9 @@ No vCenter credentials needed — pilot orchestrates other skills that handle co
 }
 ```
 
-> Fallback: `{"command": "uvx", "args": ["--from", "vmware-pilot==2.3.0", "vmware-pilot-mcp"]}` also
+Add `"--dispatch"` to `args` to have pilot run the steps itself (each companion skill must be installed: `vmware-<skill>-mcp` on `PATH`).
+
+> Fallback: `{"command": "uvx", "args": ["--from", "vmware-pilot==2.4.1", "vmware-pilot-mcp"]}` also
 > works, but `uvx` re-resolves the package against PyPI on every start and fails behind a
 > TLS-inspecting corporate proxy (`invalid peer certificate: UnknownIssuer`). The installed
 > entry point above touches the network zero times; set `UV_NATIVE_TLS=true` if you must use `uvx`.

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/skills/vmware-pilot/evals/evals.json

@@ -9,6 +9,7 @@
       "expectations": [
         "Uses create_workflow_from_template with type clone_and_test",
         "Change spec includes memory_mb: 32768",
+        "Passes snapshot_name, found with vmware-monitor list_vm_snapshots (required, no default)",
         "Workflow has approval gate before production apply",
         "Shows workflow steps for user review"
       ]

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/skills/vmware-pilot/references/agent-guardrails.md

@@ -18,7 +18,9 @@ vmware-pilot is the odd one out. It manages no infrastructure of its own — it
 designs multi-step workflows, tracks their state, and gates them on human
 approval. Two consequences follow, and both matter more on a small model than
 on a large one: **authoring a workflow is itself the write operation**, and
-**pilot does not execute anything** — the calling agent does.
+**by default pilot executes nothing** — the calling agent does. (Started with
+`--dispatch`, pilot runs each step itself in that skill's own MCP server; the
+result then has no `pending_dispatch`, and you do not perform the steps.)
 
 > **Disclaimer**: This is a community-maintained open-source project and is
 > **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom
@@ -34,7 +36,7 @@ These are structural, so it cannot.
 
 | Guardrail you would otherwise prompt for | Now enforced by |
 |---|---|
-| "Do not execute steps yourself — hand them back for a human to run" | **The dispatch contract.** Pilot never calls a companion skill's MCP tools; it returns a step description and the calling agent invokes the tool. This is architecture, not etiquette. |
+| "Do not execute steps yourself — hand them back for a human to run" | **The dispatch contract.** Without `--dispatch`, pilot never calls a companion skill's MCP tools; it returns a step description and the calling agent invokes the tool. With `--dispatch`, pilot runs the steps and stops at each approval gate, so nothing after a gate runs before `approve`. |
 | "Check the plan makes sense before running it" | **`review_workflow`** performs a structural sanity check and returns `approved` or `needs_revision`. It is a read tool that inspects a definition without executing it. |
 | "Put an approval gate before anything destructive" | **Custom-workflow rejection.** In a custom workflow (YAML, `create_workflow`, or a draft), a destructive or unclassifiable step — or any step passing `confirm: True` — with no `require_approval` before it makes `create_workflow` / `confirm_draft` / `create_workflow_from_template` refuse to save it and `run_workflow` refuse to run it — `force=True` does not override that. The refusal names the step and the gate to insert. |
 | "Log every state change you make" | **The `@vmware_tool` decorator.** Every workflow transition is recorded to `~/.vmware/audit.db`, and `get_workflow_status` returns the state plus its audit log. |
@@ -66,8 +68,8 @@ your agent's instruction block.
 
 - vmware-pilot: multi-step workflows — design, plan, run, approve, roll back,
   cancel, and inspect state.
-- vmware-aiops: VM lifecycle. Pilot never calls it; you do, when pilot hands
-  you a step.
+- vmware-aiops: VM lifecycle. Without `--dispatch` pilot never calls it; you
+  do, when pilot hands you a step.
 - vmware-monitor: read-only vCenter inventory, hosts, alarms, events.
 - vmware-nsx / vmware-nsx-security: networking and firewall.
 - vmware-storage, vmware-vks, vmware-aria, vmware-avi: their own domains.
@@ -75,8 +77,9 @@ your agent's instruction block.
 
 ## The dispatch contract
 
-- Pilot is a dispatcher, not an executor. When run_workflow returns a step, YOU
-  invoke that skill's MCP tool and report the result back. Pilot will not do it.
+- Read the result: a `pending_dispatch` list means pilot runs without
+  `--dispatch` and YOU invoke each listed tool. No `pending_dispatch` means pilot
+  ran the steps itself — do not run them again.
 - Never claim a step ran because pilot advanced its state. State advanced
   because you told pilot it did.
 - If you cannot invoke the tool a step names — it is not installed or is

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/skills/vmware-pilot/references/capabilities.md

@@ -24,7 +24,7 @@
 
 | # | Template | Steps | Approval | Skills Used | Risk |
 |---|----------|-------|----------|-------------|------|
-| 1 | `clone_and_test` | 6-7 | Yes | aiops, monitor | Medium |
+| 1 | `clone_and_test` | 7-8 | Yes | aiops, monitor | Medium |
 | 2 | `incident_response` | 4 | Yes | monitor, aiops | Medium |
 | 3 | `plan_and_approve` | 3 | Yes | aiops | High |
 | 4 | `compliance_scan` | 1-3 | No | monitor, aria | Low |
@@ -56,12 +56,12 @@ numbers matter here, and they are not the same thing:
 | Skill | Package | Skill tools | In design catalog | Domain |
 |-------|---------|:-----------:|:-----------------:|--------|
 | vmware-aiops | `vmware-aiops` | 61 | 19 | VM lifecycle, deployment, guest ops, clusters |
-| vmware-monitor | `vmware-monitor` | 33 | 5 | Read-only inventory, alarms, events |
+| vmware-monitor | `vmware-monitor` | 33 | 6 | Read-only inventory, alarms, events |
 | vmware-nsx | `vmware-nsx-mgmt` | 33 | 8 | NSX segments, gateways, NAT, routing, IPAM |
 | vmware-nsx-security | `vmware-nsx-security` | 22 | 7 | DFW policies/rules, security groups, traceflow |
 | vmware-aria | `vmware-aria` | 46 | 7 | Aria Ops metrics, alerts, capacity, anomalies |
-| vmware-vks | `vmware-vks` | 24 | 8 | Tanzu Supervisor, Namespaces, TKC clusters |
-| vmware-storage | `vmware-storage` | 15 | 5 | Datastores, iSCSI, vSAN, FC multipath |
+| vmware-vks | `vmware-vks` | 25 | 8 | Tanzu Supervisor, Namespaces, TKC clusters |
+| vmware-storage | `vmware-storage` | 16 | 5 | Datastores, per-VM usage, iSCSI, vSAN, FC multipath |
 | vmware-avi | `vmware-avi` | 28 | 13 | AVI load balancing, pool members, AKO K8s ops |
 | vmware-debug | `vmware-debug` | 14 | 5 | Incident correlation, evidence-graded cases |
 | vmware-harden | `vmware-harden` | 8 | 5 | Compliance baselines, violations, drift |
@@ -69,7 +69,7 @@ numbers matter here, and they are not the same thing:
 | vmware-privateai | `vmware-privateai` | 18 | 5 | GPU hosts, vGPU profiles, utilisation |
 | vmware-vdi | `vmware-vdi` | 27 | 9 | Horizon pools, sessions, machines, images |
 
-**Totals**: 336 tools across the 13 companion skills; the design catalog covers 100 of them
+**Totals**: 338 tools across the 13 companion skills; the design catalog covers 101 of them
 across all 13. Pilot adds 13 orchestration tools of its own. The counts are checked against
 the companion snapshot by `tests/eval/regression/test_catalog_covers_the_family.py`.
 
@@ -111,7 +111,7 @@ Pause execution for human review before destructive operations. Workflows can ha
 A failed step stops the workflow; nothing is reversed until someone calls `rollback`. It undoes, last first, only steps pilot recorded as `success` — on the MCP server (no dispatcher) that is none of the steps the agent performed, so the agent calls each step's `rollback_tool` itself. Best-effort: if one undo fails, the rest still run. Steps without a `rollback_tool` cannot be undone.
 
 ### Preview first: rollback and cancel_workflow
-Both take `confirm: bool = False`. A bare call returns `{"action": "preview", "blast_radius": ...}` and changes nothing. `blast_radius` names the workflow (id, type, state), `state_after`, and — each as a count plus up to 16 steps — `would_roll_back` / `would_skip` (rollback entries carry each step's `rollback_tool` and `rollback_params`, secrets redacted), `left_in_place` (executed steps that stay applied: cancelling part-way leaves a half-applied change), `not_reversed_by_pilot` (rollback: steps the agent performed from `pending_dispatch`), `unknown_effects` (steps interrupted mid-dispatch), plus `blockers` and `unmeasured`. `confirm=True` refuses when either list is non-empty: a state the transition is not allowed from, a step status Pilot does not recognise, a workflow record that cannot be read, or a step in `unknown_effects` (left `running`/`interrupted` by a Pilot process that stopped mid-dispatch). For the last, the refusal says what to check; after the user has checked in the target system whether each such step took effect, re-run with `acknowledge_unknown_effects=True` (default `False`). That acknowledgement covers only those steps — it lifts no blocker and no other unmeasured item.
+Both take `confirm: bool = False`. A bare call returns `{"action": "preview", "blast_radius": ...}` and changes nothing. `blast_radius` names the workflow (id, type, state), `state_after`, and — each as a count plus up to 16 steps — `would_roll_back` / `would_skip` (rollback entries carry each step's `rollback_tool` and `rollback_params`, secrets redacted), `left_in_place` (executed steps that stay applied: cancelling part-way leaves a half-applied change), `not_reversed_by_pilot` (rollback: steps the agent performed from `pending_dispatch` that have an undo to call), `not_reversible_outside_pilot` (rollback: handed-out steps with no undo — a clone, a production resize; read-only catalog tools left out), `handed_out_to_caller` (cancel: steps already in `pending_dispatch`, which cancel can neither stop nor undo), `unknown_effects` (steps interrupted mid-dispatch), plus `blockers` and `unmeasured`. `confirm=True` refuses when either list is non-empty: a state the transition is not allowed from, a step status Pilot does not recognise, a workflow record that cannot be read, or a step in `unknown_effects` (left `running`/`interrupted` by a Pilot process that stopped mid-dispatch). For the last, the refusal says what to check; after the user has checked in the target system whether each such step took effect, re-run with `acknowledge_unknown_effects=True` (default `False`). That acknowledgement covers only those steps — it lifts no blocker and no other unmeasured item.
 
 ### Companion tools that preview by default
 Destructive companion tools take `confirm: bool = False` and return `action: preview` on a bare call. Built-in template steps (and their `rollback_params`) pass `confirm=True`, because in every built-in template they come after an `approve` gate (a test enforces it). `rollback_params` with `confirm: True` in any workflow, built-in or custom, run on a `rollback(confirm=True)` call without an approval step of their own: `rollback` is itself gated, and that `confirm=True` is the human decision taken after its preview listed every rollback step's tool and parameters; they no longer pass the deprecated `confirmed` / `dry_run`. A step or rollback whose result is a top-level `action: preview` is recorded `failed` ("step only previewed"), never `success`. `baseline_remediate` adds `confirm=True` to caller-supplied drift items for those tools and refuses items that already carry `confirm`, `confirmed` or `dry_run`.

{vmware_pilot-2.3.0 → vmware_pilot-2.4.1}/skills/vmware-pilot/references/cli-reference.md

@@ -19,12 +19,12 @@ client.
 
 ```bash
 # Recommended: installed entry point, never touches the network
-uv tool install vmware-pilot==2.3.0
+uv tool install vmware-pilot==2.4.1
 vmware-pilot mcp
 
 # Fallback: uvx re-resolves against PyPI each start and fails behind a
 # TLS-inspecting corporate proxy — set UV_NATIVE_TLS=true if you must use it
-uvx --from vmware-pilot==2.3.0 vmware-pilot-mcp
+uvx --from vmware-pilot==2.4.1 vmware-pilot-mcp
 ```
 
 The server runs on **stdio** transport and exposes 13 MCP tools (4 read, 9 write).
@@ -101,7 +101,7 @@ Create a workflow from a built-in or custom template.
 ```
 create_workflow_from_template(
     workflow_type="clone_and_test",
-    params={target_vm: "db01", change_spec: {memory_mb: 32768}}
+    params={target_vm: "db01", change_spec: {memory_mb: 32768}, snapshot_name: "pre-change"}
 )
 → {workflow_id: "wf-...", steps: [...]}
 ```
@@ -165,8 +165,9 @@ rollback(workflow_id="wf-...", confirm=True)   # after the user has seen the pre
 ```
 
 `cancel_workflow(workflow_id, reason, confirm=False)` works the same way: the
-preview lists the executed steps that stay applied and the steps that would be
-skipped; `confirm=True` cancels.
+preview lists the executed steps that stay applied, the steps already handed to
+you in `pending_dispatch` (`handed_out_to_caller` — cancel neither stops nor undoes
+them) and the steps that would be skipped; `confirm=True` cancels.
 
 Both refuse `confirm=True` while a step is in `unknown_effects` (left `running`
 or `interrupted` when a Pilot process stopped mid-dispatch). Check in the target