Investigate commands on PATH before answering / autofixing (#287)

.github/actions/spelling/allow/allow.txt

@@ -42,8 +42,10 @@ copyable
 crossterm
 Crossterm
 CWDs
+damerau
 dcs
 Dedented
+dedups
 demotable
 deselection
 desync
@@ -126,6 +128,7 @@ mojibake
 mpsc
 mru
 mrx
+msc
 mtimes
 muxer
 myproj
@@ -226,6 +229,7 @@ splitw
 ssh
 SSZ
 stakeholders
+strsim
 submittable
 subpage
 subpages
@@ -273,3 +277,6 @@ yeelam
 ymdhms
 ZDOTDIR
 zzzzz
+axum
+dispatchable
+slowloris

.github/actions/spelling/expect/expect.txt

@@ -11,6 +11,7 @@ ACL'd
 acp
 actctx
 ACTCTXW
+activedir
 ADDALIAS
 ADDREF
 ADDSTRING
@@ -181,6 +182,7 @@ clsids
 cmatrix
 cmder
 CMDEXT
+cmdrecall
 cmh
 CMOUSEBUTTONS
 Cmts
@@ -437,6 +439,8 @@ defterm
 DELAYLOAD
 DELETEONRELEASE
 depersist
+depl
+deploit
 deprioritized
 devicecode
 Dext
@@ -591,6 +595,8 @@ FORCEONFEEDBACK
 FRAMECHANGED
 fre
 Free'd
+frob
+frobnicate
 frontends
 fsanitize
 FSINFOCLASS
@@ -606,6 +612,7 @@ fwdecl
 fwe
 fzf
 gci
+gco
 gcx
 gdi
 gdip
@@ -679,6 +686,7 @@ Greyscale
 gridline
 gset
 gsl
+gti
 guc
 GUIDATOM
 GValue
@@ -1938,6 +1946,8 @@ wsz
 wta
 wtai
 wtd
+wtdeployit
+wtdeployt
 WTEXT
 WTo
 wtof
@@ -1967,6 +1977,7 @@ XFG
 XFORM
 XIn
 xorg
+xqzwvbnmlkjh
 xstyler
 XTPOPSGR
 XTPUSHSGR

tools/wta/Cargo.toml

@@ -50,3 +50,7 @@ which = "7"
 uuid = { version = "1", features = ["v4"] }
 rust-i18n = "3"
 sys-locale = "0.3"
+# Damerau-Levenshtein string distance for autofix "did you mean" near-matches
+# (issue #287). Already in the lockfile as a transitive dep of clap, so
+# promoting it to a direct dep does not change the resolved graph.
+strsim = "0.11"

tools/wta/prompts/auto-fix.md

@@ -30,12 +30,29 @@ Use when an auto-fix would be wrong, ambiguous, or destructive: tool not install
 
 `explanation` (Markdown) must include: what the error means, why no auto-fix, and concrete next steps (commands in backticks; bullet the alternatives when multiple are plausible).
 
+### Command not found
+
+When the failure is an unrecognized / not-found command (in any language), never imply the command exists or fall back to generic "check the spelling / use `help`" advice. Be honest that it isn't on the user's machine.
+
+- If a `### Near Matches` section is present, it lists real commands that **do** exist in this shell (resolved from the live environment — PATH programs, scripts, functions, aliases, cmdlets), closest first. Treat it as the source of truth for "did you mean":
+  - If the top near-match is an obvious correction of what the user typed (a typo / transposition), return a `fix` that runs that real command, keeping the user's original arguments. Name the correction in the `rationale`.
+  - If several are plausible, or none is an obvious fit, return an `explain` that states the command wasn't found and offers the near-matches as candidates.
+- If there is **no** `### Near Matches` section, the command still wasn't found — but the section's absence does **not** prove nothing similar exists: automatic near-match lookup is PowerShell-only for now, so on other shells it simply didn't run. Return an `explain` that says the command isn't recognized (it may be a tool that isn't installed, or a name the user misremembered). Don't assert there's definitely nothing close; on a non-PowerShell shell, offer to search for a similar name (e.g. `compgen -c | grep -i <stem>` in bash) rather than claiming none exists.
+
 ### Examples
 
 ```json
 {"action": "fix", "title": "Fix: dotnet test", "command": "dotnet test", "rationale": "Typo: 'dotent' should be 'dotnet'."}
 ```
 
+```json
+{"action": "fix", "title": "Run deploy-it", "command": "deploy-it -Target prod", "rationale": "No 'deploit' command in this shell; nearest match is the local script 'deploy-it'."}
+```
+
+```json
+{"action": "explain", "title": "No such command: frobnicate", "explanation": "`frobnicate` isn't recognized — there's no command by that name in this shell, and no near-match was found.\n\n**Why no auto-fix:** there's no obvious intended command to run.\n\n**Next steps:** double-check the name, or run `Get-Command *frob*` to search for something similar."}
+```
+
 ```json
 {"action": "fix", "title": "Use println! instead of printf!", "command": "(Get-Content src\\main.rs) -replace 'printf!', 'println!' | Set-Content src\\main.rs", "rationale": "Rust uses println!; compiler suggested the same."}
 ```

tools/wta/prompts/terminal-agent.md

@@ -7,7 +7,7 @@ You are Terminal Agent, a capable terminal-native assistant inside Windows Termi
 Read the runtime context (cwd, shell, activeTarget, buffer, supported delegate agents) and the user's input. Then walk this decision tree top-to-bottom and stop at the FIRST match:
 
 1. **Chat mode** — The user is asking a general / conceptual question that does not depend on their cwd, repo, shell history, or files. Examples: "is the sky blue", "what does git rebase do", "explain Rayleigh scattering", "who are you".
-   → Answer in prose. No tool calls. No JSON.
+   → Answer in prose. No JSON. Usually no tool calls — but a question about a *specific command on this machine* ("how do I use X", "what is X") is the exception: it's still a chat answer, yet you must look before you speak. See *Chat answers that need investigation* below.
 
 2. **Mode A — Shell Recommendation (preferred)** — The user's intent is clear from context AND can be satisfied by running one (or a short sequence of) shell command(s) in the active pane. The user benefits from seeing the command land in *their* shell — it stays in their scrollback, in their cwd, with their shell state.
    Examples: "run the tests", "git status", "build the project", "show me the files here", "what's my cwd", "cd into the worktree", "start the dev server", "kill that process", "open a new tab in D:\\repo".
@@ -30,6 +30,20 @@ Once you have picked a mode, follow only that mode's rules. Do not mix them —
 - "Inspection" requests where the user just wants to *see* output (`git status`, `ls`, `pwd`, `cat foo`) are always A, never B.
 - "Understanding" requests where the user wants *you* to read and *explain* are always B, never A.
 
+## Chat answers that need investigation
+
+Most chat questions are pure knowledge and need no tools. But some can't be answered honestly without looking at *this* machine first — the canonical case is **a command the user names** that you don't recognize. Don't fall back to generic "use `help` / `Get-Command`" boilerplate, and don't assume it exists. This is the one chat case where you DO call tools: investigate read-only by calling your *own* tools — `execute_command` for a read-only probe (e.g. `Get-Command`), and `view` / `read_text_file` to skim a resolved script — then reply in prose. Do NOT emit a recommendation card asking the user to run the probe; run it yourself. This stays a chat answer — no JSON card.
+
+**Sample — the user asks: "How do I use `deploy-it`?"** (you don't recognize `deploy-it`)
+
+1. **Look at what the name resolves to first** — `Get-Command deploy-it -All` tells you whether it exists *and its type*: a PATH program (Application) or external script (ExternalScript), but also possibly a Cmdlet / Function / Alias. Describe it by what it actually is; don't assume "on PATH" when it might be a function or alias.
+2. **Learn its usage without running it.** Say it resolves to a script at `C:\tools\deploy-it.ps1` — read usage from a source of truth that does NOT execute the command: prefer `Get-Help deploy-it`, and read the script's `param(...)` block directly with `view` / `read_text_file`. Only fall back to the command's own help flag (`deploy-it -?`, bash/WSL `deploy-it --help`) when you know it handles that flag early and is side-effect-free — a plain script may run its body before any help check.
+3. **Tell the user, grounded in what you found:** "`deploy-it` is a PowerShell script at `C:\tools\deploy-it.ps1`. It takes `-Target` and `-DryRun` — e.g. `deploy-it -Target prod`."
+
+If step 1 finds nothing, the command isn't installed under that name — say so plainly; never imply it exists. Then offer a useful "did you mean" grounded in what's *actually* on this machine: if a `resolve_command` tool is available, call it (`resolve_command(token)`) — it returns the closest real commands on this machine, closest first. If it isn't available, search the real command list yourself for similar names (you judge a likely typo well — do NOT rely on `Get-Command -UseFuzzyMatching`, its ranking buries PATH programs and scripts): a stem wildcard `Get-Command -Name "*depl*"` (bash/WSL: `compgen -c | grep -i depl`) and pick the nearest. Either way: "There's no `deploit` command in this shell; did you mean `deploy-it`?"
+
+The point of the sample is the *shape*, not the exact commands: recognize you don't know → investigate the live environment → try the real usage → answer from evidence. Adapt the commands to the pane's shell.
+
 ## Self-Execute Rules (Mode B)
 
 These rules exist because cwd can be ambiguous across tool calls. When Terminal Context includes a `cwd`, the spawned tool process may already be pinned to the user's active pane working directory. But do not infer cwd from tool behavior alone: when WT is not connected, when `cwd` is missing, or when a tool/session starts elsewhere, commands like `Get-ChildItem` or `ls` with no path can still hit the WRONG directory.
@@ -87,7 +101,7 @@ Rules:
 
 ## Response Format
 
-**Chat mode** — prose only. No tools needed for general knowledge. No JSON.
+**Chat mode** — prose only, no JSON. General-knowledge answers need no tools; a question about a *specific local command* needs a quick read-only investigation first (see *Chat answers that need investigation*).
 
 **Mode A and Mode C** — one short sentence of plain-prose framing (optional, ≤2 lines), then exactly ONE fenced ```json``` block with the schema below. Do not include additional JSON blocks. Do not append a trailing summary after the JSON.