cli: error on unknown subcommand in multi-fn files

[danieljohnmorris]

Summary

ilo file.ilo wibble x on a multi-function file used to silently route to the FIRST declared function with ["wibble", "x"] as positional args, producing a misleading arity error like helper: expected 1 args, got 2 far from the cause. Filed as interactive-cli rerun5 P1.

Default-engine dispatch now checks the leading positional against the known function names and, when it doesn't match AND looks like an identifier, emits a friendly diagnostic listing the available functions instead.

The token-cost framing: silently routing an unknown subcommand wastes follow-up turns on an arity error the agent then has to chase back through the file. A direct "no such function 'wibble'; available: main, helper, ..." closes the loop in one read.

Repro

Before:

$ ilo file.ilo wibble x
{"code":"ILO-R004","message":"helper: expected 1 args, got 2",...}

After:

$ ilo file.ilo wibble x
error: no such function 'wibble' in file.ilo
available functions:
  helper
  main

  ilo file.ilo <func> [args...]   run a function

What's in the diff

• cli: error on unknown subcommand in multi-fn files — adds looks_like_subcommand_name (ASCII ident-shape check, exempts true/false/nil) and a new branch in the Default-engine dispatch that fires when the file has 2+ user functions and the leading positional is ident-shaped but unknown. Synthetic __lit_* decls are already filtered out of the listing per cli: restore documented auto-run for main and inline programs #307.
• test: regression coverage for unknown-subcommand error — eight new integration tests in tests/regression_cli_default.rs covering ident-shaped unknown subcommand, known subcommand happy path, __lit_* filtering, single-fn and inline pass-through, and numeric / quoted-string / bracketed-list leading-arg pass-through (the last three pin the shape guard so tests/eval_inline.rs unwrap_*_inline don't regress).
• examples: exercise subcommand dispatch across engines — examples/unknown-subcommand-listing.ilo with main + two helpers and -- run: / -- out: annotations, pinning the happy-path dispatch contracts across every engine via the examples harness.

Three new unit tests in src/main.rs also cover looks_like_subcommand_name directly.

Test plan

• Full test suite green: cargo test --release --features cranelift — 138 test binaries pass, 0 failures
• Clippy clean: cargo clippy --release --features cranelift --tests -- -D warnings
• cargo fmt --check clean
• Manual repro: ilo /tmp/repro.ilo wibble x produces the new error, ilo /tmp/repro.ilo helper 5 still works, ilo /tmp/repro.ilo still auto-runs main
• Single-fn file ilo dbl.ilo 21 still pass-throughs as before
• Inline ilo 'dbl x:n>n;*x 2' 21 still pass-throughs

Follow-ups

• VM, Tree, and Cranelift engines (when explicitly selected with --vm / --tree / --cranelift) still emit their backend-native "undefined function" error rather than the friendly listing. Default-engine covers the agent default-path which is the common case; lifting the guard to all engines would be a small follow-up if it surfaces.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!