PowerShell script exit codes collapse to 1 (script path passed without -File)

[Zebble]

Summary

RunScript() passes the temp script path to powershell.exe positionally, with no -File flag. PowerShell therefore treats it as -Command, and under -Command PowerShell 5.1 reports only 0 (success) or 1 (failure) — so a script's exit 2, exit 3, etc. all reach the server as 1.

https://github.com/amidaware/rmmagent/blob/master/agent/agent_windows.go#L153-L156

case "powershell":
    exe = getPowershellExe()
    cmdArgs = []string{"-NonInteractive", "-NoProfile", "-ExecutionPolicy", "Bypass", tmpfn.Name()}

The agent's own exit-code extraction (ws.ExitStatus()) is correct — the value is already collapsed by PowerShell before the agent sees it.

Why it matters

Script checks map return codes to severities via info_return_codes / warning_return_codes / success_return_codes. Any mapping that references a code >= 2 is silently dead — the configured severity never applies and the result falls through to whatever the unmapped-non-zero path does.

This fails silently and is close to invisible: the check "works", the output text is correct, and only a diff of the script's exit statements against the stored retcode reveals it. In a ~1,300-agent install we found several checks whose intended severities had never applied, including two cluster-health checks that had been filing genuine faults as informational.

Supporting data from that install: across 260 agents / ~1,240 stored script-check results, the only retcodes ever recorded were 0, 1 and 98 — never 2. (98 is set agent-side on timeout, not by the script.)

Reproduction

t.ps1:

exit 2

# current agent invocation
powershell.exe -NonInteractive -NoProfile -ExecutionPolicy Bypass t.ps1
echo %ERRORLEVEL%   ->  1        # expected 2

# with -File
powershell.exe -NonInteractive -NoProfile -ExecutionPolicy Bypass -File t.ps1
echo %ERRORLEVEL%   ->  2

Same collapse for exit 3, exit 98, etc. Windows PowerShell 5.1.

Note: simply adding -File is a breaking change

This looks like a one-word fix, but -File breaks argument binding. Script arguments are stored as free-form strings that contain the flag and value together (e.g. -IgnoreCheck {{client.Foo}} → -IgnoreCheck True, one argv element). -Command re-parses the command line so that binds; -File passes each argv element literally, so the parameter never binds:

# t2.ps1
param([string]$IgnoreCheck)
Write-Output "IgnoreCheck=[$IgnoreCheck]"
exit 2

passing a single argument "-IgnoreCheck True", as the agent does:

invocation	result	exit
current (positional path)	IgnoreCheck=[True]	1
-File	IgnoreCheck=[]	2
-Command "& 'script' args; exit $LASTEXITCODE"	IgnoreCheck=[True]	2

Suggested fix

Keep -Command, invoke via & (child scope, so the script's exit sets $LASTEXITCODE instead of terminating the host), and relay it explicitly:

case "powershell":
    exe = getPowershellExe()
    psCmd := fmt.Sprintf("& '%s'", strings.ReplaceAll(tmpfn.Name(), "'", "''"))
    if len(args) > 0 {
        psCmd += " " + strings.Join(args, " ")
    }
    psCmd += "; exit $LASTEXITCODE"
    cmdArgs = []string{"-NonInteractive", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", psCmd}

...with the later generic args append skipped for the powershell case, since they're already embedded.

Verified locally: this is the only formulation tested that preserves argument binding and propagates the real exit code.

Notes for maintainers

• Behaviour change: installs that worked around this (e.g. mapping 1 where the script exits 2) would see severities change once codes propagate. Probably worth a release note.
• Only the powershell branch is affected — python and cmd execute the file directly and already propagate exit codes.
• PowerShell 7 isn't a factor: getPowershellExe() (agent/utils.go) resolves powershell.exe only, with a System32\WindowsPowerShell\v1.0 fallback, and there are no pwsh references in the agent.
• Separate pre-existing issue, not addressed above: an argument value containing spaces doesn't bind under either formulation (-clientname Foo Bar Inc. binds as Foo). That's a function of how args are stored/joined rather than this invocation — mentioning it only so it isn't conflated with this bug.

Happy to open a PR if the suggested approach looks right.

[wh1te909]

known issue and yea we should eventually fix it properly but it would be a breaking change, in the meantime follow the docs here in order to get the correct exit code (need to use $host.SetShouldExit(EXITCODE)): https://docs.tacticalrmm.com/functions/scripting/#script-checks

[Zebble]

Thanks — $host.SetShouldExit() works, confirmed here under the agent's exact invocation. For anyone finding this later:

script does	agent records
exit 2	1
$host.SetShouldExit(2)	2
$host.SetShouldExit(3) + exit 3 + args	3, and args still bind

We've adopted $host.SetShouldExit(N) + exit N as the house pattern (SetShouldExit for the reported code, exit to actually stop).

On the breaking-change concern — one clarification that may narrow it, since I suspect -File is the assumed fix:

-File would be doubly breaking. It fixes exit codes but also breaks argument binding, because args are stored as single strings containing flag+value (-IgnoreCheck True as one argv element). -Command re-parses that so it binds; -File passes it literally so the parameter comes back empty:

script: param([string]$IgnoreCheck) ... exit 2
arg:    "-IgnoreCheck True"   (one element, as the agent passes it)

current : IgnoreCheck=[True]   exit=1     <- args fine, code wrong
-File   : IgnoreCheck=[]       exit=2     <- code fine, ARGS BROKEN

This formulation avoids that half of it — args keep binding exactly as today, because it's still -Command:

psCmd := fmt.Sprintf("& '%s'", strings.ReplaceAll(tmpfn.Name(), "'", "''"))
if len(args) > 0 {
    psCmd += " " + strings.Join(args, " ")
}
psCmd += "; exit $LASTEXITCODE"
cmdArgs = []string{"-NonInteractive", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", psCmd}

Invoking via & runs the script in a child scope, so its exit sets $LASTEXITCODE rather than terminating the host; the explicit relay then propagates it.

To be clear though — this doesn't make the change non-breaking, and I don't want to overstate it. Exit codes starting to propagate is the behaviour change you're describing: any install that mapped severities around the collapse (e.g. mapping 1 for a script that exits 2) would see those flip. It only removes the additional argument-binding breakage that -File would bring.

If you did want it fully non-breaking, the obvious route is opt-in — a per-script or global "propagate real exit codes" toggle, defaulting off, so existing installs are untouched and new scripts can use plain exit. Happy to put that together as a PR if it's a direction you'd take; equally happy to leave this as a docs-only matter, since SetShouldExit covers the practical need.

One unrelated thing noticed while testing, flagging so it isn't conflated: an argument value containing spaces doesn't bind under either formulation (-clientname Foo Bar Inc. binds as Foo). That's about how args are stored/joined rather than this invocation — happy to open a separate issue if it's news.