File task #USAGE variables inherit stale usage_* env vars when omitted

[x1f9-ricon]

Summary

File tasks that use #USAGE specs appear to inherit stale usage_* environment variables from the parent process when the corresponding optional arg/flag is omitted.

This surprised me because the generated usage_* variables look task-local, but an ambient usage_model can be mistaken for a flag supplied to the current invocation.

Reproduction

T=$(mktemp -d)
mkdir -p "$T/.mise/tasks"

cat > "$T/mise.toml" <<'TOML'
[settings]
experimental = true
quiet = true
task_output = "interleave"
TOML

cat > "$T/.mise/tasks/probe" <<'TASK'
#!/usr/bin/env bash
#USAGE flag "--model <model>"
#USAGE arg "[message]"
printf 'usage_model=%s\n' "${usage_model-UNSET}"
printf 'usage_message=%s\n' "${usage_message-UNSET}"
printf 'argv:'
printf ' <%s>' "$@"
printf '\n'
TASK
chmod +x "$T/.mise/tasks/probe"

usage_model=ambient-model usage_message=ambient-message MISE_TRUSTED_CONFIG_PATHS="$T" mise -C "$T" run -q probe
usage_model=ambient-model usage_message=ambient-message MISE_TRUSTED_CONFIG_PATHS="$T" mise -C "$T" run -q probe hello
usage_model=ambient-model usage_message=ambient-message MISE_TRUSTED_CONFIG_PATHS="$T" mise -C "$T" run -q probe --model explicit-model hello

rm -rf "$T"

Observed output:

usage_model=ambient-model
usage_message=ambient-message
argv: <>
usage_model=ambient-model
usage_message=hello
argv: <hello>
usage_model=explicit-model
usage_message=hello
argv: <--model> <explicit-model> <hello>

Expected behavior

For omitted optional args/flags, I expected mise/usage to either unset the generated variable or set it to empty for the task invocation. In the repro above, I expected:

usage_model=UNSET

or possibly:

usage_model=

but not the inherited parent value.

Why this matters

This can cause nested mise run invocations to accidentally treat a parent task's usage_* value as input to the child task.

A concrete case: a task wants --model to be explicit for the current invocation. If it checks usage_model, an inherited usage_model makes mise run child-task ... look as though --model was provided, even when it was not.

required=#true does appear to enforce actual CLI presence despite an inherited variable, so this is mostly a problem for optional or conditionally-required args/flags.

Question

Is this expected behavior? If not, would you be open to clearing/generated-overriding all usage_* variables for the task before applying parsed values?

If it is expected, is there a recommended way for a task to distinguish "flag omitted in this invocation" from "ambient usage_* value inherited from a parent task" without scanning argv manually?

Environment

mise 2026.4.20 macos-arm64 (2026-04-24)

mise doctor starts with:

version: 2026.4.20 macos-arm64 (2026-04-24)
activated: yes
shims_on_path: yes
self_update_available: yes

[ikma-ricon]

Follow-up after digging into usage directly: I think this is expected behavior, but the ergonomics are surprising enough that it is worth documenting on our side.

The key distinction is that usage only exports variables present in the parse output. For an optional arg/flag with no default, omission means no usage_<name> assignment is made for the child process. Since the task process inherits its parent environment, any ambient usage_<name> remains visible.

That gives a few distinct modes:

# No default: omission preserves any inherited value.
# This can be used as an ambient/default-from-caller channel, but it is risky for nested tasks.
#USAGE flag "--model <model>"
#USAGE arg "[message]"

# Explicit defaults: omission overwrites inherited values and makes the task invocation-local.
# Good default for most mise file tasks.
#USAGE flag "--headless" default=#false
#USAGE flag "--model <model>" default=""
#USAGE arg "[message]" default=""

# Variadic/repeatable values can also be cleared with an empty default.
#USAGE flag "--meta <meta>" var=#true default=""

Confirmed with a small mise run repro: adding default="" or default=#false causes mise/usage to export empty/false values and prevents stale parent usage_* from leaking into the task. Explicit CLI values still win as expected.

So the practical pattern is: if a task reads usage_<name> and wants to know what was supplied to this invocation, give that arg/flag an explicit default. Only omit the default if inheriting an ambient usage_<name> is intentional.

I'm closing this as resolved from our side. A possible upstream doc improvement would be to call out this inheritance behavior in the #USAGE / file-task docs, because usage_* variable names look task-local at first glance.