fix(task): merge TOML task block into same-named file task and surface resolved dir

[jdx]

Summary

Fixes two related issues raised in #8673:

1. TOML [tasks.<name>] block silently discarded when a file task with the same name exists. A user writing [tasks.my-script] env = { API_TOKEN = "secret" } in mise.toml alongside an auto-discovered .mise/tasks/my-script would get <unset> at runtime — the file task completely won and the TOML block's metadata was lost. Now the TOML block is treated as a metadata overlay: env, description, dir, aliases, depends, tools, etc. are merged into the file task while run/file/config_source stay with the file task base.

2. mise tasks ls --json and mise tasks info --json reported dir: null for tasks that inherited task_config.dir even when runtime correctly used the inherited dir. The JSON output now reports the resolved dir so consumers see where the task will actually run.

Changes

• src/task/mod.rs: new Task::merge_toml_overlay that overlays a TOML-block's non-default fields onto a file task.
• src/config/mod.rs: new merge_file_and_config_tasks helper used by both load_tasks_in_dir (local) and load_config_and_file_tasks (global) so the merge applies consistently in both paths.
• src/cli/tasks/ls.rs, src/cli/tasks/info.rs: resolve task.dir(config) for the dir field in JSON output.

Test plan

• New e2e/tasks/test_task_file_toml_merge — file task + TOML overlay produces merged env/description
• New e2e/tasks/test_task_ls_json_resolved_dir — JSON reports inherited dir instead of null
• Existing e2e/tasks/test_task_config_dir_inheritance still passes
• mise run test:e2e tasks (all 146 task tests) pass
• mise run test:unit passes (649 tests)
• mise run lint-fix clean

---

Note

Medium Risk
Changes task-loading precedence and env/dep resolution semantics for same-named TOML+file tasks, which could affect existing projects that relied on the previous override behavior; JSON output shape also changes (dir becomes non-null in more cases).

Overview
Fixes task precedence so a TOML [tasks.<name>] block is no longer dropped when an auto-discovered executable task with the same name exists; instead the TOML block overlays metadata (env/vars with correct relative-path resolution, description, aliases, deps including {{usage.*}} templates, dir, flags, tools, sandbox settings) onto the file task.

Updates mise tasks ls --json and mise tasks info --json to emit the resolved task directory (including inherited task_config.dir) and to include overlay env entries in displayed env lists. Adds/updates e2e coverage for TOML+file task merging and for resolved dir appearing in JSON outputs.

^{Reviewed by Cursor Bugbot for commit aa842f6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gemini-code-assist]

Code Review

This pull request introduces a mechanism to merge metadata from [tasks.<name>] TOML blocks into auto-discovered file tasks of the same name, allowing users to augment script-based tasks with environment variables, descriptions, and dependencies in mise.toml. It also updates the tasks ls --json and tasks info --json commands to report the resolved execution directory instead of the raw value. Feedback indicates that merging environment variables by simple extension may cause incorrect relative path resolution for .env files due to differing configuration sources between the script and the TOML file. Additionally, several metadata fields such as outputs, extends, and sandbox settings are currently missing from the merge logic.

[gemini-code-assist]

Merging env and vars by simply extending the vector will lead to incorrect resolution of relative paths in directives like _.file = ".env".

In mise, environment directives are resolved relative to the task's config_source. For a file task, this is the script's location (e.g., .mise/tasks/my-script), while for the TOML overlay, it is the mise.toml location. By moving directives from the TOML task into the file task, they will be resolved relative to the script's directory instead of the mise.toml directory, which is likely not what the user expects.

To fix this, the Task structure or the EnvResults::resolve logic might need to be updated to track the source path for each individual directive, rather than assuming a single source for the entire task.

[gemini-code-assist]

The merge_toml_overlay method is missing several metadata fields that should likely be included in the overlay logic to ensure a complete merge of TOML-defined task metadata onto file tasks. Specifically, the following fields are currently omitted:

• outputs: Users might want to define or override task caching behavior (e.g., outputs = ["target/bin"]) in mise.toml for an auto-discovered script.
• extends: A file task might want to extend a template defined in the config hierarchy.
• Sandbox fields (deny_all, deny_read, deny_write, deny_net, deny_env, allow_read, allow_write, allow_net, allow_env): These are critical for security and should be configurable via the TOML overlay.

Consider adding these fields to the merge logic.

[greptile-apps]

Greptile Summary

This PR fixes two task-related issues from #8673: [tasks.<name>] TOML blocks that share a name with an auto-discovered file task now act as metadata overlays (merging env, description, dir, aliases, depends, tools, etc.) instead of being silently discarded, and mise tasks ls/info --json now reports the resolved directory (including task_config.dir inheritance) instead of null.

The implementation introduces overlay_env/overlay_vars fields on Task that carry each directive's origin path (so _.file = \".env\" in a TOML overlay resolves relative to the TOML file, not the script path), a merge_toml_overlay method, and a merge_file_and_config_tasks helper used in both load_tasks_in_dir and load_config_and_file_tasks. Previous review concerns about depends_raw and outputs were addressed in follow-up commits.

Confidence Score: 5/5

Safe to merge — all previous P1 concerns (depends_raw, outputs) were resolved in follow-up commits, and no new correctness issues were found.

All findings are P2 or lower. The overlay merge logic is well-implemented with proper raw-snapshot seeding, path-source preservation for env directives, and a cache guard that prevents cross-contamination. E2E coverage is thorough including the usage-template edge case.

No files require special attention.

Important Files Changed

Filename	Overview
src/task/mod.rs	Adds overlay_env/overlay_vars fields and merge_toml_overlay; correctly handles depends_raw seeding and outputs/sandbox merge as addressed in follow-up commits.
src/config/mod.rs	New merge_file_and_config_tasks helper consistently applies overlay logic in both load_tasks_in_dir and load_config_and_file_tasks; logic is straightforward and correct.
src/task/task_context_builder.rs	Cache guard at both read and write sites now checks overlay_env.is_empty(), preventing a TOML-overlaid file task from sharing or polluting a sibling task's cached env entry.
src/cli/tasks/ls.rs	JSON output now reports resolved dir via task.dir(config).await? and chains overlay_env into the env array; straightforward change.
src/cli/tasks/info.rs	Both human-readable and JSON output now display overlay_env; JSON additionally uses resolved dir. Note: human-readable display still shows raw task.dir (pre-existing), so inherited-only dirs remain hidden in text mode.
e2e/tasks/test_task_file_toml_merge	New e2e test covering env overlay, path-relative directives, description propagation, JSON surfacing, and overlay depends with {{usage.*}} templates.
e2e/tasks/test_task_ls_json_resolved_dir	New e2e test verifying that inherited task_config.dir appears in JSON output instead of null; covers both tasks ls and tasks info.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Config Loading] --> B[load_config_tasks\nTOML blocks]
    A --> C[load_file_tasks\nauto-discovered scripts]
    B --> D[merge_file_and_config_tasks]
    C --> D
    D --> E{Same name?}
    E -- Yes --> F[file task stays as base\nTask::merge_toml_overlay\nenv/vars to overlay_env/overlay_vars\ndescription, dir, aliases, depends,\noutputs, sandbox, etc.]
    E -- No --> G[keep as-is]
    F --> H[Merged Task]
    G --> H
    H --> I{JSON output?}
    I -- Yes --> J[task.dir config .await?\nresolved dir incl. inherited\ntask_config.dir]
    I -- No --> K[raw task.dir field]
    J --> L[JSON with resolved dir\n+ overlay_env in env array]
    K --> M[Human-readable output]

Loading

_{Reviews (3): Last reviewed commit: "test(task): update test_task_info snapsh..." | Re-trigger Greptile}

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.15 x -- echo	24.1 ± 0.6	23.4	30.4	1.00
mise x -- echo	24.4 ± 2.0	23.5	45.5	1.01 ± 0.08

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.15 env	23.5 ± 0.7	22.8	31.9	1.01 ± 0.04
mise env	23.4 ± 0.4	22.7	25.9	1.00

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.15 hook-env	24.2 ± 0.3	23.6	25.8	1.00 ± 0.02
mise hook-env	24.1 ± 0.4	23.5	25.8	1.00

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.15 ls	21.3 ± 0.4	20.5	22.8	1.00
mise ls	21.3 ± 0.4	20.5	22.8	1.00 ± 0.02

xtasks/test/perf

Command	mise-2026.4.15	mise	Variance
install (cached)	156ms	155ms	+0%
ls (cached)	81ms	81ms	+0%
bin-paths (cached)	86ms	85ms	+1%
task-ls (cached)	807ms	789ms	+2%

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8702080. Configure here.}