@paradigma-inc/flywheel 0.1.19 → 0.1.25

package/README.md

@@ -107,6 +107,14 @@ Reruns refresh every already-installed bundled skill in place and install any
 newly bundled skills from the updated package. They do not create side-by-side
 copies for the same scope and agent location.
 
+If you choose to refresh via `skills experimental_sync` instead of rerunning
+setup, install Flywheel locally in that project first:
+
+```bash
+npm install --save-dev @paradigma-inc/flywheel@latest
+npx skills experimental_sync --agent codex -y
+```
+
 ## Supported Hosts For Bundled Skill Install
 
 - Claude Code

package/package.json

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

package/skills/flywheel/references/experiment-design-protocol.md

@@ -141,7 +141,7 @@ Typical flow:
 1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_stage_node_create`
 2. `mcp__flywheel__flywheel_stage_node_update` with the explicit run summary and the local question or hypothesis for that branch
 3. `mcp__flywheel__flywheel_request_compute_grant_approval` only after the user accepts the design
-4. `mcp__flywheel__flywheel_list_compute_grants` or `mcp__flywheel__flywheel_list_approval_sessions` when you need to resolve the approved `compute_grant_id`
+4. `mcp__flywheel__flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)` when you need to resolve the approved `compute_grant_id`
 5. `mcp__flywheel__flywheel_compute_acquire` and related compute tools only when execution is actually needed
 6. `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, then `mcp__flywheel__flywheel_finalize_artifact_uploads`
 7. Do a brief epistemic check before commit: verify what the evidence actually shows, whether it matches the interpretation rule from the brief, and whether any gap between the data and the hoped-for story needs to be named explicitly in the node summary.

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

@@ -12,13 +12,6 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - 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`.
 
@@ -47,11 +40,13 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `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
+### Node stage and commit
 
-- `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_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/commit-new`; full-surface only): Commit a locally staged new node into canonical storage and return the persisted node.
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire a session-scoped stage lease for an existing node before local staged edits.
+- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/heartbeat`; full-surface only): Refresh the active stage lease for the current editing session.
+- `flywheel_release_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/release`; full-surface only): Release the active stage lease for the current editing session.
+- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/commit`; core surface): Commit an existing node by publishing the caller's staged payload under an active stage lease.
 - `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).
@@ -77,20 +72,20 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 ### 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_compute_status` (read; scopes: `compute`; HTTP: `GET /mcp/compute/status`; core surface): Read managed compute lease status for the current user and current lease_control_token scope. 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. This tool is token-scoped to lease_control_token and 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_approval_sessions` (read; scopes: `compute`; HTTP: `GET /mcp/approval-sessions`; core surface): List approval sessions visible to the current user.
+- `flywheel_expire_approval_session` (mutating; scopes: `compute`; HTTP: `POST /mcp/approval-sessions/expire`; core surface): Expire the current compute-grant approval session context without releasing active leases.
+- `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Request budget approval context before managed compute acquisition; branch on response status.
 - `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.
+- `flywheel_compute_acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; 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 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 within the current lease_control_token scope.
+- `flywheel_compute_release_all` (mutating; scopes: `compute`; HTTP: `POST /mcp/compute/release-all`; core surface): Asynchronously release active managed compute leases in the current lease_control_token scope; set force=true for explicit account-wide cleanup for the current user.
 
 ### Contract, audit, and export
 
@@ -113,15 +108,15 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 ### 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.
+2. `flywheel_acquire_stage_lease`: Acquire a session-scoped stage lease before editing an existing node locally.
+3. `flywheel_commit_node`: Commit with `stage_session_id`, `base_committed_revision`, and full `staged_payload` 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.
+1. `flywheel_commit_new_node`: Commit a local staged new node to canonical storage as the first persistence boundary.
+2. `flywheel_commit_node`: Commit staged empirical fields with `stage_session_id`, `base_committed_revision`, and a full `staged_payload` once the working state is ready to publish.
+3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval context first. Branch on response status.
+4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status (`already_approved`, `approval_required`, `insufficient_credits`).. if `already_approved` then `reuse_compute_grant_id`: Use returned `compute_grant_id` directly for flywheel_compute_acquire.. 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_compute_grants`: After approval, list active grants for the current `approval_session_id` and use the returned `compute_grant_id` for acquire.. if `insufficient_credits` then `request_user_credit_top_up`: No `approval_url` is returned. Ask the user to add credits, then retry flywheel_request_compute_grant_approval.
 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.
@@ -135,19 +130,19 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - `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_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`: coordinate session-scoped local staged edits for an existing node before commit.
 - `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_compute_status`: check first when work may need managed compute (GPU), using the active lease_control_token from host context (or pass it explicitly).
 - `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_request_compute_grant_approval`: request/confirm budget before acquire and choose a budget source (`user` or `root`); branch on status (`already_approved`, `approval_required`, `insufficient_credits`).
+- `flywheel_compute_connection`: read SSH connection material for the active user lease once status indicates the lease is usable, scoped by lease_control_token.
 - `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_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). Capture `compute.lease_control_token` from the response for follow-up lease control tools.
+- `flywheel_compute_release`: release compute when no longer needed, scoped by lease_control_token.
+- `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution status transitions.
 - `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).
+- `flywheel_commit_new_node`, `flywheel_commit_node`: publish the caller's full staged payload for an existing node once terminal and contract-complete; requires an active stage lease and explicit `base_committed_revision`.

package/skills/flywheel/setting-up-flywheel/updating-flywheel-mcp.md

@@ -9,6 +9,14 @@ npx @paradigma-inc/flywheel uninstall
 
 `uninstall` removes Flywheel MCP entries from host config files.
 
+If you choose to refresh via `skills experimental_sync` instead of rerunning
+setup, install Flywheel locally in that project first:
+
+```bash
+npm install --save-dev @paradigma-inc/flywheel@latest
+npx skills experimental_sync --agent codex -y
+```
+
 ## FAQ: How Do I Migrate from the Previous OAuth-Based MCP Client Setup?
 
 If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:

package/skills/flywheel-auto/SKILL.md

@@ -82,7 +82,7 @@ Before execution, recover or establish these inputs:
 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-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`, 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.
+   - 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(status=active, approval_session_id=<session_id>)`, 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.

package/skills/flywheel-auto/references/ARTIFACTS.md

@@ -43,7 +43,6 @@ Canonical artifact upload/finalize contract derived from `mcp_contract.py`.
 
 - Stale `expected_revision` on mutating calls returns `409` and requires explicit reconciliation.
 - Reusing an idempotency key with a different payload hash causes `409_conflict`.
-- Empirical `completed` commits must satisfy one of: `artifacts_non_empty`, `no_artifacts_reason_non_empty`.
 - Prepare item payloads must be structured objects; stringified JSON item payloads are invalid.
 - Uploading metadata wrappers instead of raw file bytes violates the upload contract.
 - Finalize requires a valid prepared batch token and staged uploads from that batch.

package/skills/flywheel-auto/references/INTERFACES.md

@@ -9,10 +9,10 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - Section order:
 - `quickstart` (Quickstart): Recommended first calls and section read order for onboarding.
 - `graph` (Graph): Node model, graph topology guidance, and durable behavior rules.
-- `lifecycle` (Lifecycle): Lifecycle operations, commit-time validation requirements, and reproducibility guidance.
+- `stage_commit` (Stage and commit): Stage/commit operations, commit-time validation requirements, and reproducibility guidance.
 - `sharing` (Sharing): Sharing modes, derived visibility, collaborator roles, and query translation.
 - `artifacts` (Artifacts): Prepare/upload/finalize requirements and artifact type rules.
-- `compute` (Compute): Lease ownership, approval session, and budget source semantics.
+- `compute` (Compute): Lease ownership, token-scoped control, approval session, and budget source semantics.
 - `compute/troubleshooting_v1` (Compute Troubleshooting v1): Provider-specific acquire/retry hints for launch kwargs and request tuning.
 - `campaign` (Campaign Contract): Campaign projection and budget contracts plus template section pointers.
 
@@ -50,10 +50,12 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `flywheel_get_campaign_snapshot` (read; scopes: `read`; core surface; binding: `operation`)
 - `flywheel_list_audit` (read; scopes: `read`; full-surface only; binding: `operation`)
 
-### Node lifecycle
+### Node stage and commit
 
-- `flywheel_stage_node_create` (mutating; scopes: `write`; full-surface only; binding: `operation`)
-- `flywheel_stage_node_update` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_commit_new_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_release_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_commit_node` (mutating; scopes: `write`; core surface; binding: `operation`)
 - `flywheel_branch_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_merge_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
@@ -132,10 +134,12 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `GET /mcp/nodes/{node_id}/campaign/snapshot` -> `flywheel_get_campaign_snapshot`
 - `GET /mcp/nodes/{node_id}/audit` -> `flywheel_list_audit`
 
-### Node lifecycle
+### Node stage and commit
 
-- `POST /mcp/nodes/stage/create` -> `flywheel_stage_node_create`
-- `PATCH /mcp/nodes/{node_id}/stage/update` -> `flywheel_stage_node_update`
+- `POST /mcp/nodes/commit-new` -> `flywheel_commit_new_node`
+- `POST /mcp/nodes/{node_id}/stage/lease/acquire` -> `flywheel_acquire_stage_lease`
+- `POST /mcp/nodes/{node_id}/stage/lease/heartbeat` -> `flywheel_heartbeat_stage_lease`
+- `POST /mcp/nodes/{node_id}/stage/lease/release` -> `flywheel_release_stage_lease`
 - `POST /mcp/nodes/{node_id}/commit` -> `flywheel_commit_node`
 - `POST /mcp/nodes/{node_id}/branch` -> `flywheel_branch_node`
 - `POST /mcp/nodes/merge` -> `flywheel_merge_nodes`
@@ -173,7 +177,7 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `POST /mcp/nodes/{root_node_id}/campaign-budgets` -> `flywheel_create_campaign_budget`
 - `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_update_campaign_budget`
 - `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_revoke_campaign_budget`
-- `POST /mcp/nodes/{node_id}/compute/acquire` -> `flywheel_compute_acquire`
+- `tool-mediated` -> `flywheel_compute_acquire`
 - `POST /mcp/compute/release` -> `flywheel_compute_release`
 - `POST /mcp/compute/release-all` -> `flywheel_compute_release_all`
 

package/skills/flywheel-auto/references/experiment-design-protocol.md

@@ -141,7 +141,7 @@ Typical flow:
 1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_stage_node_create`
 2. `mcp__flywheel__flywheel_stage_node_update` with the explicit run summary and the local question or hypothesis for that branch
 3. `mcp__flywheel__flywheel_request_compute_grant_approval` only after the user accepts the design
-4. `mcp__flywheel__flywheel_list_compute_grants` or `mcp__flywheel__flywheel_list_approval_sessions` when you need to resolve the approved `compute_grant_id`
+4. `mcp__flywheel__flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)` when you need to resolve the approved `compute_grant_id`
 5. `mcp__flywheel__flywheel_compute_acquire` and related compute tools only when execution is actually needed
 6. `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, then `mcp__flywheel__flywheel_finalize_artifact_uploads`
 7. Do a brief epistemic check before commit: verify what the evidence actually shows, whether it matches the interpretation rule from the brief, and whether any gap between the data and the hoped-for story needs to be named explicitly in the node summary.

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

@@ -12,13 +12,6 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - 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`.
 
@@ -47,11 +40,13 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `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
+### Node stage and commit
 
-- `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_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/commit-new`; full-surface only): Commit a locally staged new node into canonical storage and return the persisted node.
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire a session-scoped stage lease for an existing node before local staged edits.
+- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/heartbeat`; full-surface only): Refresh the active stage lease for the current editing session.
+- `flywheel_release_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/release`; full-surface only): Release the active stage lease for the current editing session.
+- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/commit`; core surface): Commit an existing node by publishing the caller's staged payload under an active stage lease.
 - `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).
@@ -77,20 +72,20 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 ### 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_compute_status` (read; scopes: `compute`; HTTP: `GET /mcp/compute/status`; core surface): Read managed compute lease status for the current user and current lease_control_token scope. 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. This tool is token-scoped to lease_control_token and 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_approval_sessions` (read; scopes: `compute`; HTTP: `GET /mcp/approval-sessions`; core surface): List approval sessions visible to the current user.
+- `flywheel_expire_approval_session` (mutating; scopes: `compute`; HTTP: `POST /mcp/approval-sessions/expire`; core surface): Expire the current compute-grant approval session context without releasing active leases.
+- `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Request budget approval context before managed compute acquisition; branch on response status.
 - `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.
+- `flywheel_compute_acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; 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 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 within the current lease_control_token scope.
+- `flywheel_compute_release_all` (mutating; scopes: `compute`; HTTP: `POST /mcp/compute/release-all`; core surface): Asynchronously release active managed compute leases in the current lease_control_token scope; set force=true for explicit account-wide cleanup for the current user.
 
 ### Contract, audit, and export
 
@@ -113,15 +108,15 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 ### 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.
+2. `flywheel_acquire_stage_lease`: Acquire a session-scoped stage lease before editing an existing node locally.
+3. `flywheel_commit_node`: Commit with `stage_session_id`, `base_committed_revision`, and full `staged_payload` 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.
+1. `flywheel_commit_new_node`: Commit a local staged new node to canonical storage as the first persistence boundary.
+2. `flywheel_commit_node`: Commit staged empirical fields with `stage_session_id`, `base_committed_revision`, and a full `staged_payload` once the working state is ready to publish.
+3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval context first. Branch on response status.
+4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status (`already_approved`, `approval_required`, `insufficient_credits`).. if `already_approved` then `reuse_compute_grant_id`: Use returned `compute_grant_id` directly for flywheel_compute_acquire.. 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_compute_grants`: After approval, list active grants for the current `approval_session_id` and use the returned `compute_grant_id` for acquire.. if `insufficient_credits` then `request_user_credit_top_up`: No `approval_url` is returned. Ask the user to add credits, then retry flywheel_request_compute_grant_approval.
 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.
@@ -135,19 +130,19 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - `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_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`: coordinate session-scoped local staged edits for an existing node before commit.
 - `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_compute_status`: check first when work may need managed compute (GPU), using the active lease_control_token from host context (or pass it explicitly).
 - `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_request_compute_grant_approval`: request/confirm budget before acquire and choose a budget source (`user` or `root`); branch on status (`already_approved`, `approval_required`, `insufficient_credits`).
+- `flywheel_compute_connection`: read SSH connection material for the active user lease once status indicates the lease is usable, scoped by lease_control_token.
 - `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_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). Capture `compute.lease_control_token` from the response for follow-up lease control tools.
+- `flywheel_compute_release`: release compute when no longer needed, scoped by lease_control_token.
+- `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution status transitions.
 - `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).
+- `flywheel_commit_new_node`, `flywheel_commit_node`: publish the caller's full staged payload for an existing node once terminal and contract-complete; requires an active stage lease and explicit `base_committed_revision`.

package/skills/flywheel-lookahead/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: flywheel-lookahead
-description: Stage a single-path next-step frontier from existing Flywheel graph state with Flywheel MCP using lookahead depth `n` and per-hop option width `k`, without execution or compute acquisition. Use for planning what to do next, not claim validation, source-to-graph authoring, or autonomous execution.
+description: Plan the next Flywheel frontier from existing graph state by persisting a control node, explicit option nodes at each hop, and one selected continuation chain, without execution or compute acquisition. Use when Codex needs planning-only Flywheel graph authoring, `n`/`k` lookahead, or graph-native comparison of candidate next steps, not claim validation, source-to-graph authoring, or autonomous execution.
 ---
 
 # flywheel-lookahead
 
 ## When To Use
 
-Use this skill when the task is to shape information inside Flywheel rather than only discuss it. Use the flywheel-lookahead skill when the user wants Flywheel to plan the next frontier of work from an existing set of nodes without executing it yet. Flywheel MCP is a node-first durable system of record for research work: nodes hold durable state, artifacts hold supporting files, executions record runs, and compute leases provide managed hardware. This skill is planning only: it stages next-step nodes from existing graph state without hidden execution, compute approval, or managed compute acquisition.
+The frontmatter description owns trigger semantics. Once invoked, use this skill only for planning-only Flywheel frontier authoring: persist a control node, hop-selector nodes, and explicit option nodes from existing graph state without hidden execution, compute approval, or managed compute acquisition.
 
 If exact tool or field semantics are unclear, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and [references/INTERFACES.md](references/INTERFACES.md) before mutating nodes.
 
@@ -39,7 +39,9 @@ Before planning, recover or establish these inputs:
 - Lookahead depth `n`: number of sequential hops in one plan path.
 - Step option width `k`: number of candidate directions to evaluate at each hop.
 - Expansion rule: at hop `i`, generate up to `k` non-redundant options, select exactly 1 winner, and only that winner continues to hop `i+1`.
-- Graph shape for this mode: a single chain of `n` staged nodes (not `k` parallel branches).
+- Graph shape for this mode: a single chain of `n` hop-selector nodes, each with up to `k` explicit option nodes (not `k` parallel continuation chains).
+- Each considered option should normally be staged as its own node when it is a stable, non-redundant candidate direction. Do not collapse the `k` options into prose only.
+- The next hop should keep the current hop-selector node as a parent and add the chosen option node as an additional selected edge/parent when the topology can express that relationship.
 - Each step node must record:
   - the `k` considered options,
   - the selection criterion,
@@ -68,8 +70,11 @@ Before planning, recover or establish these inputs:
    - Later lookahead passes must read the control node `content` first and continue from that persisted contract rather than from chat memory.
 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.
-   - Update an existing node with `flywheel_get_node` + `flywheel_stage_node_update` when continuing work.
+   - In this skill, each stable considered direction at a hop should normally become its own option node; the hop-selector node remains the decision record for that hop.
+   - Prefer `flywheel_commit_new_node` for a new standalone control or planning node when there is no existing parent to branch from.
+   - Prefer `flywheel_branch_node` for hop-selector nodes or option nodes that should attach directly under an existing control node, frontier node, or winning option node.
+   - Update an existing node with `flywheel_get_node`, `flywheel_acquire_stage_lease`, and `flywheel_commit_node`.
+   - Use `flywheel_add_parent` when the chosen option should remain recoverable in topology as an additional parent or selected edge, not prose alone.
 4. Put the primary page markdown or plan rationale in the node body/readme field (`content`).
    - Keep `summary` concise.
    - Populate `hypothesis`, `insights`, `outcome`, and similar fields only when the source actually supports them.
@@ -86,22 +91,23 @@ Before planning, recover or establish these inputs:
    - Expand from the resolved frontier rather than mirroring the source corpus again.
    - Depth `n` means plan `n` sequential hops ahead from the currently resolved frontier. Default `n=1`.
    - Width `k` means evaluate up to `k` distinct non-redundant candidate directions at each hop. Default `k=1`.
-   - At each hop, stage the considered options in the step record, apply the selection criterion, and choose exactly one continuation.
-   - Only the chosen continuation advances to hop `i+1`; do not stage `k` parallel continuation branches for this mode.
-   - The staged graph shape for this mode is a single chain of up to `n` unresolved step nodes (shorter only when the terminal condition is met early).
-   - Each step node must record: the `k` considered options, the selection criterion used, and the chosen continuation.
+   - At each hop, stage up to `k` explicit option nodes, record them in the hop-selector node, apply the selection criterion, and choose exactly one continuation.
+   - Only the chosen continuation advances to hop `i+1`; do not stage `k` parallel continuation chains for this mode.
+   - The staged graph shape for this mode is a single chain of up to `n` unresolved hop-selector nodes (shorter only when the terminal condition is met early), with up to `k` option nodes attached to each hop.
+   - When one option wins, encode that choice in topology as well as prose: the next hop should be reachable from the chosen option node via a selected edge or additional parent relationship when available on the current Flywheel surface.
+   - Each hop-selector node must record: the `k` considered option nodes, the selection criterion used, and the chosen continuation.
 8. 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.
-   - Leave unresolved plan nodes staged.
+   - Keep unresolved plan nodes durable and explicitly unresolved in their content; do not rely on uncommitted local drafts to preserve the frontier.
 
 ## Result Contract
 
 When the skill completes a pass, it should leave behind:
 
 - One persisted `insight` control node containing the canonical planning contract.
-- A single staged next-step chain up to the current `n` limit where each hop records up to `k` considered options and one selected continuation.
-- Updated node summaries, rationale, and edges only where the current planning pass justifies them.
+- A single persisted next-step chain up to the current `n` limit where each hop has a selector node plus up to `k` explicit option nodes and one selected continuation.
+- Updated node summaries, rationale, and selected edges that make the chosen path explicit without turning the graph into `k` parallel continuation chains.
 - No hidden execution, no compute approval, and no managed compute acquisition.
 
 ## Persisted Control Contract
@@ -112,11 +118,11 @@ For the canonical entity model and public contract terminology behind this contr
 
 Use this storage convention:
 
-1. Reuse an existing control node when one already governs the same frontier; otherwise create one with `flywheel_stage_node_create`.
+1. Reuse an existing control node when one already governs the same frontier; otherwise create one with `flywheel_commit_new_node` or `flywheel_branch_node`, depending on whether it should attach to an existing parent.
 2. Put the canonical contract in node `content`.
 3. Put a one-line synopsis in `summary`.
 4. Put the planning rationale or branch-selection logic in `insights` so the `insight` commit contract is satisfied.
-5. Update the control node with `flywheel_stage_node_update`.
+5. Update the control node with `flywheel_acquire_stage_lease` + `flywheel_commit_node`.
 6. Read the control node with `flywheel_get_node` before later replans that need a fresh `expected_revision`.
 7. Commit the control node with `flywheel_commit_node` once the contract is coherent, even if downstream frontier nodes remain staged.
 
@@ -139,7 +145,8 @@ The `Start nodes` line is the recovery anchor for later replans. If multiple fro
 
 ## Guardrails
 
-- Build the graph explicitly with nodes, artifacts, and selected edges.
+- Build the graph explicitly with nodes, artifacts, and selected edges. Do not substitute prose-only option lists for durable option nodes when those options are stable enough to plan against.
+- Use the current public Flywheel MCP mutation surface (`flywheel_commit_new_node`, `flywheel_branch_node`, `flywheel_acquire_stage_lease`, `flywheel_commit_node`, `flywheel_add_parent`) rather than inventing local stage-helper tool names.
 - Do not request compute approval, acquire managed compute, or launch execution just to do planning.
 - These planning-only execution prohibitions apply only when $flywheel-lookahead is the active skill.
 

package/skills/flywheel-lookahead/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
-  display_name: "flywheel-lookahead"
-  short_description: "Plan the next Flywheel frontier"
-  default_prompt: "Use $flywheel-lookahead to expand this Flywheel frontier into staged next-step nodes."
+  display_name: "Flywheel Lookahead"
+  short_description: "Plan staged Flywheel frontiers without execution"
+  default_prompt: "Use $flywheel-lookahead to plan a Flywheel frontier with explicit option nodes and one chosen continuation."
 
 dependencies:
   tools:

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

@@ -14,7 +14,19 @@
   {
     "id": "planning-only-with-explicit-depth-and-width",
     "prompt": "Use $flywheel-lookahead to stage two sequential hops of next-step work while evaluating up to three non-redundant options at each hop from the current Flywheel frontier. Plan only for later work and do not execute anything.",
-    "expected_output": "Persist `n=2` and `k=3` in the planning contract, evaluate up to three non-redundant options at each hop, record the considered options plus selection criterion plus chosen continuation for each step node, continue only along the single chosen path, and avoid compute approval, managed compute acquisition, or execution launch.",
+    "expected_output": "Persist `n=2` and `k=3` in the planning contract, stage up to three explicit option nodes at each hop, record those option nodes plus the selection criterion plus chosen continuation in each hop-selector node, continue only along the single chosen path, encode the chosen path with selected edges or additional-parent topology when possible, and avoid compute approval, managed compute acquisition, or execution launch.",
+    "files": []
+  },
+  {
+    "id": "explicit-option-nodes-not-prose-only",
+    "prompt": "Use $flywheel-lookahead to plan one hop ahead with four candidate directions. Keep it as a single selected path, but make the graph structure explicit enough that another agent can traverse each considered direction as its own node rather than recovering those options from prose.",
+    "expected_output": "Treat the four candidate directions as explicit option nodes, keep only one chosen continuation for the next hop, avoid staging four parallel continuation chains, and make the selected option discoverable from graph topology rather than prose alone.",
+    "files": []
+  },
+  {
+    "id": "use-current-public-mcp-mutation-tools",
+    "prompt": "Use $flywheel-lookahead to plan one hop ahead from an existing Flywheel frontier. Use the current public Flywheel MCP surface rather than inventing local staging helpers.",
+    "expected_output": "Use `flywheel_commit_new_node` for new standalone nodes when needed, prefer `flywheel_branch_node` for child hop-selector or option nodes, use `flywheel_get_node` plus `flywheel_acquire_stage_lease` plus `flywheel_commit_node` for updates, and use `flywheel_add_parent` when encoding the selected option in topology.",
     "files": []
   }
 ]

package/skills/flywheel-lookahead/references/ARTIFACTS.md

@@ -43,7 +43,6 @@ Canonical artifact upload/finalize contract derived from `mcp_contract.py`.
 
 - Stale `expected_revision` on mutating calls returns `409` and requires explicit reconciliation.
 - Reusing an idempotency key with a different payload hash causes `409_conflict`.
-- Empirical `completed` commits must satisfy one of: `artifacts_non_empty`, `no_artifacts_reason_non_empty`.
 - Prepare item payloads must be structured objects; stringified JSON item payloads are invalid.
 - Uploading metadata wrappers instead of raw file bytes violates the upload contract.
 - Finalize requires a valid prepared batch token and staged uploads from that batch.