@paradigma-inc/flywheel 0.1.15 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.15",
+  "version": "0.1.19",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [

package/skills/flywheel/SKILL.md

@@ -50,3 +50,10 @@ Choose one primary file first, then add at most one supporting file only if need
 - Prefer concrete steps and decision points over long narrative explanations.
 - Do not run broad document reads; load only what is required by the current request.
 - Do not start compute-heavy execution before design intent is clear.
+- When another specialized Flywheel skill is explicitly invoked, this skill provides background guidance only and must not override that skill's workflow rules.
+- For managed compute cleanup in autonomous runs, default to releasing only
+  known leases (leases acquired in the current run or explicitly selected by
+  the user).
+- When unknown active leases are present, report and skip by default.
+- Use account-wide release (`flywheel_compute_release_all`) only when the user
+  explicitly asks for account-wide cleanup.

package/skills/flywheel/compute/managed-compute.md

@@ -14,8 +14,14 @@ Flywheel can provision managed GPU instances for you from providers like Lambda
    ```
 
 2. **Approve a budget.** Flywheel opens an approval page in your browser where you set a spending cap for managed compute acquisition.
-3. **The agent handles the rest.** It acquires a machine, waits for it to become ready, and gets SSH access automatically. Provisioning typically takes a few minutes — the agent polls for readiness in the background.
-4. **Release when done.** When you're finished, the agent releases the lease. You can also release leases from the WebUI at any time.
+3. **Review and choose a GPU.** The agent lists current offers, recommends one option with rationale, presents alternatives, and waits for your explicit confirmation before acquiring.
+4. **The agent acquires and connects.** After explicit confirmation, the agent acquires a machine, waits for it to become ready, and gets SSH access automatically. Provisioning typically takes a few minutes — the agent polls for readiness in the background.
+5. **Release when done.** When you're finished, the agent releases the lease. You can also release leases from the WebUI at any time.
+
+For autonomous runs, agents should default to releasing only known leases
+(leases acquired in the current run or explicitly selected by the user). If
+unknown active leases are detected, agents should report and skip those leases
+by default. Use account-wide release only when the user explicitly requests it.
 
 ## [](https://flywheel.paradigma.inc//#managing-machines-in-the-webui)Managing machines in the WebUI
 
@@ -37,6 +43,114 @@ Compute is billed against your Flywheel credits balance, which is separate from
 
 For a focused reference, see `compute/credits-and-billing.md`.
 
+## Recommendation procedure
+
+### Step 1 - Filter to allowed options
+
+- Input: `options` from `flywheel_compute_list_options`.
+- Keep only entries where `allowed == true`.
+- If empty, return "empty option list" failure mode and stop.
+
+### Step 2 - Extract task signals from node text
+
+- Read `node.content`, `node.hypothesis`, `node.summary`.
+- Extract:
+  - `weight_class` in `{light, medium, heavy, unknown}`
+  - `expected_runtime_hours`
+  - `min_vram_gb`
+- Defaults:
+  - `expected_runtime_hours`: `1` for light, `3` for medium, `8` for heavy, `unknown` when weight is unknown.
+  - `min_vram_gb`: `0` for light, `24` for medium, `40` for heavy.
+- If any signal is `unknown`, ask exactly one clarifying question:
+  - "Roughly what size model and how long do you expect to run?"
+- LLM judgment is allowed only in this step.
+
+### Step 3 - Apply affordability filter
+
+- Compute `runway_hours = budget_remaining_cents / price_cents_per_hour` for each option.
+- Drop options where `runway_hours < expected_runtime_hours * 1.25`.
+- `1.25` is fixed in this issue; do not change it.
+- If empty, return "all options over cap" failure mode and stop.
+
+### Step 4 - Apply minimum VRAM filter
+
+- Drop options where `gpu_memory_gb < min_vram_gb`.
+- If this would empty the set, keep the Step 3 set and mark `VRAM-constrained fallback`.
+- Use the Step 4-qualified set for subsequent ranking, alternatives, and retries.
+- Use the Step 3 survivors for those later decisions only when `VRAM-constrained fallback` is active.
+
+### Step 5 - Rank and pick recommendation
+
+Evaluate buckets in this order and stop at the first non-empty bucket:
+
+1. Preferred + affordable + VRAM-met (`offer_id` in `preferred_offer_ids`)
+2. Affordable + VRAM-met
+3. Affordable fallback (when `VRAM-constrained fallback` is active)
+
+Sorting rules:
+
+- Buckets 1 and 2 primary sort: cheapest `price_cents_per_hour`.
+- Bucket 3 primary sort: largest `gpu_memory_gb`, then cheapest on tie.
+
+Tie-breakers (only when primary sort values are exactly equal):
+
+1. `availability_mode == live_capacity` before `allocation_time`
+2. `price_kind == provider_reported` before `estimate`
+3. more `regions` entries first
+4. lexicographic `offer_id`
+
+### Step 6 - Build recommendation rationale
+
+Include:
+
+- GPU identity: `{gpu_model} ({gpu_memory_gb}GB)`
+- Hourly rate in dollars per hour
+- Estimate suffix when `price_kind == estimate`
+- Runway statement using `budget_remaining_cents`
+- Weight-class match statement
+- Availability note only when non-default
+- Provenance tag for preferred-list pick or VRAM fallback
+
+### Step 7 - Select up to two alternatives
+
+From the active candidate set (Step 4-qualified set by default; Step 3 survivors only when `VRAM-constrained fallback` is active), fill at most two slots in this order:
+
+1. Reliability alternative (only if recommendation is `allocation_time`): cheapest `live_capacity`
+2. Cheaper alternative: strictly cheaper than recommendation
+3. Headroom alternative: strictly higher `gpu_memory_gb` than recommendation
+
+Display order:
+
+1. recommendation first
+2. filled alternatives in slot order
+
+Never display more than three total options.
+
+### Step 8 - Require confirmation and handle acquire failure
+
+- Wait for explicit user confirmation (or explicit user override offer id) before `flywheel_compute_acquire`.
+- On acquire failure due to capacity:
+  1. pick next-best candidate from the active candidate set (excluding failed offer),
+  2. same provider -> retry immediately without re-confirmation,
+  3. different provider -> ask user to re-confirm before retry,
+  4. cap retries at 3 total acquire attempts per user confirmation,
+  5. for `flywheel-auto` with `k > 1`, apply retry cap and confirmation boundary per worker.
+
+Fixed numeric defaults for this flow:
+
+- `1`, `3`, `8` runtime defaults
+- affordability multiplier `1.25`
+- acquire retry cap `3`
+
+## Presenting the options
+
+- Always show the recommended offer first with rationale.
+- Then show up to two alternatives.
+- Always wait for explicit user confirmation before calling `flywheel_compute_acquire`.
+- If the user provides an explicit offer-id override, Treat as first-class and proceed with that selected offer after confirmation.
+
+For persistent preference, set `preferred_offer_ids` in the node compute policy.
+
 ## [](https://flywheel.paradigma.inc//#tips)Tips
 
 - Provisioning takes a few minutes — the agent polls automatically, so you don't need to babysit it.

package/skills/flywheel/references/flywheel-mcp-tool-map.md

@@ -1,160 +1,153 @@
 # Flywheel MCP Tool Map
 
-This reference describes the Flywheel MCP tool families and the common runtime
-contract expected by the public Flywheel skill.
+Contract-aligned routing guide for Flywheel MCP tool usage.
 
-Use it as a routing guide, not as a session snapshot. Always verify the exact
-tool surface exposed by your current MCP host before executing critical flows.
+Flywheel is a graph-based system for tracking research work, decisions, and evidence over time. Flywheel MCP is the tool interface for reading and updating that graph. You can discover, create, and manage nodes. You can collaborate with other users and use managed compute.
 
 ## Core Contract Expectations
 
-- Node lifecycle and graph-mutation flows use optimistic locking
-  (`expected_revision`).
-- Node commits require `kind`, `outcome`, and `summary`.
-- `kind` is typically `insight` or `empirical`.
-- `insight` commits require non-empty `insights`.
-- `empirical` commits require a non-empty `hypothesis`; completed empirical
-  commits also require artifacts or a `no_artifacts_reason`.
-- Artifact publish is a two-step flow:
-  prepare upload, upload raw bytes to returned signed URLs, then finalize
-  the upload batch.
+- Use `flywheel_get_contract` + `flywheel_get_contract_section` as canonical contract references.
+- Node state is canonical durable state; avoid relying on ephemeral transcript state.
+- Node kind (`untyped`, `empirical`, `insight`) is an explicit durable field.
+- Node references include immutable `node_id` and optional immutable `slug_name`; prefer communicating both together for human clarity and disambiguation.
+- Insight nodes should represent conceptual observations (theoretical insights, intuitions, motivations, decision-relevant framing); empirical nodes should represent experiments with explicit hypotheses and measured outcomes.
+- Graph topology should encode logical/causal relations between concepts and experiments. Avoid defaulting to shallow root-only branching unless work items are truly independent.
+- Node lifecycle semantics are interface-agnostic (`stage_node_create`, `stage_node_update`, `commit_node`); MCP tools are one projection of this shared contract.
+- Mutating node writes are optimistic-locking operations: read latest state, pass `expected_revision`, and handle `409 conflict` with explicit reconciliation.
+- Mutating operations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
+- Commit is finalize-only: commit requests require `expected_revision` and may optionally override `summary`; committed node state must still satisfy strict contract (`summary`/`outcome`, `empirical+completed` requires artifacts or `no_artifacts_reason`, `insight` requires non-empty insights).
+- When code is involved, pass `repo_url`/`branch_name`/`head_commit_sha` and align git structure with graph topology where practical (without forcing one-to-one mapping).
+- Summaries, hypotheses, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
+- Empirical workflow is hypothesis-driven: launch execution, inspect outcomes, publish evidence artifacts, and commit only after terminal status.
+- For empirical work, publish evidence with `flywheel_prepare_artifact_uploads`, upload raw file bytes, then `flywheel_finalize_artifact_uploads` before commit.
+- Artifact metadata records expose a non-empty `title` suitable for display labels; title normalization must never derive from `storage_url`.
 
 ## Tool Families
 
-### Session, Auth, and Contract
-
-- `mcp__flywheel__flywheel_auth_status`
-- `mcp__flywheel__flywheel_get_contract`
-- `mcp__flywheel__flywheel_get_contract_section`
-- `mcp__flywheel__flywheel_get_credits_balance`
-
-### Node Discovery and Read
-
-- `mcp__flywheel__flywheel_list_nodes`
-- `mcp__flywheel__flywheel_get_node`
-- `mcp__flywheel__flywheel_get_node_tree`
-- `mcp__flywheel__flywheel_get_node_ancestry`
-- `mcp__flywheel__flywheel_summarize_node_tree`
-- `mcp__flywheel__flywheel_get_campaign_snapshot`
-- `mcp__flywheel__flywheel_list_audit`
-
-### Node Mutation, Branching, and Commit
-
-- `mcp__flywheel__flywheel_stage_node_create`
-- `mcp__flywheel__flywheel_stage_node_update`
-- `mcp__flywheel__flywheel_commit_node`
-- `mcp__flywheel__flywheel_branch_node`
-- `mcp__flywheel__flywheel_merge_nodes`
-- `mcp__flywheel__flywheel_add_parent`
-- `mcp__flywheel__flywheel_remove_parent`
-- `mcp__flywheel__flywheel_delete_node`
-- `mcp__flywheel__flywheel_bulk_delete_nodes`
-
-### Access Policy and Collaboration
-
-- `mcp__flywheel__flywheel_get_node_sharing`
-- `mcp__flywheel__flywheel_set_sharing_for_node`
-- `mcp__flywheel__flywheel_set_sharing_for_nodes`
-
-### Tags and Graph Annotation
-
-- `mcp__flywheel__flywheel_create_node_tag`
-- `mcp__flywheel__flywheel_update_node_tag`
-- `mcp__flywheel__flywheel_delete_node_tag`
-- `mcp__flywheel__flywheel_set_node_tag_assignments`
+### Discovery and sharing
+
+- `flywheel_auth_status` (read; scopes: `read`; HTTP: `GET /auth/status`; core surface): Return Flywheel auth status for the current access token.
+- `flywheel_get_credits_balance` (read; scopes: `read`; HTTP: `GET /credits`; core surface): Return current user credits balance and lifetime counters.
+- `flywheel_updates_list` (read; scopes: `read`; HTTP: `GET /mcp/updates`; core surface): List in-app updates/announcements for the signed-in user.
+- `flywheel_updates_hide` (mutating; scopes: `write`; HTTP: `POST /mcp/updates/{announcement_id}/hide`; core surface): Mark one update as hidden for the current user (Don't show again).
+- `flywheel_updates_hide_all_active` (mutating; scopes: `write`; HTTP: `POST /mcp/updates/hide-all-active`; core surface): Hide all active updates for the current user (Don't show all active again).
+- `flywheel_updates_unhide` (mutating; scopes: `write`; HTTP: `DELETE /mcp/updates/{announcement_id}/hide`; core surface): Restore one hidden update for the current user.
+- `flywheel_list_nodes` (read; scopes: `read`; HTTP: `GET /mcp/nodes`; full-surface only): List nodes with optional owners/writers/visibility filters and projection control (`core`, `topology`, `full`).
+- `flywheel_resolve_node_slug` (read; scopes: `read`; HTTP: `GET /mcp/nodes/resolve-by-slug`; core surface): Resolve a node by slug_name with explicit conflict handling (`unique`, `context_resolved`, `ambiguous`, `not_found`).
+- `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/sharing`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
+- `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `PUT /mcp/nodes/{node_id}/sharing`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
+- `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/sharing/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
+- `flywheel_get_node` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}`; core surface): Get one node by node_id.
+- `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node.
+- `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
+- `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.
+- `flywheel_set_node_tag_assignments` (mutating; scopes: `write`; HTTP: `PUT /mcp/nodes/{node_id}/tags`; full-surface only): Set graph tag assignments for one node.
+- `flywheel_get_node_tree` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/tree`; full-surface only): Get a root-aware bounded tree/DAG projection for an anchor node.
+- `flywheel_get_node_ancestry` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/ancestry`; full-surface only): Get ordered ancestry metadata from an anchor node to root boundaries.
+- `flywheel_get_campaign_snapshot` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/campaign/snapshot`; core surface): Read the current campaign snapshot for a node's root campaign, including configured views and derived records.
+- `flywheel_list_audit` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/audit`; full-surface only): List node MCP audit events.
+
+### Node lifecycle
+
+- `flywheel_stage_node_create` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/stage/create`; full-surface only): Stage creation of a new Flywheel node.
+- `flywheel_stage_node_update` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{node_id}/stage/update`; core surface): Stage mutable node fields, including content/readme text, with optimistic locking; use `no_artifacts_reason` when empirical completed nodes intentionally have no artifacts.
+- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/commit`; core surface): Commit a node with contract validation.
+- `flywheel_branch_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/branch`; full-surface only): Create a child branch node.
+- `flywheel_merge_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/merge`; full-surface only): Merge nodes with caller-resolved node payload.
+- `flywheel_add_parent` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/parents/add`; full-surface only): Attach an additional parent edge to an existing node (keeps node identity, validates against cycles).
+- `flywheel_remove_parent` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/parents/remove`; full-surface only): Detach one parent edge from a node without deleting the node.
+- `flywheel_delete_node` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{node_id}`; full-surface only): Delete a node subtree.
+- `flywheel_bulk_delete_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/bulk-delete`; full-surface only): Delete multiple node subtrees in one operation.
 
 ### Artifacts
 
-- `mcp__flywheel__flywheel_list_artifacts`
-- `mcp__flywheel__flywheel_get_artifact`
-- `mcp__flywheel__flywheel_get_artifact_preview`
-- `mcp__flywheel__flywheel_prepare_artifact_uploads`
-- `mcp__flywheel__flywheel_finalize_artifact_uploads`
-- `mcp__flywheel__flywheel_set_artifact_note`
-- `mcp__flywheel__flywheel_delete_artifact`
-
-Common artifact types include:
-`text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`,
-`checkpoint`, and `diff_carousel`.
-
-### Export and Import
-
-- `mcp__flywheel__flywheel_export_subgraph`
-- `mcp__flywheel__flywheel_import_subgraph`
-- `mcp__flywheel__flywheel_export_summary`
-- `mcp__flywheel__flywheel_export_summary_stream`
-- `mcp__flywheel__flywheel_export_summary_pdf`
-- `mcp__flywheel__flywheel_export_summary_render_pdf`
+- `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/artifacts/uploads/prepare`; core surface): Prepare one or more raw-file artifact uploads (returns batch token + signed upload URLs). Upload must send raw file bytes to the returned URLs (do not upload JSON metadata wrappers).
+- `flywheel_finalize_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/artifacts/uploads/finalize`; core surface): Finalize a prepared artifact upload batch and append all staged artifacts to the node in one revision bump.
+- `flywheel_list_artifacts` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/artifacts`; core surface): List node artifacts.
+- `flywheel_get_artifact` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}`; core surface): Get one artifact by id.
+- `flywheel_delete_artifact` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{node_id}/artifacts/{artifact_id}`; core surface): Delete one artifact by id with optimistic locking.
+- `flywheel_set_artifact_note` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{node_id}/artifacts/{artifact_id}/note`; core surface): Set or clear one artifact note with optimistic locking.
 
 ### Executions
 
-- `mcp__flywheel__flywheel_launch_execution`
-- `mcp__flywheel__flywheel_list_executions`
-- `mcp__flywheel__flywheel_terminate_execution`
-
-### Managed Compute
-
-- `mcp__flywheel__flywheel_approval_session_heartbeat`
-- `mcp__flywheel__flywheel_list_approval_sessions`
-- `mcp__flywheel__flywheel_expire_approval_session`
-- `mcp__flywheel__flywheel_request_compute_grant_approval`
-- `mcp__flywheel__flywheel_list_compute_grants`
-- `mcp__flywheel__flywheel_compute_list_options`
-- `mcp__flywheel__flywheel_compute_acquire`
-- `mcp__flywheel__flywheel_compute_status`
-- `mcp__flywheel__flywheel_compute_connection`
-- `mcp__flywheel__flywheel_compute_release`
-- `mcp__flywheel__flywheel_compute_release_all`
-
-### Campaign Budgets (Organizer Flows)
-
-- `mcp__flywheel__flywheel_list_campaign_budgets`
-- `mcp__flywheel__flywheel_create_campaign_budget`
-- `mcp__flywheel__flywheel_update_campaign_budget`
-- `mcp__flywheel__flywheel_revoke_campaign_budget`
-
-### Migration Helpers
-
-Some installations may expose migration-only helper tools with hashed names.
-Treat these as specialized one-off tools, not part of day-to-day research
-workflows.
+- `flywheel_launch_execution` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/executions`; core surface): Launch node execution.
+- `flywheel_list_executions` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/executions`; core surface): List node executions.
+- `flywheel_terminate_execution` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/executions/{execution_id}/terminate`; core surface): Terminate a node execution.
+
+### Compute and budgets
+
+- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /mcp/nodes/{node_id}/compute/options`; core surface): List managed compute options allowed for a node. When using grant-backed compute, pass the same compute_grant_id you will use for acquire.
+- `flywheel_compute_status` (read; scopes: `compute`; HTTP: `GET /mcp/compute/status`; core surface): Read managed compute lease status for the current user. Lease rows include ownership flags so hosts can distinguish user-owned leases from sponsor-visible campaign leases. When checking a grant-backed lease, reuse the same compute_grant_id passed to acquire.
+- `flywheel_compute_connection` (read; scopes: `compute`; HTTP: `GET /mcp/compute/connection`; core surface): Read SSH connection material for an active managed compute lease once flywheel_compute_status indicates the lease is usable. Only leases owned by the current user are connectable. Pass lease_id or node_id to disambiguate when needed.
+- `flywheel_approval_session_heartbeat` (read; scopes: `compute`; HTTP: `POST /mcp/approval-sessions/heartbeat`; core surface): Create or refresh a compute-grant approval session for the current MCP host session.
+- `flywheel_list_approval_sessions` (read; scopes: `compute`; HTTP: `GET /mcp/approval-sessions`; core surface): List approval sessions visible to the current user. Optionally include grant approval bindings for each session.
+- `flywheel_expire_approval_session` (mutating; scopes: `compute`; HTTP: `POST /mcp/approval-sessions/expire`; core surface): Expire the current compute-grant approval session and release its active leases.
+- `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Request budget approval and return approval_url + request_id for user confirmation before managed compute acquisition.
+- `flywheel_list_compute_grants` (read; scopes: `compute`; HTTP: `GET /mcp/compute/grants`; core surface): List active/exhausted compute grants available to the current user.
+- `flywheel_list_campaign_budgets` (read; scopes: `compute`; HTTP: `GET /mcp/nodes/{root_node_id}/campaign-budgets`; full-surface only): List campaign compute budgets for a campaign root. Organizer-only management view.
+- `flywheel_create_campaign_budget` (mutating; scopes: `compute`; HTTP: `POST /mcp/nodes/{root_node_id}/campaign-budgets`; full-surface only): Create an organizer-funded campaign compute budget shared with participants.
+- `flywheel_update_campaign_budget` (mutating; scopes: `compute`; HTTP: `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; full-surface only): Update hard caps or metadata for an organizer-funded campaign compute budget.
+- `flywheel_revoke_campaign_budget` (mutating; scopes: `compute`; HTTP: `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; full-surface only): Revoke an organizer-funded campaign compute budget.
+- `flywheel_compute_acquire` (mutating; scopes: `compute`; HTTP: `POST /mcp/nodes/{node_id}/compute/acquire`; core surface): Acquire managed compute for a node with explicit SKU + region and required compute_grant_id (returns accepted/completed lease state only; poll flywheel_compute_status for readiness, not SSH key material). This tool heartbeats and forwards approval_session_id.
+- `flywheel_compute_release` (mutating; scopes: `compute`; HTTP: `POST /mcp/compute/release`; core surface): Asynchronously release one managed compute lease by lease_id.
+- `flywheel_compute_release_all` (mutating; scopes: `compute`; HTTP: `POST /mcp/compute/release-all`; core surface): Asynchronously release all active managed compute leases for the current user.
+
+### Contract, audit, and export
+
+- `flywheel_get_contract` (read; scopes: `read`; HTTP: `GET /mcp/contract`; core surface): Return Flywheel MCP contract overview (scopes, write safety, operation catalog, and section index).
+- `flywheel_get_contract_section` (read; scopes: `read`; HTTP: `GET /mcp/contract/sections/{section_id}`; core surface): Return one contract section by section_id (for example `graph` or `campaign/template_v1`).
+- `flywheel_export_subgraph` (read; scopes: `read`; HTTP: `POST /mcp/export`; full-surface only): Export selected graph/subgraph nodes as JSON.
+- `flywheel_import_subgraph` (mutating; scopes: `write`; HTTP: `POST /mcp/import`; full-surface only): Import graph/subgraph JSON payload into new node IDs. Set normalize_cycles=true to drop cycle/self-loop edges; default rejects cyclic payloads.
+- `flywheel_summarize_node_tree` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/summary`; full-surface only): Summarize a node tree using node fields only.
+- `flywheel_export_summary` (read; scopes: `read`; HTTP: `POST /mcp/export-summary`; full-surface only): Generate markdown summary for selected nodes.
+- `flywheel_export_summary_stream` (read; scopes: `read`; HTTP: `POST /mcp/export-summary-stream`; full-surface only): Generate summary stream events for selected nodes.
+- `flywheel_export_summary_pdf` (read; scopes: `read`; HTTP: `POST /mcp/export-summary-pdf`; full-surface only): Generate PDF summary for selected nodes.
+- `flywheel_export_summary_render_pdf` (read; scopes: `read`; HTTP: `POST /mcp/export-summary-render-pdf`; full-surface only): Render provided markdown to PDF and embed export metadata.
 
 ## Practical Tool Sequences
 
-### Insight Node Flow
-
-1. `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update`
-3. `mcp__flywheel__flywheel_commit_node`
-
-### Empirical Node With Artifacts
-
-1. `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update`
-3. Run experiment or compute steps
-4. `mcp__flywheel__flywheel_prepare_artifact_uploads`
-5. Upload artifact bytes to signed URLs
-6. `mcp__flywheel__flywheel_finalize_artifact_uploads`
-7. `mcp__flywheel__flywheel_commit_node`
-
-### Managed Compute Flow
-
-1. `mcp__flywheel__flywheel_approval_session_heartbeat`
-2. `mcp__flywheel__flywheel_request_compute_grant_approval`
-3. `mcp__flywheel__flywheel_list_compute_grants` (if needed)
-4. `mcp__flywheel__flywheel_compute_acquire`
-5. `mcp__flywheel__flywheel_compute_status` until ready
-6. `mcp__flywheel__flywheel_compute_connection`
-7. `mcp__flywheel__flywheel_compute_release` (or `..._release_all`)
-
-### Share a Graph With Collaborators
-
-1. `mcp__flywheel__flywheel_get_node_sharing`
-2. `mcp__flywheel__flywheel_set_sharing_for_node` (or `..._for_nodes`)
-3. `mcp__flywheel__flywheel_export_summary` or `..._export_subgraph` for handoff
-
-## Safety Notes
-
-- Prefer `get_contract` before implementing strict assumptions in automation.
-- Avoid call-order assumptions not mandated by contract.
-- Keep checks bounded: list/read first, then mutate only the intended nodes.
+### List Owned Nodes
+
+1. `flywheel_list_nodes` with `{'owners': ['me'], 'projection': 'core'}`.
+
+### Safe Node Update
+
+1. `flywheel_get_node`: Read latest node state before mutating fields.
+2. `flywheel_stage_node_update`: Stage changes with fresh expected_revision and resolve 409 conflicts explicitly.
+3. `flywheel_commit_node`: Commit once terminal and contract-complete.
+
+### Empirical Workflow
+
+1. `flywheel_stage_node_create`: Create a staged node, then set empirical fields before execution.
+2. `flywheel_stage_node_update`: Set `kind=empirical`, `hypothesis`, and summary fields with fresh `expected_revision`.
+3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval first. Response status is `approval_required`.
+4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status. `approval_required` is a response state, not a request parameter.. if `approval_required` then `present_approval_url_to_user`: Present `approval_url` to the user; the user opens it and confirms budget approval.; `flywheel_list_approval_sessions`: After approval, list approval sessions with include_approvals=true and use the active `compute_grant_id` for the current approval_session_id.
+5. `flywheel_compute_acquire`: Acquire lease with `compute_grant_id`; include `approval_session_id` from approval response.
+6. `flywheel_compute_status`: Poll until the active lease is ready; follow `recommended_next_action`.
+7. `flywheel_launch_execution`: Launch execution once compute and inputs are ready.
+8. `flywheel_list_executions`: Poll until execution reaches terminal status.
+9. `flywheel_prepare_artifact_uploads`: Prepare signed upload URLs for empirical evidence.
+10. `raw_file_upload`: Upload raw bytes to each signed URL with required headers.
+11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit, or set `no_artifacts_reason` when intentionally artifact-free.
+12. `flywheel_commit_node`: Commit terminal empirical node once contract requirements are satisfied.
+
+## Runtime Guidance
+
+- `flywheel_resolve_node_slug`: resolve human-facing slug references. If response status is `ambiguous`, ask the user to confirm the intended node_id before mutating anything.
+- `flywheel_get_node`: read the current node state before writes.
+- `flywheel_stage_node_update`: update in-progress node fields (title/content/summary, kind/outcome/hypothesis/insights/no_artifacts_reason), always with fresh `expected_revision`.
+- `flywheel_get_campaign_snapshot`: read the current derived campaign state for this node's root campaign instead of inferring standings from freeform text.
+- `flywheel_get_node_sharing`: after sharing writes, verify with flywheel_get_node_sharing before reporting private/shared/public state.
+- `flywheel_compute_status`: check first when work may need managed compute (GPU), to detect any active user lease state.
+- `flywheel_list_compute_grants`: list active compute grants (funded by user/root budgets) and select one `compute_grant_id` for acquisition.
+- `flywheel_request_compute_grant_approval`: request/confirm budget before acquire and choose a budget source (`user` or `root`); this returns `approval_url` + `request_id` when interactive approval is needed.
+- `flywheel_compute_connection`: read SSH connection material for the active user lease once status indicates the lease is usable.
+- `flywheel_compute_list_options`: use when a lease is needed and no suitable active lease exists, then select explicit provider-qualified `offer_id` (`provider::offer_id`) and `region`. Consider each option's `availability_mode`: `live_capacity` means provider-reported capacity, `allocation_time` means capacity is confirmed only when `flywheel_compute_acquire` attempts provisioning.
+- `flywheel_compute_acquire`: provision compute once requirements are clear. This requires a valid `compute_grant_id` and returns lease/provisioning state only (not SSH key material).
+- `flywheel_compute_release`: release compute when no longer needed.
+- `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution lifecycle.
+- `flywheel_prepare_artifact_uploads`: prepare one or more signed raw-file upload requests for concrete deliverables/evidence produced by the work.
+- `flywheel_finalize_artifact_uploads`: finalize a staged artifact batch and append all uploaded artifacts in one revision bump.
+- `flywheel_delete_artifact`: remove an accidental/obsolete node artifact.
+- `flywheel_list_artifacts`, `flywheel_get_artifact`: inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
+- `flywheel_commit_node`: finalize staged node state once terminal and contract-complete (optional summary override only).

package/skills/flywheel-auto/SKILL.md

@@ -21,7 +21,8 @@ Before execution, recover or establish these inputs:
   - Ask only when a required execution input cannot be recovered from explicit user instructions, current conversational context, or recent graph state.
   - If start nodes cannot be recovered from explicit ids/slugs, named current context, or recent graph context, ask once.
   - If the objective is missing, ask once; if the user refuses, infer it from graph context and persist it before execution.
-  - If budget ceiling, budget unit, or terminal condition is missing, ask once before execution. If the budget contract remains incomplete, keep planning but do not request compute approval or acquire compute.
+  - If budget ceiling or budget unit is missing, ask once before execution.
+  - If budget ceiling and budget unit are present but terminal condition is missing, set `terminal_condition: "budget ceiling reached"` and persist that derivation in the control node `content` before compute request or acquisition.
   - If the user gives a non-credit budget unit, persist that exact user-facing unit and derive the operational compute approval cap before acquisition.
 
 ## Working Terms
@@ -37,6 +38,7 @@ Before execution, recover or establish these inputs:
 - Use artifacts for supporting files and evidence, not as a substitute for the node's main narrative.
 - Only create graph edges for durable semantic relationships, because graphifying every wiki link floods the graph with noise that hides decision-relevant structure.
 - Treat the flywheel-auto skill as graph-local autonomous research: persist the run contract in the graph, keep the plan `n` hops ahead, and spend only within an explicit measured budget.
+- When guidance from flywheel, flywheel-lookahead, flywheel-reproduce, or flywheel-to-graph conflicts during an active $flywheel-auto run, flywheel-auto rules take precedence for compute, questioning, and stop decisions.
 - Ask only the minimum clarification questions needed to establish a coherent control contract, and ask none when the required answers are already recoverable from user instructions, conversational context, or graph state.
 - Planned nodes that are expected to produce evidence or artifacts should be typed `empirical`; planned nodes that only encode synthesis, decomposition, or decision structure should be typed `insight`.
 - Keep the control node typed `insight` and keep its `insights` non-empty so the insight commit contract stays valid.
@@ -49,12 +51,12 @@ Before execution, recover or establish these inputs:
 2. Resolve the objective and budget contract.
    - Recover required execution inputs from the current conversation and graph first. Ask only for inputs that remain genuinely missing after that recovery pass.
    - The flywheel-auto skill requires a measurable objective and an explicit terminal condition. Ask once for missing prerequisites; if the user refuses to specify an objective, infer it from the available graph context and state it explicitly before continuing.
-   - The budget contract must be explicit before execution starts. Ask once for any missing budget ceiling, budget unit, or terminal condition. If those inputs remain unavailable after one clarification round, keep planning but do not request compute approval or acquire compute.
+   - The budget contract must be explicit before execution starts. Ask once for missing budget ceiling or budget unit. When budget ceiling and budget unit are present but terminal condition is missing, derive `terminal_condition: "budget ceiling reached"` and persist that derivation into the control node `content` before any compute request or acquisition.
    - Managed compute spend is billed in Flywheel credits. If the user gives dollars, hours, or another measurable budget semantic, persist that user-facing cap explicitly and derive the operational compute approval cap before acquisition.
    - Persist the run contract in a dedicated `insight` control node for this frontier. Put the canonical contract in node `content`, keep a one-line synopsis in `summary`, and keep brief run rationale in `insights` so the commit contract stays valid.
    - The control contract must name: objective, decision criterion, start nodes, budget ceiling and unit, lookahead depth `n`, frontier width `k`, and an explicit terminal condition.
    - Later flywheel-auto replans must read the control node `content` first and continue from that persisted contract rather than from chat memory.
-   - Run the design gate from [references/experiment-design-protocol.md](references/experiment-design-protocol.md) before the first compute request: confirm objective, decision criterion, evidence plan, and budget readiness, even though later continuation decisions become graph-local.
+   - Run the design gate from [references/experiment-design-protocol-autonomous.md](references/experiment-design-protocol-autonomous.md) before the first compute request: confirm objective, decision criterion, evidence plan, budget readiness, and stop-reason recording requirements, even though later continuation decisions become graph-local.
 3. Map each stable page, claim, or concept to a node.
    - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
    - Create a new node with `flywheel_stage_node_create` when needed.
@@ -78,14 +80,20 @@ Before execution, recover or establish these inputs:
    - In the flywheel-auto skill, the same `k` also caps concurrent workers pursuing executable frontier nodes.
    - Keep unresolved plan nodes staged until the corresponding work is resolved.
 8. Execute and replan continuously.
-   - For exact execution and compute request shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and [references/experiment-design-protocol.md](references/experiment-design-protocol.md).
+   - For exact execution and compute request shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and [references/experiment-design-protocol-autonomous.md](references/experiment-design-protocol-autonomous.md).
    - Use `flywheel_launch_execution` when the branch can run as a Flywheel node execution without a separate leased machine, and inspect terminal status before commit.
-   - Use managed compute when the branch needs provider or SKU choice, SSH access, a custom runtime, or longer-lived hardware. In that case use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants` or `flywheel_list_approval_sessions`, then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready.
+   - Use managed compute when the branch needs provider or SKU choice, SSH access, a custom runtime, or longer-lived hardware. In that case use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants` or `flywheel_list_approval_sessions`, call `flywheel_compute_list_options`, recommend one offer deterministically and present up to two alternatives, wait for explicit user confirmation (or explicit user override offer id), then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready.
    - Spawn up to `k` workers for distinct executable frontier nodes.
+   - For `k > 1`, apply the list-options -> recommendation -> explicit confirmation boundary per worker before each worker-specific acquire call.
    - Route additional viable branches sequentially when there are more than `k` worthwhile directions.
    - After each resolved node, refresh the lookahead so the graph remains `n` hops ahead.
-   - Release managed compute with `flywheel_compute_release` or `flywheel_compute_release_all` when a branch is done.
+   - Release managed compute when a branch is done. Default to releasing only
+     known leases. Use `flywheel_compute_release_all` only when the user
+     explicitly requests account-wide cleanup.
    - Stop only when the graph-local terminal condition says to stop, such as: objective met, budget exhausted, or no non-redundant frontier branch is likely to produce enough decision-relevant information to justify the remaining budget and duplication risk.
+   - If stopping because no non-redundant frontier branch is worth pursuing, record a per-candidate rejection rationale in control node `content` before termination.
+   - Before every termination path, persist `stop_reason` in control node `content` as one of: `budget_exhausted`, `objective_met`, `no_viable_branch`, `user_cancelled`, `runtime_error`.
+
 9. Commit after the node snapshot is coherent with `flywheel_commit_node`.
    - Commit resolved insight nodes only when they have non-empty `insights`.
    - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
@@ -100,7 +108,8 @@ When the skill completes a pass, it should leave behind:
 - Zero or more committed resolved nodes, but only when their commit contracts are satisfied.
 - Uploaded artifacts for completed empirical work, or an explicit `no_artifacts_reason` when artifacts are absent by design.
 - Released managed compute if any lease was acquired during the pass.
-- An explicit stop reason, continuation rule, or next action recorded in node state so a later pass can resume graph-locally.
+- An explicit `stop_reason` recorded in node state so a later pass can resume graph-locally.
+- If the no-branch stop clause is used, a per-candidate rejection log recorded in control node `content`.
 
 ## Persisted Control Contract
 
@@ -138,6 +147,7 @@ Canonical contract shape:
 - Lookahead depth:
 - Frontier width:
 - Terminal condition:
+- Stop reason:
 ```
 
 Use `Compute approval cap` for the operational cap that will govern managed

package/skills/flywheel-auto/evals/evals.json

@@ -11,6 +11,12 @@
     "expected_output": "Persist the dollar-denominated budget ceiling and unit verbatim in the control node, derive an operational compute approval cap before acquisition, record both values before any compute request is made, and leave a coherent run contract behind for later continuation.",
     "files": []
   },
+  {
+    "id": "cold-start-budget-only-auto-exhaustion",
+    "prompt": "Use $flywheel-auto to continue autonomously under a budget ceiling when only the budget contract is explicit at cold start.",
+    "expected_output": "When terminal condition is missing but budget ceiling and budget unit are explicit, derive terminal condition as budget ceiling reached, continue autonomously without premature user handoff, and persist stop_reason in the committed control contract before termination.",
+    "files": []
+  },
   {
     "id": "cold-start-with-no-objective",
     "prompt": "Use $flywheel-auto to go autonomous on this Flywheel graph until you find something interesting. If I refuse to specify an objective, infer one from the graph context and make it explicit before you execute.",