…ER env

Phase 2 of the unified resolution chain. The resolver now honors a CLI
override (`--pm`, `--runner`) and its env-var mirror (`RUNNER_PM`,
`RUNNER_RUNNER`), with CLI winning over env. Both flags are global so
they apply to every subcommand and to the `run` alias binary.

`ResolutionOverrides::from_cli_and_env` collects sources and returns a
typed bundle tagged with `OverrideOrigin` for later diagnostics. The
parse step is split into `from_values` so tests can inject env values
without touching the process environment.

Override semantics for `resolve_node_pm`:
- A PM override that can dispatch `package.json` scripts (Node ecosystem
  plus Deno) wins immediately and is recorded as `Override(origin)`.
- A cross-ecosystem override like `--pm cargo` falls through to
  detection rather than hijacking Node script dispatch; Phase 5 will
  surface this as a warning.
- The legacy `npm` fallback is preserved so behavior is unchanged when
  no override and no detection signal are present.

`PackageManager::from_label` / `TaskRunner::from_label` parse the user-
supplied values; `all()` enumerates the valid values for error
messages. The `bundle` alias for Bundler and `go-task` alias for the
GoTask runner are accepted so users can spell the CLI name they know.

The `--runner` value is parsed and stored for now; source-selection
semantics land with Phase 8.

Phase 3 of the unified resolution chain. A `runner.toml` at the project
root now contributes per-ecosystem PM overrides that win over detection
but lose to CLI/env.

`src/config.rs` (new) loads `runner.toml`, deserializes the full schema
(`[pm]`, `[task_runner]`, `[resolution]`, `[sources.*]`) and rejects
unknown keys via `serde(deny_unknown_fields)` so typos surface at parse
time. Only `[pm]` is consumed today — the rest is captured for later
phases.

Resolver changes:
- `OverrideOrigin` gains `ConfigFile { path }` and is now `Clone`
  instead of `Copy` (PathBuf can't be Copy). PmOverride/RunnerOverride/
  ResolvedPm follow.
- `ResolutionOverrides.pm_by_ecosystem: HashMap<Ecosystem, PmOverride>`
  carries the per-ecosystem map sourced from `[pm].node`/`[pm].python`.
- `Resolver::resolve_node_pm` consults the map (Node entry, then Deno
  entry) after CLI/env falls through.
- `from_cli_and_env` / `from_values` take an `Option<&LoadedConfig>`
  argument and surface ecosystem-mismatch errors (`[pm].node = "cargo"`
  fails fast).

`types::PackageManager::ecosystem()` plus the new `Ecosystem` enum
formalize the Node/Deno/Python/Rust/Go/Ruby/PHP mapping the resolver
needs to keep CLI overrides scoped to compatible ecosystems.

`lib::dispatch` and `dispatch_run_alias` load the config once and pass
it through `from_cli_and_env`.

Phase 4 of the unified resolution chain. The resolver now consults
package.json's `packageManager` field and the new
`devEngines.packageManager` field (OpenJS proposal, npm 10.9+) between
the CLI/env/config overrides and the lockfile fallback.

`tool::node`:
- `parse_package_manager_spec` extracts the `name@version` form once and
  is shared between the legacy field and devEngines entries.
- `DevEngines` / `DevEnginesPmField` (untagged enum) accept either a
  single object or an array per the spec.
- `OnFail` carries the four proposal values mapped to runner's three
  effective modes (`download` collapses to `Warn` — runner is not an
  installer). Defaults follow the proposal: single object → `Error`,
  last array entry → `Error`, prior entries → `Ignore`.
- `detect_pm_from_manifest` returns `Option<ManifestPmDecl>` favoring
  the legacy field, falling through to `devEngines`, and picking the
  last resolvable array entry.

Resolver:
- New `ResolutionStep::ManifestPackageManager` and
  `ManifestDevEngines { on_fail }` variants.
- `resolve_node_pm` consults `detect_pm_from_manifest` between
  config-sourced overrides and the lockfile fallback; manifest wins over
  lockfile per Corepack semantics.
- `cross_check_against_lockfile` emits a `package.json` warning when
  the declared PM disagrees with the detected lockfile signal,
  attributing the discrepancy and telling the user to regenerate the
  lockfile.
- `ResolvedPm` gains a `warnings` field so resolver-time warnings
  travel back to the caller.

`cmd::run::build_run_command` prints resolver warnings before spawning
the underlying command. `cmd::print_warning_slice` is the shared
formatter used by both `print_warnings(&ctx)` and the resolver path.

Phase 5 of the unified resolution chain. When no override, manifest, or
lockfile signal selects a package manager, the resolver now walks `$PATH`
in canonical order (`bun > pnpm > yarn > npm`) and picks the first
installed binary instead of silently defaulting to `npm`. If nothing is
on `$PATH`, the user sees an actionable error that lists every source
that was checked and how to pin one.

New `--fallback <policy>` global flag (and `RUNNER_FALLBACK` env mirror,
`[resolution].fallback` in `runner.toml`) gates the behavior:
- `probe` (default) — PATH probe, error if nothing matches.
- `npm` — legacy silent fallback (opt-in for backwards compatibility).
- `error` — refuse to proceed without an explicit signal.

`devEngines.packageManager` onFail handling now plugs into the same
probe primitive:
- `ignore` — use the declared PM, no check.
- `warn` — emit a warning when the declared PM is missing from PATH but
  still attempt dispatch.
- `error` — bail immediately when the declared PM is missing.

`src/resolver/probe.rs` (new) is the pure PATH walk — `probe_in` takes
PATH and PATHEXT explicitly so unit tests can exercise it against a
temp directory. Windows shim resolution mirrors the approach used by
`tool::program::command`.

`Resolver::resolve_node_pm` now returns `Result<ResolvedPm>` so the
error-path policies and `onFail = error` declarations have somewhere to
land. All call sites updated.

…ripts

Phase 7 generalizes passthrough-wrapper detection so a package.json
script like \"build\": \"just build\" is recognized as a thin wrapper
around the underlying task runner — not just turbo.

New `src/tool/passthrough.rs` hosts a conservative one-shot matcher
(`detect_target`) that returns the `TaskRunner` a script wraps:
- Turbo (delegates to the existing `tool::turbo::is_self_passthrough`
  which carries its detailed shell-token validation).
- just / make / go-task (`task`) / bacon (positional task name).
- nx / mise (`run <task>` shape).

Any shell-active tail (control operators, redirects, `$` expansion,
backtick substitution) keeps a script visible so wrappers that actually
do work — `just test && echo done`, `task lint > out.log` — are not
silently collapsed.

`Task.passthrough_to_turbo: bool` becomes
`Task.passthrough_to: Option<TaskRunner>`. The completion dedup logic
in `cli::task_candidates_from` checks the new field against
`TaskRunner::task_source()`: a `package.json` script is hidden only
when its declared target runner also has a same-named task entry to
absorb it (peer-source check), so wrappers to runners without task
extraction (nx, mise) stay visible.

Phase 8 collapses the two task-selection paths in cmd::run — the
non-Deno source_priority path and the Deno-only (depth, display_order)
path — into one. The unified sort key is:

  (source_priority, source_depth, display_order, alias_of.is_some())

source_priority keeps the Turbo > PackageJson > others ordering it has
today, and source_depth is now consulted for every selection: among
ties on source_priority, the source whose config sits in the nearest
ancestor of the current directory wins. Deno's existing
deno_task_priority is removed in favor of the shared source_depth
helper.

Behavior at parity for most projects (configs at root collapse depth
to a no-op tiebreak; display_order takes over). The win is in nested
Cargo/Make/Just layouts where additional `walk_upwards` source
implementations can later plug into source_depth and immediately
benefit from the nearest-config tiebreak the Deno path proved out.

Phase 6 (minimal scope). Adds a global `--explain` flag and matching
`RUNNER_EXPLAIN` env var that emit a single-line attribution to stderr
after PM resolution:

  · runner resolved: yarn via package.json "packageManager"

The `doctor` and `why` subcommands described in the spec are deferred —
this slice ships the highest-value piece (attribution at run time) and
leaves the standalone diagnostic tools for a later change.

`ResolvedPm::describe` renders each `ResolutionStep` variant into a
human-readable label:
- Override(CliFlag) / Override(EnvVar) / Override(ConfigFile { path })
- ManifestPackageManager / ManifestDevEngines { on_fail }
- Lockfile / PathProbe { binary } / LegacyNpmFallback

`ResolutionOverrides` gains an `explain` flag plus a
`from_values_with_explain` constructor; `from_cli_and_env` takes the
new `cli_explain` bool. The CLI value (`Some(true)` when --explain is
passed) wins over env (non-empty truthy values: anything except `0`,
`false`, `no`, `off`).

The plain `from_values` helper is now `#[cfg(test)]` since production
goes through `from_values_with_explain`; tests keep using the shorter
form.

Both the no-task fallback paths in cmd::run were bypassing the
resolver: `--pm npm` against a Bun-detected project would still trigger
the bun-test special case, and `runner run eslint --pm yarn` would
silently dispatch through whichever PM detection picked. Both now
consult ResolutionOverrides first and fall back to detected context
only when no override applies, matching the precedence used by the
PackageJson dispatch path.

- `run_pm_exec_fallback(ctx, overrides, target, args)` — pulls the
  script-dispatching PM out of the override bundle (CLI/env first,
  then per-ecosystem config) before falling back to `ctx.primary_pm`.
- `run_bun_test_fallback(ctx, overrides, task, args)` — only fires
  when the effective PM (override or detected) is actually Bun.
- `should_use_bun_test_fallback` checks the override chain so
  `--pm npm` correctly suppresses the fallback even when bun.lock is
  detected.
- New helpers: `exec_pm_for_overrides` (extracts an override-chosen
  PM, preferring CLI/env over config) and `pm_dispatches_scripts`
  (small predicate matching the existing exec-cmd-supporting set).

CLI doc comments for `--pm`, `--runner`, `--fallback`, and `--explain`
no longer claim they "fall back to env vars" via clap — env reads
live in the resolver, so the docs now name `crate::resolver` as the
reader to avoid suggesting clap's `env` attribute is in play.

Two new tests prove the precedence:
- `--pm npm` against a Bun-detected ctx suppresses bun-test fallback.
- `--pm bun` against an empty ctx still enables it.

`source_dir` previously only walked upward for `PackageJson` and
`DenoJson` (via per-tool helpers that respect workspace boundaries).
Every other source (`Makefile`, `Justfile`, `Taskfile`, `BaconToml`,
`TurboJson`) used `find_first(root, …)` which only checked the literal
project root, so in a nested layout the depth tiebreak always
collapsed to `0` or `usize::MAX` — making it a no-op once
`source_priority` tied.

Now every non-workspace-aware source consults
`tool::files::find_first_upwards`, which walks ancestors and stops at
the VCS boundary (`.git`/`.jj`). A member project running `runner
build` inside `apps/api/` resolves the workspace-root `Makefile` with
a finite depth, and the resolver's `(source_priority, source_depth,
display_order, alias_last)` key correctly picks the nearest config
when ties happen across same-priority sources.

`PackageJson`, `DenoJson`, and `CargoAliases` keep their bespoke
walkers because each models workspace membership rules (member globs
in `pnpm-workspace.yaml`, `deno.json`, and the `.cargo/config.toml`
chain) that a plain ancestor walk doesn't capture.

Resolver work introduces new public surface (`runner doctor`,
`runner why`, `--pm`/`--runner`/`--fallback`/`--explain` global flags,
`runner.toml` config) plus a small but real API break — the resolver
chain reorders detection-vs-declaration precedence and `Task` swaps
its `passthrough_to_turbo: bool` field for `passthrough_to:
Option<TaskRunner>`. Minor bump per SemVer; CodeRabbit's pre-merge
checks flagged both the missing changelog entry and the missing
version bump on the PR.

Cargo.lock regenerated on next cargo invocation; no other artifacts
change.

`apply_manifest_on_fail` now takes `is_present` and `check_version`
closures so the `onFail = Error` branches are testable. Production
calls in `Resolver::resolve_node_pm` wire in the real implementations
(`real_binary_check` walks `$PATH` via `probe::probe`,
`check_version_constraint` spawns `<pm> --version`); unit tests pass
deterministic mocks that don't depend on the host system.

Closes the test-coverage gap flagged in the internal review — neither
`Error + missing binary` nor `Error + version mismatch` was previously
exercisable without controlling the real PATH and binary versions.
Six new tests cover the full matrix:

- `manifest_on_fail_error_bails_when_binary_missing`
- `manifest_on_fail_error_bails_when_version_mismatched`
- `manifest_on_fail_warn_emits_warning_when_binary_missing`
- `manifest_on_fail_warn_emits_warning_on_version_mismatch`
- `manifest_on_fail_ignore_skips_all_checks` (uses panicking
  checkers to prove the early return)
- `manifest_on_fail_unverifiable_version_continues_without_warning`

Behavior unchanged for callers — the production path wires the same
`probe::probe` + `check_version_constraint` calls that lived inline
before, just through `FnOnce` parameters.

`ResolutionOverrides::from_values_with_explain` was 9 positional
`Option<&str>` parameters — adding any new override source (`--on-
mismatch` / `RUNNER_ON_MISMATCH` would be the next one) meant a 2-arg
expansion across every test site plus the production wrapper. The
`#[allow(clippy::too_many_arguments)]` was a sign of the underlying
shape problem, not a real local concern.

Introduces three new types in `src/resolver/mod.rs`:

- `OverrideSources<'a>` — bundles every CLI/env input the resolver
  consumes (pm/runner/fallback/explain + config). `Default`-able so
  tests construct partial bundles with `..OverrideSources::default()`.
- `SourceValue<'a>` — `{ cli: Option<&str>, env: Option<&str> }` for
  string-typed overrides.
- `ExplainSource<'a>` — same shape but `cli: bool` for the
  presence-flag pattern used by `--explain`.

`from_sources(OverrideSources)` is the new pure-function constructor.
`from_cli_and_env` becomes a thin wrapper that reads `std::env` and
builds the struct. `from_values_with_explain` is removed entirely;
`from_values` survives as a `#[cfg(test)]` adapter so the existing 14
test sites don't churn, but the doc points new tests at `from_sources`
directly:

    ResolutionOverrides::from_sources(OverrideSources {
        pm: SourceValue { cli: Some("yarn"), env: None },
        ..OverrideSources::default()
    })

One new test (`from_sources_builder_is_ergonomic_for_partial_overrides`)
demonstrates the target shape so future migrations have a pattern to
follow.

`from_values` was introduced in the previous OverrideSources refactor
as a transitional `#[cfg(test)]` adapter so the 14 existing test sites
didn't have to migrate at the same time. With the new struct shape
proven, the positional-argument helper is now dead weight — a future
override source would still need to update its 7-arg signature plus
every call site.

All 14 test sites now construct `OverrideSources` directly:

    ResolutionOverrides::from_sources(OverrideSources {
        pm: SourceValue { cli: Some("yarn"), env: None },
        ..OverrideSources::default()
    })

The shape is slightly more lines per call but each value is named, so
tests read as "what override is this exercising" rather than "what
position is this argument in."

`from_values` and its callsite comments are deleted. The test imports
gain `OverrideSources`, `SourceValue`, `ExplainSource`; the one test
that previously had a local `use` block (the ergonomics demo) drops
the redundant import since the module-level `use` covers it.

`completion_dir` only read `RUNNER_DIR` + cwd, so
`runner --dir /other-repo <TAB>` listed tasks from the shell's
working directory instead of `/other-repo`. Completion silently
disagreed with the dispatch that ran a moment later.

Add `cli_dir_from_argv` to scan the in-flight argv for `--dir`
(space + `=` forms, last occurrence wins to match clap) and thread
it into `resolve_completion_dir` ahead of the env var. The argv
walker skips past the first `--` because `clap_complete`'s bash
registration invokes the completer as `completer -- "${words[@]}"`;
direct invocation (no harness) still works because the start index
falls back to 1.

Five new tests pin: cli-over-env precedence, harness vs direct
invocation, equals form, last-wins for repeated flags, and the
None case.

`detect_pm_from_manifest` previously fell through to `devEngines`
whenever `parse_package_manager_spec` returned `None`, including when
the legacy `packageManager` field was present but malformed (typo like
`pnpmm@9`, unsupported PM, lone `@9`). That silently substituted a PM
the user never declared.

Corepack treats `packageManager` as authoritative when present, so a
present-but-unparseable value must NOT promote a different declaration.
Trim the field, treat whitespace-only as "not set" (round-trips editor
trailing-newline mishaps), and when the trimmed value is non-empty
short-circuit with whatever `parse_package_manager_spec` returns — so
unparseable → `None`, dropping the resolver to step 6 (lockfile) / step
7 (PATH probe) instead of synthesising a `devEngines` decision.

Two regression tests pin both directions: unparseable spec blocks
`devEngines`; whitespace-only spec still lets `devEngines` win.

The prior commit (`stop unparseable packageManager from electing
devEngines`) blocked the silent substitution, but the resolver still
dropped to lockfile / PATH probe with zero diagnostic. `doctor --json`
showed `manifest_pm: null` with no hint that the field was the cause,
so a user with a typo like `pnpmm@9` had to inspect their own
`package.json` to figure out why the declared PM was ignored.

Add `DetectionWarning::UnparseablePackageManager { raw }` and a new
`tool::node::detect_pm_field_with_diagnostics` helper that returns
`(Option<PackageManager>, Option<raw>)`. `detect_package_managers`
calls it and pushes the warning when the trimmed value is present
but non-parseable. Every surface that already prints `ctx.warnings`
(run / list / info / doctor / why) now echoes the typo back verbatim
with the accepted vocabulary on the same line:

  warn: package.json: packageManager value "[email protected]" doesn't name
  a script-dispatching package manager (expected one of
  npm|pnpm|yarn|bun|deno, optionally followed by @<version>);
  declaration ignored, falling back to lockfile / PATH probe

One regression test pins both invariants: the raw string appears
verbatim (so trailing whitespace / control chars survive) and the
accepted vocabulary is listed.

`parse_package_manager_spec` collapsed `"pnpm@"` and bare `"pnpm"`
into the same `(Pnpm, None)` result via `(!v.is_empty()).then(...)`.
Both stayed "valid" — the `@` plus empty RHS silently disappeared.

`"pnpm@"` is almost never intentional; it's `"[email protected]"` with the
version chopped off. The earlier `UnparseablePackageManager` plumbing
(`6c1d037`, `7c3b54b`) only fires when the parser returns `None`, so
this typo never surfaced — the resolver picked Pnpm with no version
constraint and the user never learned their pin was dropped.

Match `Some((_, ""))` first and bail. Bare `"pnpm"` (no `@` at all)
still parses as `(Pnpm, None)`; only the truncated form is rejected,
which is the signal the detection-layer warning needs to fire.

Three regression tests: trailing-`@` rejected for `pnpm`/`npm`, bare
name still accepted, and the end-to-end `detect_pm_from_manifest`
path returns `None` for `"packageManager": "pnpm@"`.