@xelauvas/xela-cli 0.1.0

package/src/utils/powershell/parser.ts

@@ -0,0 +1,1804 @@
+import { execa } from 'execa'
+import { logForDebugging } from '../debug.js'
+import { memoizeWithLRU } from '../memoize.js'
+import { getCachedPowerShellPath } from '../shell/powershellDetection.js'
+import { jsonParse } from '../slowOperations.js'
+
+// ---------------------------------------------------------------------------
+// Public types describing the parsed output returned to callers.
+// These map to System.Management.Automation.Language AST classes.
+// Raw internal types (RawParsedOutput etc.) are defined further below.
+// ---------------------------------------------------------------------------
+
+/**
+ * The PowerShell AST element type for pipeline elements.
+ * Maps directly to CommandBaseAst derivatives in System.Management.Automation.Language.
+ */
+type PipelineElementType =
+  | 'CommandAst'
+  | 'CommandExpressionAst'
+  | 'ParenExpressionAst'
+
+/**
+ * The AST node type for individual command elements (arguments, expressions).
+ * Used to classify each element during the AST walk so TypeScript can derive
+ * security flags without extra Find-AstNodes calls in PowerShell.
+ */
+type CommandElementType =
+  | 'ScriptBlock'
+  | 'SubExpression'
+  | 'ExpandableString'
+  | 'MemberInvocation'
+  | 'Variable'
+  | 'StringConstant'
+  | 'Parameter'
+  | 'Other'
+
+/**
+ * A child node of a command element (one level deep). Populated for
+ * CommandParameterAst → .Argument (colon-bound parameters like
+ * `-InputObject:$env:SECRET`). Consumers check `child.type` to classify
+ * the bound value (Variable, StringConstant, Other) without parsing text.
+ */
+export type CommandElementChild = {
+  type: CommandElementType
+  text: string
+}
+
+/**
+ * The PowerShell AST statement type.
+ * Maps directly to StatementAst derivatives in System.Management.Automation.Language.
+ */
+type StatementType =
+  | 'PipelineAst'
+  | 'PipelineChainAst'
+  | 'AssignmentStatementAst'
+  | 'IfStatementAst'
+  | 'ForStatementAst'
+  | 'ForEachStatementAst'
+  | 'WhileStatementAst'
+  | 'DoWhileStatementAst'
+  | 'DoUntilStatementAst'
+  | 'SwitchStatementAst'
+  | 'TryStatementAst'
+  | 'TrapStatementAst'
+  | 'FunctionDefinitionAst'
+  | 'DataStatementAst'
+  | 'UnknownStatementAst'
+
+/**
+ * A command invocation within a pipeline segment.
+ */
+export type ParsedCommandElement = {
+  /** The command/cmdlet name (e.g., "Get-ChildItem", "git") */
+  name: string
+  /** The command name type: cmdlet, application (exe), or unknown */
+  nameType: 'cmdlet' | 'application' | 'unknown'
+  /** The AST element type from PowerShell's parser */
+  elementType: PipelineElementType
+  /** All arguments as strings (includes flags like "-Recurse") */
+  args: string[]
+  /** The full text of this command element */
+  text: string
+  /** AST node types for each element in this command (arguments, expressions, etc.) */
+  elementTypes?: CommandElementType[]
+  /**
+   * Child nodes of each argument, aligned with `args[]` (so
+   * `children[i]` ↔ `args[i]` ↔ `elementTypes[i+1]`). Only populated for
+   * Parameter elements with a colon-bound argument. Undefined for elements
+   * with no children. Lets consumers check `children[i].some(c => c.type
+   * !== 'StringConstant')` instead of parsing the arg text for `:` + `$`.
+   */
+  children?: (CommandElementChild[] | undefined)[]
+  /** Redirections on this command element (from nested commands in && / || chains) */
+  redirections?: ParsedRedirection[]
+}
+
+/**
+ * A redirection found in the command.
+ */
+type ParsedRedirection = {
+  /** The redirection operator */
+  operator: '>' | '>>' | '2>' | '2>>' | '*>' | '*>>' | '2>&1'
+  /** The target (file path or stream number) */
+  target: string
+  /** Whether this is a merging redirection like 2>&1 */
+  isMerging: boolean
+}
+
+/**
+ * A parsed statement from PowerShell.
+ * Can be a pipeline, assignment, control flow statement, etc.
+ */
+type ParsedStatement = {
+  /** The AST statement type from PowerShell's parser */
+  statementType: StatementType
+  /** Individual commands in this statement (for pipelines) */
+  commands: ParsedCommandElement[]
+  /** Redirections on this statement */
+  redirections: ParsedRedirection[]
+  /** Full text of the statement */
+  text: string
+  /**
+   * For control flow statements (if, for, foreach, while, try, etc.),
+   * commands found recursively inside the body blocks.
+   * Uses FindAll() to extract ALL nested CommandAst nodes at any depth.
+   */
+  nestedCommands?: ParsedCommandElement[]
+  /**
+   * Security-relevant AST patterns found via FindAll() on the entire statement,
+   * regardless of statement type. This catches patterns that elementTypes may
+   * miss (e.g. member invocations inside assignments, subexpressions in
+   * non-pipeline statements). Computed in the PS1 script using instanceof
+   * checks against the PowerShell AST type system.
+   */
+  securityPatterns?: {
+    hasMemberInvocations?: boolean
+    hasSubExpressions?: boolean
+    hasExpandableStrings?: boolean
+    hasScriptBlocks?: boolean
+  }
+}
+
+/**
+ * A variable reference found in the command.
+ */
+type ParsedVariable = {
+  /** The variable path (e.g., "HOME", "env:PATH", "global:x") */
+  path: string
+  /** Whether this variable uses splatting (@var instead of $var) */
+  isSplatted: boolean
+}
+
+/**
+ * A parse error from PowerShell's parser.
+ */
+type ParseError = {
+  message: string
+  errorId: string
+}
+
+/**
+ * The complete parsed result from the PowerShell AST parser.
+ */
+export type ParsedPowerShellCommand = {
+  /** Whether the command parsed successfully (no syntax errors) */
+  valid: boolean
+  /** Parse errors, if any */
+  errors: ParseError[]
+  /** Top-level statements, separated by ; or newlines */
+  statements: ParsedStatement[]
+  /** All variable references found */
+  variables: ParsedVariable[]
+  /** Whether the token stream contains a stop-parsing (--%) token */
+  hasStopParsing: boolean
+  /** The original command text */
+  originalCommand: string
+  /**
+   * All .NET type literals found anywhere in the AST (TypeExpressionAst +
+   * TypeConstraintAst). TypeName.FullName — the literal text as written, NOT
+   * the resolved .NET type (e.g. [int] → "int", not "System.Int32").
+   * Consumed by the CLM-allowlist check in powershellSecurity.ts.
+   */
+  typeLiterals?: string[]
+  /**
+   * Whether the command contains `using module` or `using assembly` statements.
+   * These load external code (modules/assemblies) and execute their top-level
+   * script body or module initializers. The using statement is a sibling of
+   * the named blocks on ScriptBlockAst, not a child, so it is not visible
+   * to Process-BlockStatements or any downstream command walker.
+   */
+  hasUsingStatements?: boolean
+  /**
+   * Whether the command contains `#Requires` directives (ScriptRequirements).
+   * `#Requires -Modules <name>` triggers module loading from PSModulePath.
+   */
+  hasScriptRequirements?: boolean
+}
+
+// ---------------------------------------------------------------------------
+
+// Default 5s is fine for interactive use (warm pwsh spawn is ~450ms). Windows
+// CI under Defender/AMSI load can exceed 5s on consecutive spawns even after
+// CAN_SPAWN_PARSE_SCRIPT() warms the JIT (run 23574701241 windows-shard-5:
+// attackVectors F1 hit 2×5s timeout → valid:false → 'ask' instead of 'deny').
+// Override via env for tests. Read inside parsePowerShellCommandImpl, not
+// top-level, per CLAUDE.md (globalSettings.env ordering).
+const DEFAULT_PARSE_TIMEOUT_MS = 5_000
+function getParseTimeoutMs(): number {
+  const env = process.env.CLAUDE_CODE_PWSH_PARSE_TIMEOUT_MS
+  if (env) {
+    const parsed = parseInt(env, 10)
+    if (!isNaN(parsed) && parsed > 0) return parsed
+  }
+  return DEFAULT_PARSE_TIMEOUT_MS
+}
+// MAX_COMMAND_LENGTH is derived from PARSE_SCRIPT_BODY.length below (after the
+// script body is defined) so it cannot go stale as the script grows.
+
+/**
+ * The PowerShell parse script inlined as a string constant.
+ * This avoids needing to read from disk at runtime (the file may not exist
+ * in bundled builds). The script uses the native PowerShell AST parser to
+ * analyze a command and output structured JSON.
+ */
+// Raw types describing PS script JSON output (exported for testing)
+export type RawCommandElement = {
+  type: string // .GetType().Name e.g. "StringConstantExpressionAst"
+  text: string // .Extent.Text
+  value?: string // .Value if available (resolves backtick escapes)
+  expressionType?: string // .Expression.GetType().Name for CommandExpressionAst
+  children?: { type: string; text: string }[] // CommandParameterAst.Argument, one level
+}
+
+export type RawRedirection = {
+  type: string // "FileRedirectionAst" or "MergingRedirectionAst"
+  append?: boolean // .Append (FileRedirectionAst only)
+  fromStream?: string // .FromStream.ToString() e.g. "Output", "Error", "All"
+  locationText?: string // .Location.Extent.Text (FileRedirectionAst only)
+}
+
+export type RawPipelineElement = {
+  type: string // .GetType().Name e.g. "CommandAst", "CommandExpressionAst"
+  text: string // .Extent.Text
+  commandElements?: RawCommandElement[]
+  redirections?: RawRedirection[]
+  expressionType?: string // for CommandExpressionAst: .Expression.GetType().Name
+}
+
+export type RawStatement = {
+  type: string // .GetType().Name e.g. "PipelineAst", "IfStatementAst", "TrapStatementAst"
+  text: string // .Extent.Text
+  elements?: RawPipelineElement[] // for PipelineAst: the pipeline elements
+  nestedCommands?: RawPipelineElement[] // commands found via FindAll (all statement types)
+  redirections?: RawRedirection[] // FileRedirectionAst found via FindAll (non-PipelineAst only)
+  securityPatterns?: {
+    // Security-relevant AST node types found via FindAll on the statement
+    hasMemberInvocations?: boolean
+    hasSubExpressions?: boolean
+    hasExpandableStrings?: boolean
+    hasScriptBlocks?: boolean
+  }
+}
+
+type RawParsedOutput = {
+  valid: boolean
+  errors: { message: string; errorId: string }[]
+  statements: RawStatement[]
+  variables: { path: string; isSplatted: boolean }[]
+  hasStopParsing: boolean
+  originalCommand: string
+  typeLiterals?: string[]
+  hasUsingStatements?: boolean
+  hasScriptRequirements?: boolean
+}
+
+// This is the canonical copy of the parse script. There is no separate .ps1 file.
+/**
+ * The core parse logic.
+ * The command is passed via Base64-encoded $EncodedCommand variable
+ * to avoid here-string injection attacks.
+ *
+ * SECURITY — top-level ParamBlock: ScriptBlockAst.ParamBlock is a SIBLING of
+ * the named blocks (Begin/Process/End/Clean/DynamicParam), not nested inside
+ * them, so Process-BlockStatements never reaches it. Commands inside param()
+ * default-value expressions and attribute arguments (e.g. [ValidateScript({...})])
+ * were invisible to every downstream check. PoC:
+ *   param($x = (Remove-Item /)); Get-Process   → only Get-Process surfaced
+ *   param([ValidateScript({rm /;$true})]$x='t') → rm invisible, runs on bind
+ * Function-level param() IS covered: FindAll on the FunctionDefinitionAst
+ * statement recurses into its descendants. The gap was only the script-level
+ * ParamBlock. ParamBlockAst has .Parameters (not .Statements) so we FindAll
+ * on it directly rather than reusing Process-BlockStatements. We only emit a
+ * statement if there is something to report, to avoid noise for plain
+ * param($x) declarations. (Kept compact in-script to preserve argv budget.)
+ */
+/**
+ * PS1 parse script. Comments live here (not inline) — every char inside the
+ * backticks eats into WINDOWS_MAX_COMMAND_LENGTH (argv budget).
+ *
+ * Structure:
+ * - Get-RawCommandElements: extract CommandAst element data (type, text, value,
+ *   expressionType, children for colon-bound param .Argument)
+ * - Get-RawRedirections: extract FileRedirectionAst operator+target
+ * - Get-SecurityPatterns: FindAll for security flags (hasSubExpressions via
+ *   Sub/Array/ParenExpressionAst, hasScriptBlocks, etc.)
+ * - Type literals: emit TypeExpressionAst names for CLM allowlist check
+ * - --% token: PS7 MinusMinus, PS5.1 Generic kind
+ * - CommandExpressionAst.Redirections: inherits from CommandBaseAst —
+ *   `1 > /tmp/x` statement has FileRedirectionAst that element-iteration misses
+ * - Nested commands: FindAll for ALL statement types (if/for/foreach/while/
+ *   switch/try/function/assignment/PipelineChainAst) — skip direct pipeline
+ *   elements already in the loop
+ */
+// exported for testing
+export const PARSE_SCRIPT_BODY = `
+if (-not $EncodedCommand) {
+    Write-Output '{"valid":false,"errors":[{"message":"No command provided","errorId":"NoInput"}],"statements":[],"variables":[],"hasStopParsing":false,"originalCommand":""}'
+    exit 0
+}
+
+$Command = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($EncodedCommand))
+
+$tokens = $null
+$parseErrors = $null
+$ast = [System.Management.Automation.Language.Parser]::ParseInput(
+    $Command,
+    [ref]$tokens,
+    [ref]$parseErrors
+)
+
+$allVariables = [System.Collections.ArrayList]::new()
+
+function Get-RawCommandElements {
+    param([System.Management.Automation.Language.CommandAst]$CmdAst)
+    $elems = [System.Collections.ArrayList]::new()
+    foreach ($ce in $CmdAst.CommandElements) {
+        $ceData = @{ type = $ce.GetType().Name; text = $ce.Extent.Text }
+        if ($ce.PSObject.Properties['Value'] -and $null -ne $ce.Value -and $ce.Value -is [string]) {
+            $ceData.value = $ce.Value
+        }
+        if ($ce -is [System.Management.Automation.Language.CommandExpressionAst]) {
+            $ceData.expressionType = $ce.Expression.GetType().Name
+        }
+        $a=$ce.Argument;if($a){$ceData.children=@(@{type=$a.GetType().Name;text=$a.Extent.Text})}
+        [void]$elems.Add($ceData)
+    }
+    return $elems
+}
+
+function Get-RawRedirections {
+    param($Redirections)
+    $result = [System.Collections.ArrayList]::new()
+    foreach ($redir in $Redirections) {
+        $redirData = @{ type = $redir.GetType().Name }
+        if ($redir -is [System.Management.Automation.Language.FileRedirectionAst]) {
+            $redirData.append = [bool]$redir.Append
+            $redirData.fromStream = $redir.FromStream.ToString()
+            $redirData.locationText = $redir.Location.Extent.Text
+        }
+        [void]$result.Add($redirData)
+    }
+    return $result
+}
+
+function Get-SecurityPatterns($A) {
+    $p = @{}
+    foreach ($n in $A.FindAll({ param($x)
+        $x -is [System.Management.Automation.Language.MemberExpressionAst] -or
+        $x -is [System.Management.Automation.Language.SubExpressionAst] -or
+        $x -is [System.Management.Automation.Language.ArrayExpressionAst] -or
+        $x -is [System.Management.Automation.Language.ExpandableStringExpressionAst] -or
+        $x -is [System.Management.Automation.Language.ScriptBlockExpressionAst] -or
+        $x -is [System.Management.Automation.Language.ParenExpressionAst]
+    }, $true)) { switch ($n.GetType().Name) {
+        'InvokeMemberExpressionAst' { $p.hasMemberInvocations = $true }
+        'MemberExpressionAst' { $p.hasMemberInvocations = $true }
+        'SubExpressionAst' { $p.hasSubExpressions = $true }
+        'ArrayExpressionAst' { $p.hasSubExpressions = $true }
+        'ParenExpressionAst' { $p.hasSubExpressions = $true }
+        'ExpandableStringExpressionAst' { $p.hasExpandableStrings = $true }
+        'ScriptBlockExpressionAst' { $p.hasScriptBlocks = $true }
+    }}
+    if ($p.Count -gt 0) { return $p }
+    return $null
+}
+
+$varExprs = $ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.VariableExpressionAst] }, $true)
+foreach ($v in $varExprs) {
+    [void]$allVariables.Add(@{
+        path = $v.VariablePath.ToString()
+        isSplatted = [bool]$v.Splatted
+    })
+}
+
+$typeLiterals = [System.Collections.ArrayList]::new()
+foreach ($t in $ast.FindAll({ param($n)
+    $n -is [System.Management.Automation.Language.TypeExpressionAst] -or
+    $n -is [System.Management.Automation.Language.TypeConstraintAst]
+}, $true)) { [void]$typeLiterals.Add($t.TypeName.FullName) }
+
+$hasStopParsing = $false
+$tk = [System.Management.Automation.Language.TokenKind]
+foreach ($tok in $tokens) {
+    if ($tok.Kind -eq $tk::MinusMinus) { $hasStopParsing = $true; break }
+    if ($tok.Kind -eq $tk::Generic -and ($tok.Text -replace '[\u2013\u2014\u2015]','-') -eq '--%') {
+        $hasStopParsing = $true; break
+    }
+}
+
+$statements = [System.Collections.ArrayList]::new()
+
+function Process-BlockStatements {
+    param($Block)
+    if (-not $Block) { return }
+
+    foreach ($stmt in $Block.Statements) {
+        $statement = @{
+            type = $stmt.GetType().Name
+            text = $stmt.Extent.Text
+        }
+
+        if ($stmt -is [System.Management.Automation.Language.PipelineAst]) {
+            $elements = [System.Collections.ArrayList]::new()
+            foreach ($element in $stmt.PipelineElements) {
+                $elemData = @{
+                    type = $element.GetType().Name
+                    text = $element.Extent.Text
+                }
+
+                if ($element -is [System.Management.Automation.Language.CommandAst]) {
+                    $elemData.commandElements = @(Get-RawCommandElements -CmdAst $element)
+                    $elemData.redirections = @(Get-RawRedirections -Redirections $element.Redirections)
+                } elseif ($element -is [System.Management.Automation.Language.CommandExpressionAst]) {
+                    $elemData.expressionType = $element.Expression.GetType().Name
+                    $elemData.redirections = @(Get-RawRedirections -Redirections $element.Redirections)
+                }
+
+                [void]$elements.Add($elemData)
+            }
+            $statement.elements = @($elements)
+
+            $allNestedCmds = $stmt.FindAll(
+                { param($node) $node -is [System.Management.Automation.Language.CommandAst] },
+                $true
+            )
+            $nestedCmds = [System.Collections.ArrayList]::new()
+            foreach ($cmd in $allNestedCmds) {
+                if ($cmd.Parent -eq $stmt) { continue }
+                $nested = @{
+                    type = $cmd.GetType().Name
+                    text = $cmd.Extent.Text
+                    commandElements = @(Get-RawCommandElements -CmdAst $cmd)
+                    redirections = @(Get-RawRedirections -Redirections $cmd.Redirections)
+                }
+                [void]$nestedCmds.Add($nested)
+            }
+            if ($nestedCmds.Count -gt 0) {
+                $statement.nestedCommands = @($nestedCmds)
+            }
+            $r = $stmt.FindAll({param($n) $n -is [System.Management.Automation.Language.FileRedirectionAst]}, $true)
+            if ($r.Count -gt 0) {
+                $rr = @(Get-RawRedirections -Redirections $r)
+                $statement.redirections = if ($statement.redirections) { @($statement.redirections) + $rr } else { $rr }
+            }
+        } else {
+            $nestedCmdAsts = $stmt.FindAll(
+                { param($node) $node -is [System.Management.Automation.Language.CommandAst] },
+                $true
+            )
+            $nested = [System.Collections.ArrayList]::new()
+            foreach ($cmd in $nestedCmdAsts) {
+                [void]$nested.Add(@{
+                    type = 'CommandAst'
+                    text = $cmd.Extent.Text
+                    commandElements = @(Get-RawCommandElements -CmdAst $cmd)
+                    redirections = @(Get-RawRedirections -Redirections $cmd.Redirections)
+                })
+            }
+            if ($nested.Count -gt 0) {
+                $statement.nestedCommands = @($nested)
+            }
+            $r = $stmt.FindAll({param($n) $n -is [System.Management.Automation.Language.FileRedirectionAst]}, $true)
+            if ($r.Count -gt 0) { $statement.redirections = @(Get-RawRedirections -Redirections $r) }
+        }
+
+        $sp = Get-SecurityPatterns $stmt
+        if ($sp) { $statement.securityPatterns = $sp }
+
+        [void]$statements.Add($statement)
+    }
+
+    if ($Block.Traps) {
+        foreach ($trap in $Block.Traps) {
+            $statement = @{
+                type = 'TrapStatementAst'
+                text = $trap.Extent.Text
+            }
+            $nestedCmdAsts = $trap.FindAll(
+                { param($node) $node -is [System.Management.Automation.Language.CommandAst] },
+                $true
+            )
+            $nestedCmds = [System.Collections.ArrayList]::new()
+            foreach ($cmd in $nestedCmdAsts) {
+                $nested = @{
+                    type = $cmd.GetType().Name
+                    text = $cmd.Extent.Text
+                    commandElements = @(Get-RawCommandElements -CmdAst $cmd)
+                    redirections = @(Get-RawRedirections -Redirections $cmd.Redirections)
+                }
+                [void]$nestedCmds.Add($nested)
+            }
+            if ($nestedCmds.Count -gt 0) {
+                $statement.nestedCommands = @($nestedCmds)
+            }
+            $r = $trap.FindAll({param($n) $n -is [System.Management.Automation.Language.FileRedirectionAst]}, $true)
+            if ($r.Count -gt 0) { $statement.redirections = @(Get-RawRedirections -Redirections $r) }
+            $sp = Get-SecurityPatterns $trap
+            if ($sp) { $statement.securityPatterns = $sp }
+            [void]$statements.Add($statement)
+        }
+    }
+}
+
+Process-BlockStatements -Block $ast.BeginBlock
+Process-BlockStatements -Block $ast.ProcessBlock
+Process-BlockStatements -Block $ast.EndBlock
+Process-BlockStatements -Block $ast.CleanBlock
+Process-BlockStatements -Block $ast.DynamicParamBlock
+
+if ($ast.ParamBlock) {
+  $pb = $ast.ParamBlock
+  $pn = [System.Collections.ArrayList]::new()
+  foreach ($c in $pb.FindAll({param($n) $n -is [System.Management.Automation.Language.CommandAst]}, $true)) {
+    [void]$pn.Add(@{type='CommandAst';text=$c.Extent.Text;commandElements=@(Get-RawCommandElements -CmdAst $c);redirections=@(Get-RawRedirections -Redirections $c.Redirections)})
+  }
+  $pr = $pb.FindAll({param($n) $n -is [System.Management.Automation.Language.FileRedirectionAst]}, $true)
+  $ps = Get-SecurityPatterns $pb
+  if ($pn.Count -gt 0 -or $pr.Count -gt 0 -or $ps) {
+    $st = @{type='ParamBlockAst';text=$pb.Extent.Text}
+    if ($pn.Count -gt 0) { $st.nestedCommands = @($pn) }
+    if ($pr.Count -gt 0) { $st.redirections = @(Get-RawRedirections -Redirections $pr) }
+    if ($ps) { $st.securityPatterns = $ps }
+    [void]$statements.Add($st)
+  }
+}
+
+$hasUsingStatements = $ast.UsingStatements -and $ast.UsingStatements.Count -gt 0
+$hasScriptRequirements = $ast.ScriptRequirements -ne $null
+
+$output = @{
+    valid = ($parseErrors.Count -eq 0)
+    errors = @($parseErrors | ForEach-Object {
+        @{
+            message = $_.Message
+            errorId = $_.ErrorId
+        }
+    })
+    statements = @($statements)
+    variables = @($allVariables)
+    hasStopParsing = $hasStopParsing
+    originalCommand = $Command
+    typeLiterals = @($typeLiterals)
+    hasUsingStatements = [bool]$hasUsingStatements
+    hasScriptRequirements = [bool]$hasScriptRequirements
+}
+
+$output | ConvertTo-Json -Depth 10 -Compress
+`
+
+// ---------------------------------------------------------------------------
+// Windows CreateProcess has a 32,767 char command-line limit. The encoding
+// chain is:
+//   command (N UTF-8 bytes) → Base64 (~4N/3 chars) → $EncodedCommand = '...'\n
+//   → full script (wrapper + PARSE_SCRIPT_BODY) → UTF-16LE (2× bytes)
+//   → Base64 (4/3× chars) → -EncodedCommand argv
+// Final cmdline ≈ argv_overhead + (wrapper + 4N/3 + body) × 8/3
+//
+// Solving for N (UTF-8 bytes) with a 32,767 cap:
+//   script_budget   = (32767 - argv_overhead) × 3/8
+//   cmd_b64_budget  = script_budget - PARSE_SCRIPT_BODY.length - wrapper
+//   N               = cmd_b64_budget × 3/4 - safety_margin
+//
+// SECURITY: N is a UTF-8 BYTE budget, not a UTF-16 code-unit budget. The
+// length gate MUST measure Buffer.byteLength(command, 'utf8'), not
+// command.length. A BMP character in U+0800–U+FFFF (CJK ideographs, most
+// non-Latin scripts) is 1 UTF-16 code unit but 3 UTF-8 bytes. With
+// PARSE_SCRIPT_BODY ≈ 10.6K, N ≈ 1,092 bytes. Comparing against .length
+// permits a 1,092-code-unit pure-CJK command (≈3,276 UTF-8 bytes) → inner
+// base64 ≈ 4,368 chars → final argv ≈ 40K chars, overflowing 32,767 by
+// ~7.4K. CreateProcess fails → valid:false → parse-fail degradation (deny
+// rules silently downgrade to ask). Finding #36.
+//
+// COMPUTED from PARSE_SCRIPT_BODY.length so it cannot drift. The prior
+// hardcoded value (4,500) was derived from a ~6K body estimate; the body is
+// actually ~11K chars, so the real ceiling was ~1,850. Commands in the
+// 1,850–4,500 range passed this gate but then failed CreateProcess on
+// Windows, returning valid=false and skipping all AST-based security checks.
+//
+// Unix argv limits are typically 2MB+ (ARG_MAX) with ~128KB per-argument
+// limit (MAX_ARG_STRLEN on Linux; macOS has no per-arg limit below ARG_MAX).
+// At MAX=4,500 the -EncodedCommand argument is ~45KB — well under either.
+// Applying the Windows-derived limit on Unix would REGRESS: commands in the
+// ~1K–4.5K range previously parsed successfully and reached the sub-command
+// deny loop at powershellPermissions.ts; rejecting them pre-spawn degrades
+// user-configured deny rules from deny→ask for compound commands with a
+// denied cmdlet buried mid-script. So the Windows limit is platform-gated.
+//
+// If the Windows limit becomes too restrictive, switch to -File with a temp
+// file for large inputs.
+// ---------------------------------------------------------------------------
+const WINDOWS_ARGV_CAP = 32_767
+// pwsh path + " -NoProfile -NonInteractive -NoLogo -EncodedCommand " +
+// argv quoting. A long Windows pwsh path (C:\Program Files\PowerShell\7\
+// pwsh.exe) + flags is ~95 chars; 200 leaves headroom for unusual installs.
+const FIXED_ARGV_OVERHEAD = 200
+// "$EncodedCommand = '" + "'\n" wrapper around the user command's base64
+const ENCODED_CMD_WRAPPER = `$EncodedCommand = ''\n`.length
+// Margin for base64 padding rounding (≤4 chars at each of 2 levels) and minor
+// estimation drift. Multibyte expansion is NOT absorbed here — the gate
+// measures actual UTF-8 bytes (Buffer.byteLength), not code units.
+const SAFETY_MARGIN = 100
+const SCRIPT_CHARS_BUDGET = ((WINDOWS_ARGV_CAP - FIXED_ARGV_OVERHEAD) * 3) / 8
+const CMD_B64_BUDGET =
+  SCRIPT_CHARS_BUDGET - PARSE_SCRIPT_BODY.length - ENCODED_CMD_WRAPPER
+// Exported for drift-guard tests (the drift-prone value is the Windows one).
+// Unit: UTF-8 BYTES. Compare against Buffer.byteLength, not .length.
+export const WINDOWS_MAX_COMMAND_LENGTH = Math.max(
+  0,
+  Math.floor((CMD_B64_BUDGET * 3) / 4) - SAFETY_MARGIN,
+)
+// Pre-existing value, known to work on Unix. See comment above re: why the
+// Windows derivation must NOT be applied here. Unit: UTF-8 BYTES — for ASCII
+// commands (the common case) bytes==chars so no regression; for multibyte
+// commands this is slightly tighter but still far below Unix ARG_MAX (~128KB
+// per-arg), so the argv spawn cannot overflow.
+const UNIX_MAX_COMMAND_LENGTH = 4_500
+// Unit: UTF-8 BYTES (see SECURITY note above).
+export const MAX_COMMAND_LENGTH =
+  process.platform === 'win32'
+    ? WINDOWS_MAX_COMMAND_LENGTH
+    : UNIX_MAX_COMMAND_LENGTH
+
+const INVALID_RESULT_BASE: Omit<
+  ParsedPowerShellCommand,
+  'errors' | 'originalCommand'
+> = {
+  valid: false,
+  statements: [],
+  variables: [],
+  hasStopParsing: false,
+}
+
+function makeInvalidResult(
+  command: string,
+  message: string,
+  errorId: string,
+): ParsedPowerShellCommand {
+  return {
+    ...INVALID_RESULT_BASE,
+    errors: [{ message, errorId }],
+    originalCommand: command,
+  }
+}
+
+/**
+ * Base64-encode a string as UTF-16LE, which is the encoding required by
+ * PowerShell's -EncodedCommand parameter.
+ */
+function toUtf16LeBase64(text: string): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(text, 'utf16le').toString('base64')
+  }
+  // Fallback for non-Node environments
+  const bytes: number[] = []
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i)
+    bytes.push(code & 0xff, (code >> 8) & 0xff)
+  }
+  return btoa(bytes.map(b => String.fromCharCode(b)).join(''))
+}
+
+/**
+ * Build the full PowerShell script that parses a command.
+ * The user command is Base64-encoded (UTF-8) and embedded in a variable
+ * to prevent injection attacks.
+ */
+function buildParseScript(command: string): string {
+  const encoded =
+    typeof Buffer !== 'undefined'
+      ? Buffer.from(command, 'utf8').toString('base64')
+      : btoa(
+          new TextEncoder()
+            .encode(command)
+            .reduce((s, b) => s + String.fromCharCode(b), ''),
+        )
+  return `$EncodedCommand = '${encoded}'\n${PARSE_SCRIPT_BODY}`
+}
+
+/**
+ * Ensure a value is an array. PowerShell 5.1's ConvertTo-Json may unwrap
+ * single-element arrays into plain objects.
+ */
+function ensureArray<T>(value: T | T[] | undefined | null): T[] {
+  if (value === undefined || value === null) {
+    return []
+  }
+  return Array.isArray(value) ? value : [value]
+}
+
+/** Map raw .NET AST type name to our StatementType union */
+// exported for testing
+export function mapStatementType(rawType: string): StatementType {
+  switch (rawType) {
+    case 'PipelineAst':
+      return 'PipelineAst'
+    case 'PipelineChainAst':
+      return 'PipelineChainAst'
+    case 'AssignmentStatementAst':
+      return 'AssignmentStatementAst'
+    case 'IfStatementAst':
+      return 'IfStatementAst'
+    case 'ForStatementAst':
+      return 'ForStatementAst'
+    case 'ForEachStatementAst':
+      return 'ForEachStatementAst'
+    case 'WhileStatementAst':
+      return 'WhileStatementAst'
+    case 'DoWhileStatementAst':
+      return 'DoWhileStatementAst'
+    case 'DoUntilStatementAst':
+      return 'DoUntilStatementAst'
+    case 'SwitchStatementAst':
+      return 'SwitchStatementAst'
+    case 'TryStatementAst':
+      return 'TryStatementAst'
+    case 'TrapStatementAst':
+      return 'TrapStatementAst'
+    case 'FunctionDefinitionAst':
+      return 'FunctionDefinitionAst'
+    case 'DataStatementAst':
+      return 'DataStatementAst'
+    default:
+      return 'UnknownStatementAst'
+  }
+}
+
+/** Map raw .NET AST type name to our CommandElementType union */
+// exported for testing
+export function mapElementType(
+  rawType: string,
+  expressionType?: string,
+): CommandElementType {
+  switch (rawType) {
+    case 'ScriptBlockExpressionAst':
+      return 'ScriptBlock'
+    case 'SubExpressionAst':
+    case 'ArrayExpressionAst':
+      // SECURITY: ArrayExpressionAst (@()) is a sibling of SubExpressionAst,
+      // not a subclass. Both evaluate arbitrary pipelines with side effects:
+      // Get-ChildItem @(Remove-Item ./data) runs Remove-Item inside @().
+      // Map both to SubExpression so hasSubExpressions fires and isReadOnlyCommand
+      // rejects (it doesn't check nestedCommands, only pipeline.commands[]).
+      return 'SubExpression'
+    case 'ExpandableStringExpressionAst':
+      return 'ExpandableString'
+    case 'InvokeMemberExpressionAst':
+    case 'MemberExpressionAst':
+      return 'MemberInvocation'
+    case 'VariableExpressionAst':
+      return 'Variable'
+    case 'StringConstantExpressionAst':
+    case 'ConstantExpressionAst':
+      // ConstantExpressionAst covers numeric literals (5, 3.14). For
+      // permission purposes a numeric literal is as safe as a string
+      // literal — it's an inert value, not code. Without this mapping,
+      // `-Seconds:5` produced children[0].type='Other' and consumers
+      // checking `children.some(c => c.type !== 'StringConstant')` would
+      // false-positive ask on harmless numeric args.
+      return 'StringConstant'
+    case 'CommandParameterAst':
+      return 'Parameter'
+    case 'ParenExpressionAst':
+      return 'SubExpression'
+    case 'CommandExpressionAst':
+      // Delegate to the wrapped expression type so we catch SubExpressionAst,
+      // ExpandableStringExpressionAst, ScriptBlockExpressionAst, etc.
+      // without maintaining a manual list. Falls through to 'Other' if the
+      // inner type is unrecognised.
+      if (expressionType) {
+        return mapElementType(expressionType)
+      }
+      return 'Other'
+    default:
+      return 'Other'
+  }
+}
+
+/** Classify command name as cmdlet, application, or unknown */
+// exported for testing
+export function classifyCommandName(
+  name: string,
+): 'cmdlet' | 'application' | 'unknown' {
+  if (/^[A-Za-z]+-[A-Za-z][A-Za-z0-9_]*$/.test(name)) {
+    return 'cmdlet'
+  }
+  if (/[.\\/]/.test(name)) {
+    return 'application'
+  }
+  return 'unknown'
+}
+
+/** Strip module prefix from command name (e.g. "Microsoft.PowerShell.Utility\\Invoke-Expression" -> "Invoke-Expression") */
+// exported for testing
+export function stripModulePrefix(name: string): string {
+  const idx = name.lastIndexOf('\\')
+  if (idx < 0) return name
+  // Don't strip file paths: drive letters (C:\...), UNC paths (\\server\...), or relative paths (.\, ..\)
+  if (
+    /^[A-Za-z]:/.test(name) ||
+    name.startsWith('\\\\') ||
+    name.startsWith('.\\') ||
+    name.startsWith('..\\')
+  )
+    return name
+  return name.substring(idx + 1)
+}
+
+/** Transform a raw CommandAst pipeline element into ParsedCommandElement */
+// exported for testing
+export function transformCommandAst(
+  raw: RawPipelineElement,
+): ParsedCommandElement {
+  const cmdElements = ensureArray(raw.commandElements)
+  let name = ''
+  const args: string[] = []
+  const elementTypes: CommandElementType[] = []
+  const children: (CommandElementChild[] | undefined)[] = []
+  let hasChildren = false
+
+  // SECURITY: nameType MUST be computed from the raw name (before
+  // stripModulePrefix). classifyCommandName('scripts\\Get-Process') returns
+  // 'application' (contains \\) — the correct answer, since PowerShell resolves
+  // this as a file path. After stripping it becomes 'Get-Process' which
+  // classifies as 'cmdlet' — wrong, and allowlist checks would trust it.
+  // Auto-allow paths gate on nameType !== 'application' to catch this.
+  // name (stripped) is still used for deny-rule matching symmetry, which is
+  // fail-safe: deny rules over-match (Module\\Remove-Item still hits a
+  // Remove-Item deny), allow rules are separately gated by nameType.
+  let nameType: 'cmdlet' | 'application' | 'unknown' = 'unknown'
+  if (cmdElements.length > 0) {
+    const first = cmdElements[0]!
+    // SECURITY: only trust .value for string-literal element types with a
+    // string-typed value. Numeric ConstantExpressionAst (e.g. `& 1`) emits an
+    // integer .value that crashes stripModulePrefix() → parser falls through
+    // to passthrough. For non-string-literal or non-string .value, use .text.
+    const isFirstStringLiteral =
+      first.type === 'StringConstantExpressionAst' ||
+      first.type === 'ExpandableStringExpressionAst'
+    const rawNameUnstripped =
+      isFirstStringLiteral && typeof first.value === 'string'
+        ? first.value
+        : first.text
+    // SECURITY: strip surrounding quotes from the command name. When .value is
+    // unavailable (no StaticType on the raw node), .text preserves quotes —
+    // `& 'Invoke-Expression' 'x'` yields "'Invoke-Expression'". Stripping here
+    // at the source means every downstream reader of element.name (deny-rule
+    // matching, GIT_SAFETY_WRITE_CMDLETS lookup, resolveToCanonical, etc.)
+    // sees the bare cmdlet name. No-op when .value already stripped.
+    const rawName = rawNameUnstripped.replace(/^['"]|['"]$/g, '')
+    // SECURITY: PowerShell built-in cmdlet names are ASCII-only. Non-ASCII
+    // characters in cmdlet position are inherently suspicious — .NET
+    // OrdinalIgnoreCase folds U+017F (ſ) → S and U+0131 (ı) → I per
+    // UnicodeData.txt SimpleUppercaseMapping, so PowerShell resolves
+    // `ſtart-proceſſ` → Start-Process at runtime. JS .toLowerCase() does NOT
+    // fold these (ſ is already lowercase), so every downstream name
+    // comparison (NEVER_SUGGEST, deny-rule strEquals, resolveToCanonical,
+    // security validators) misses. Force 'application' to gate auto-allow
+    // (blocks at the nameType !== 'application' checks). Finding #31.
+    // Verified on Windows (pwsh 7.x, 2026-03): ſtart-proceſſ does NOT resolve.
+    // Retained as defense-in-depth against future .NET/PS behavior changes
+    // or module-provided command resolution hooks.
+    if (/[\u0080-\uFFFF]/.test(rawName)) {
+      nameType = 'application'
+    } else {
+      nameType = classifyCommandName(rawName)
+    }
+    name = stripModulePrefix(rawName)
+    elementTypes.push(mapElementType(first.type, first.expressionType))
+
+    for (let i = 1; i < cmdElements.length; i++) {
+      const ce = cmdElements[i]!
+      // Use resolved .value for string constants (strips quotes, resolves
+      // backtick escapes like `n -> newline) but keep raw .text for parameters
+      // (where .value loses the dash prefix, e.g. '-Path' -> 'Path'),
+      // variables, and other non-string types.
+      const isStringLiteral =
+        ce.type === 'StringConstantExpressionAst' ||
+        ce.type === 'ExpandableStringExpressionAst'
+      args.push(isStringLiteral && ce.value != null ? ce.value : ce.text)
+      elementTypes.push(mapElementType(ce.type, ce.expressionType))
+      // Map raw children (CommandParameterAst.Argument) through
+      // mapElementType so consumers see 'Variable', 'StringConstant', etc.
+      const rawChildren = ensureArray(ce.children)
+      if (rawChildren.length > 0) {
+        hasChildren = true
+        children.push(
+          rawChildren.map(c => ({
+            type: mapElementType(c.type),
+            text: c.text,
+          })),
+        )
+      } else {
+        children.push(undefined)
+      }
+    }
+  }
+
+  const result: ParsedCommandElement = {
+    name,
+    nameType,
+    elementType: 'CommandAst',
+    args,
+    text: raw.text,
+    elementTypes,
+    ...(hasChildren ? { children } : {}),
+  }
+
+  // Preserve redirections from nested commands (e.g., in && / || chains)
+  const rawRedirs = ensureArray(raw.redirections)
+  if (rawRedirs.length > 0) {
+    result.redirections = rawRedirs.map(transformRedirection)
+  }
+
+  return result
+}
+
+/** Transform a non-CommandAst pipeline element into ParsedCommandElement */
+// exported for testing
+export function transformExpressionElement(
+  raw: RawPipelineElement,
+): ParsedCommandElement {
+  const elementType: PipelineElementType =
+    raw.type === 'ParenExpressionAst'
+      ? 'ParenExpressionAst'
+      : 'CommandExpressionAst'
+  const elementTypes: CommandElementType[] = [
+    mapElementType(raw.type, raw.expressionType),
+  ]
+
+  return {
+    name: raw.text,
+    nameType: 'unknown',
+    elementType,
+    args: [],
+    text: raw.text,
+    elementTypes,
+  }
+}
+
+/** Map raw redirection to ParsedRedirection */
+// exported for testing
+export function transformRedirection(raw: RawRedirection): ParsedRedirection {
+  if (raw.type === 'MergingRedirectionAst') {
+    return { operator: '2>&1', target: '', isMerging: true }
+  }
+
+  const append = raw.append ?? false
+  const fromStream = raw.fromStream ?? 'Output'
+
+  let operator: ParsedRedirection['operator']
+  if (append) {
+    switch (fromStream) {
+      case 'Error':
+        operator = '2>>'
+        break
+      case 'All':
+        operator = '*>>'
+        break
+      default:
+        operator = '>>'
+        break
+    }
+  } else {
+    switch (fromStream) {
+      case 'Error':
+        operator = '2>'
+        break
+      case 'All':
+        operator = '*>'
+        break
+      default:
+        operator = '>'
+        break
+    }
+  }
+
+  return { operator, target: raw.locationText ?? '', isMerging: false }
+}
+
+/** Transform a raw statement into ParsedStatement */
+// exported for testing
+export function transformStatement(raw: RawStatement): ParsedStatement {
+  const statementType = mapStatementType(raw.type)
+  const commands: ParsedCommandElement[] = []
+  const redirections: ParsedRedirection[] = []
+
+  if (raw.elements) {
+    // PipelineAst: walk pipeline elements
+    for (const elem of ensureArray(raw.elements)) {
+      if (elem.type === 'CommandAst') {
+        commands.push(transformCommandAst(elem))
+        for (const redir of ensureArray(elem.redirections)) {
+          redirections.push(transformRedirection(redir))
+        }
+      } else {
+        commands.push(transformExpressionElement(elem))
+        // SECURITY: CommandExpressionAst also carries .Redirections (inherited
+        // from CommandBaseAst). `1 > /tmp/evil.txt` is a CommandExpressionAst
+        // with a FileRedirectionAst. Must extract here or getFileRedirections()
+        // misses it and compound commands like `Get-ChildItem; 1 > /tmp/x`
+        // auto-allow at step 5 (only Get-ChildItem is checked).
+        for (const redir of ensureArray(elem.redirections)) {
+          redirections.push(transformRedirection(redir))
+        }
+      }
+    }
+    // SECURITY: The PS1 PipelineAst branch does a deep FindAll for
+    // FileRedirectionAst to catch redirections hidden inside:
+    //  - colon-bound ParenExpressionAst args: -Name:('payload' > file)
+    //  - hashtable value statements: @{k='payload' > ~/.bashrc}
+    // Both are invisible at the element level — the redirection's parent
+    // is a child of CommandParameterAst / CommandExpressionAst, not a
+    // separate pipeline element. Merge into statement-level redirections.
+    //
+    // The FindAll ALSO re-discovers direct-element redirections already
+    // captured in the per-element loop above. Dedupe by (operator, target)
+    // so tests and consumers see the real count.
+    const seen = new Set(redirections.map(r => `${r.operator}\0${r.target}`))
+    for (const redir of ensureArray(raw.redirections)) {
+      const r = transformRedirection(redir)
+      const key = `${r.operator}\0${r.target}`
+      if (!seen.has(key)) {
+        seen.add(key)
+        redirections.push(r)
+      }
+    }
+  } else {
+    // Non-pipeline statement: add synthetic command entry with full text
+    commands.push({
+      name: raw.text,
+      nameType: 'unknown',
+      elementType: 'CommandExpressionAst',
+      args: [],
+      text: raw.text,
+    })
+    // SECURITY: The PS1 else-branch does a direct recursive FindAll on
+    // FileRedirectionAst to catch expression redirections inside control flow
+    // (if/for/foreach/while/switch/try/trap/&& and ||). The CommandAst FindAll
+    // above CANNOT see these: in if ($x) { 1 > /tmp/evil }, the literal 1 with
+    // its attached redirection is a CommandExpressionAst — a SIBLING of
+    // CommandAst in the type hierarchy, not a subclass. So nestedCommands never
+    // contains it, and without this hoist the redirection is invisible to
+    // getFileRedirections → step 4.6 misses it → compound commands like
+    // `Get-Process && 1 > /tmp/evil` auto-allow at step 5 (only Get-Process
+    // is checked, allowlisted).
+    //
+    // Finding FileRedirectionAst DIRECTLY (rather than finding CommandExpressionAst
+    // and extracting .Redirections) is both simpler and more robust: it catches
+    // redirections on any node type, including ones we don't know about yet.
+    //
+    // Double-counts redirections already on nested CommandAst commands (those are
+    // extracted at line ~395 into nestedCommands[i].redirections AND found again
+    // here). Harmless: step 4.6 only checks fileRedirections.length > 0, not
+    // the exact count. No code does arithmetic on redirection counts.
+    //
+    // PS1 SIZE NOTE: The full rationale lives here (TS), not in the PS1 script,
+    // because PS1 comments bloat the -EncodedCommand payload and push the
+    // Windows CreateProcess 32K limit. Keep PS1 comments terse; point them here.
+    for (const redir of ensureArray(raw.redirections)) {
+      redirections.push(transformRedirection(redir))
+    }
+  }
+
+  let nestedCommands: ParsedCommandElement[] | undefined
+  const rawNested = ensureArray(raw.nestedCommands)
+  if (rawNested.length > 0) {
+    nestedCommands = rawNested.map(transformCommandAst)
+  }
+
+  const result: ParsedStatement = {
+    statementType,
+    commands,
+    redirections,
+    text: raw.text,
+    nestedCommands,
+  }
+
+  if (raw.securityPatterns) {
+    result.securityPatterns = raw.securityPatterns
+  }
+
+  return result
+}
+
+/** Transform the complete raw PS output into ParsedPowerShellCommand */
+function transformRawOutput(raw: RawParsedOutput): ParsedPowerShellCommand {
+  const result: ParsedPowerShellCommand = {
+    valid: raw.valid,
+    errors: ensureArray(raw.errors),
+    statements: ensureArray(raw.statements).map(transformStatement),
+    variables: ensureArray(raw.variables),
+    hasStopParsing: raw.hasStopParsing,
+    originalCommand: raw.originalCommand,
+  }
+  const tl = ensureArray(raw.typeLiterals)
+  if (tl.length > 0) {
+    result.typeLiterals = tl
+  }
+  if (raw.hasUsingStatements) {
+    result.hasUsingStatements = true
+  }
+  if (raw.hasScriptRequirements) {
+    result.hasScriptRequirements = true
+  }
+  return result
+}
+
+/**
+ * Parse a PowerShell command using the native AST parser.
+ * Spawns pwsh to parse the command and returns structured results.
+ * Results are memoized by command string.
+ *
+ * @param command - The PowerShell command to parse
+ * @returns Parsed command structure, or a result with valid=false on failure
+ */
+async function parsePowerShellCommandImpl(
+  command: string,
+): Promise<ParsedPowerShellCommand> {
+  // SECURITY: MAX_COMMAND_LENGTH is a UTF-8 BYTE budget (see derivation at the
+  // constant definition). command.length counts UTF-16 code units; a CJK
+  // character is 1 code unit but 3 UTF-8 bytes, so .length under-reports by
+  // up to 3× and allows argv overflow on Windows → CreateProcess fails →
+  // valid:false → deny rules degrade to ask. Finding #36.
+  const commandBytes = Buffer.byteLength(command, 'utf8')
+  if (commandBytes > MAX_COMMAND_LENGTH) {
+    logForDebugging(
+      `PowerShell parser: command too long (${commandBytes} bytes, max ${MAX_COMMAND_LENGTH})`,
+    )
+    return makeInvalidResult(
+      command,
+      `Command too long for parsing (${commandBytes} bytes). Maximum supported length is ${MAX_COMMAND_LENGTH} bytes.`,
+      'CommandTooLong',
+    )
+  }
+
+  const pwshPath = await getCachedPowerShellPath()
+  if (!pwshPath) {
+    return makeInvalidResult(
+      command,
+      'PowerShell is not available',
+      'NoPowerShell',
+    )
+  }
+
+  const script = buildParseScript(command)
+
+  // Pass the script to PowerShell via -EncodedCommand.
+  // -EncodedCommand takes a Base64-encoded UTF-16LE string and executes it,
+  // which avoids: (1) stdin interactive-mode issues where -File - produces
+  // PS prompts and ANSI escapes in stdout, (2) command-line escaping issues,
+  // (3) temp files. The script itself is large but well within OS arg limits
+  // (Windows: 32K chars, Unix: typically 2MB+).
+  const encodedScript = toUtf16LeBase64(script)
+  const args = [
+    '-NoProfile',
+    '-NonInteractive',
+    '-NoLogo',
+    '-EncodedCommand',
+    encodedScript,
+  ]
+
+  // Spawn pwsh with one retry on timeout. On loaded CI runners (Windows
+  // especially), pwsh spawn + .NET JIT + ParseInput occasionally exceeds 5s
+  // even after CAN_SPAWN_PARSE_SCRIPT() warms the JIT. execa kills the process
+  // but exitCode is undefined, which the old code reported as the misleading
+  // "pwsh exited with code 1:" with empty stderr. A single retry absorbs
+  // transient load spikes; a double timeout is reported as PwshTimeout.
+  const parseTimeoutMs = getParseTimeoutMs()
+  let stdout = ''
+  let stderr = ''
+  let code: number | null = null
+  let timedOut = false
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const result = await execa(pwshPath, args, {
+        timeout: parseTimeoutMs,
+        reject: false,
+      })
+      stdout = result.stdout
+      stderr = result.stderr
+      timedOut = result.timedOut
+      code = result.failed ? (result.exitCode ?? 1) : 0
+    } catch (e: unknown) {
+      logForDebugging(
+        `PowerShell parser: failed to spawn pwsh: ${e instanceof Error ? e.message : e}`,
+      )
+      return makeInvalidResult(
+        command,
+        `Failed to spawn PowerShell: ${e instanceof Error ? e.message : e}`,
+        'PwshSpawnError',
+      )
+    }
+    if (!timedOut) break
+    logForDebugging(
+      `PowerShell parser: pwsh timed out after ${parseTimeoutMs}ms (attempt ${attempt + 1})`,
+    )
+  }
+
+  if (timedOut) {
+    return makeInvalidResult(
+      command,
+      `pwsh timed out after ${parseTimeoutMs}ms (2 attempts)`,
+      'PwshTimeout',
+    )
+  }
+
+  if (code !== 0) {
+    logForDebugging(
+      `PowerShell parser: pwsh exited with code ${code}, stderr: ${stderr}`,
+    )
+    return makeInvalidResult(
+      command,
+      `pwsh exited with code ${code}: ${stderr}`,
+      'PwshError',
+    )
+  }
+
+  const trimmed = stdout.trim()
+  if (!trimmed) {
+    logForDebugging('PowerShell parser: empty stdout from pwsh')
+    return makeInvalidResult(
+      command,
+      'No output from PowerShell parser',
+      'EmptyOutput',
+    )
+  }
+
+  try {
+    const raw = jsonParse(trimmed) as RawParsedOutput
+    return transformRawOutput(raw)
+  } catch {
+    logForDebugging(
+      `PowerShell parser: invalid JSON output: ${trimmed.slice(0, 200)}`,
+    )
+    return makeInvalidResult(
+      command,
+      'Invalid JSON from PowerShell parser',
+      'InvalidJson',
+    )
+  }
+}
+
+// Error IDs from makeInvalidResult that represent transient process failures.
+// These should be evicted from the cache so subsequent calls can retry.
+// Deterministic failures (CommandTooLong, syntax errors from successful parses)
+// should stay cached since retrying would produce the same result.
+const TRANSIENT_ERROR_IDS = new Set([
+  'PwshSpawnError',
+  'PwshError',
+  'PwshTimeout',
+  'EmptyOutput',
+  'InvalidJson',
+])
+
+const parsePowerShellCommandCached = memoizeWithLRU(
+  (command: string) => {
+    const promise = parsePowerShellCommandImpl(command)
+    // Evict transient failures after resolution so they can be retried.
+    // The current caller still receives the cached promise for this call,
+    // ensuring concurrent callers share the same result.
+    void promise.then(result => {
+      if (
+        !result.valid &&
+        TRANSIENT_ERROR_IDS.has(result.errors[0]?.errorId ?? '')
+      ) {
+        parsePowerShellCommandCached.cache.delete(command)
+      }
+    })
+    return promise
+  },
+  (command: string) => command,
+  256,
+)
+export { parsePowerShellCommandCached as parsePowerShellCommand }
+
+// ---------------------------------------------------------------------------
+// Analysis helpers — derived from the parsed AST structure.
+// ---------------------------------------------------------------------------
+
+/**
+ * Security-relevant flags derived from the parsed AST.
+ */
+type SecurityFlags = {
+  /** Contains $(...) subexpression */
+  hasSubExpressions: boolean
+  /** Contains { ... } script block expressions */
+  hasScriptBlocks: boolean
+  /** Contains @variable splatting */
+  hasSplatting: boolean
+  /** Contains expandable strings with embedded expressions ("...$()...") */
+  hasExpandableStrings: boolean
+  /** Contains .NET method invocations ([Type]::Method or $obj.Method()) */
+  hasMemberInvocations: boolean
+  /** Contains variable assignments ($x = ...) */
+  hasAssignments: boolean
+  /** Uses stop-parsing token (--%) */
+  hasStopParsing: boolean
+}
+
+/**
+ * Common PowerShell aliases mapped to their canonical cmdlet names.
+ * Uses Object.create(null) to prevent prototype-chain pollution — attacker-controlled
+ * command names like 'constructor' or '__proto__' must return undefined, not inherited
+ * Object.prototype properties.
+ */
+export const COMMON_ALIASES: Record<string, string> = Object.assign(
+  Object.create(null) as Record<string, string>,
+  {
+    // Directory listing
+    ls: 'Get-ChildItem',
+    dir: 'Get-ChildItem',
+    gci: 'Get-ChildItem',
+    // Content
+    cat: 'Get-Content',
+    type: 'Get-Content',
+    gc: 'Get-Content',
+    // Navigation
+    cd: 'Set-Location',
+    sl: 'Set-Location',
+    chdir: 'Set-Location',
+    pushd: 'Push-Location',
+    popd: 'Pop-Location',
+    pwd: 'Get-Location',
+    gl: 'Get-Location',
+    // Items
+    gi: 'Get-Item',
+    gp: 'Get-ItemProperty',
+    ni: 'New-Item',
+    mkdir: 'New-Item',
+    // `md` is PowerShell's built-in alias for `mkdir`. resolveToCanonical is
+    // single-hop (no md→mkdir→New-Item chaining), so it needs its own entry
+    // or `md /etc/x` falls through while `mkdir /etc/x` is caught.
+    md: 'New-Item',
+    ri: 'Remove-Item',
+    del: 'Remove-Item',
+    rd: 'Remove-Item',
+    rmdir: 'Remove-Item',
+    rm: 'Remove-Item',
+    erase: 'Remove-Item',
+    mi: 'Move-Item',
+    mv: 'Move-Item',
+    move: 'Move-Item',
+    ci: 'Copy-Item',
+    cp: 'Copy-Item',
+    copy: 'Copy-Item',
+    cpi: 'Copy-Item',
+    si: 'Set-Item',
+    rni: 'Rename-Item',
+    ren: 'Rename-Item',
+    // Process
+    ps: 'Get-Process',
+    gps: 'Get-Process',
+    kill: 'Stop-Process',
+    spps: 'Stop-Process',
+    start: 'Start-Process',
+    saps: 'Start-Process',
+    sajb: 'Start-Job',
+    ipmo: 'Import-Module',
+    // Output
+    echo: 'Write-Output',
+    write: 'Write-Output',
+    sleep: 'Start-Sleep',
+    // Help
+    help: 'Get-Help',
+    man: 'Get-Help',
+    gcm: 'Get-Command',
+    // Service
+    gsv: 'Get-Service',
+    // Variables
+    gv: 'Get-Variable',
+    sv: 'Set-Variable',
+    // History
+    h: 'Get-History',
+    history: 'Get-History',
+    // Invoke
+    iex: 'Invoke-Expression',
+    iwr: 'Invoke-WebRequest',
+    irm: 'Invoke-RestMethod',
+    icm: 'Invoke-Command',
+    ii: 'Invoke-Item',
+    // PSSession — remote code execution surface
+    nsn: 'New-PSSession',
+    etsn: 'Enter-PSSession',
+    exsn: 'Exit-PSSession',
+    gsn: 'Get-PSSession',
+    rsn: 'Remove-PSSession',
+    // Misc
+    cls: 'Clear-Host',
+    clear: 'Clear-Host',
+    select: 'Select-Object',
+    where: 'Where-Object',
+    foreach: 'ForEach-Object',
+    '%': 'ForEach-Object',
+    '?': 'Where-Object',
+    measure: 'Measure-Object',
+    ft: 'Format-Table',
+    fl: 'Format-List',
+    fw: 'Format-Wide',
+    oh: 'Out-Host',
+    ogv: 'Out-GridView',
+    // SECURITY: The following aliases are deliberately omitted because PS Core 6+
+    // removed them (they collide with native executables). Our allowlist logic
+    // resolves aliases BEFORE checking safety — if we map 'sort' → 'Sort-Object'
+    // but PowerShell 7/Windows actually runs sort.exe, we'd auto-allow the wrong
+    // program.
+    //   'sc'   → sc.exe (Service Controller) — e.g. `sc config Svc binpath= ...`
+    //   'sort' → sort.exe — e.g. `sort /O C:\evil.txt` (arbitrary file write)
+    //   'curl' → curl.exe (shipped with Windows 10 1803+)
+    //   'wget' → wget.exe (if installed)
+    // Prefer to leave ambiguous aliases unmapped — users can write the full name.
+    // If adding aliases that resolve to SAFE_OUTPUT_CMDLETS or
+    // ACCEPT_EDITS_ALLOWED_CMDLETS, verify no native .exe collision on PS Core.
+    ac: 'Add-Content',
+    clc: 'Clear-Content',
+    // Write/export: tee-object/export-csv are in
+    // CMDLET_PATH_CONFIG so path-level Edit denies fire on the full cmdlet name,
+    // but PowerShell's built-in aliases fell through to ask-then-approve because
+    // resolveToCanonical couldn't resolve them). Neither tee-object nor
+    // export-csv is in SAFE_OUTPUT_CMDLETS or ACCEPT_EDITS_ALLOWED_CMDLETS, so
+    // the native-exe collision warning above doesn't apply — on Linux PS Core
+    // where `tee` runs /usr/bin/tee, that binary also writes to its positional
+    // file arg and we correctly extract+check it.
+    tee: 'Tee-Object',
+    epcsv: 'Export-Csv',
+    sp: 'Set-ItemProperty',
+    rp: 'Remove-ItemProperty',
+    cli: 'Clear-Item',
+    epal: 'Export-Alias',
+    // Text search
+    sls: 'Select-String',
+  },
+)
+
+const DIRECTORY_CHANGE_CMDLETS = new Set([
+  'set-location',
+  'push-location',
+  'pop-location',
+])
+
+const DIRECTORY_CHANGE_ALIASES = new Set(['cd', 'sl', 'chdir', 'pushd', 'popd'])
+
+/**
+ * Get all command names across all statements, pipeline segments, and nested commands.
+ * Returns lowercased names for case-insensitive comparison.
+ */
+// exported for testing
+export function getAllCommandNames(parsed: ParsedPowerShellCommand): string[] {
+  const names: string[] = []
+  for (const statement of parsed.statements) {
+    for (const cmd of statement.commands) {
+      names.push(cmd.name.toLowerCase())
+    }
+    if (statement.nestedCommands) {
+      for (const cmd of statement.nestedCommands) {
+        names.push(cmd.name.toLowerCase())
+      }
+    }
+  }
+  return names
+}
+
+/**
+ * Get all pipeline segments as flat list of commands.
+ * Useful for checking each command independently.
+ */
+export function getAllCommands(
+  parsed: ParsedPowerShellCommand,
+): ParsedCommandElement[] {
+  const commands: ParsedCommandElement[] = []
+  for (const statement of parsed.statements) {
+    for (const cmd of statement.commands) {
+      commands.push(cmd)
+    }
+    if (statement.nestedCommands) {
+      for (const cmd of statement.nestedCommands) {
+        commands.push(cmd)
+      }
+    }
+  }
+  return commands
+}
+
+/**
+ * Get all redirections across all statements.
+ */
+// exported for testing
+export function getAllRedirections(
+  parsed: ParsedPowerShellCommand,
+): ParsedRedirection[] {
+  const redirections: ParsedRedirection[] = []
+  for (const statement of parsed.statements) {
+    for (const redir of statement.redirections) {
+      redirections.push(redir)
+    }
+    // Include redirections from nested commands (e.g., from && / || chains)
+    if (statement.nestedCommands) {
+      for (const cmd of statement.nestedCommands) {
+        if (cmd.redirections) {
+          for (const redir of cmd.redirections) {
+            redirections.push(redir)
+          }
+        }
+      }
+    }
+  }
+  return redirections
+}
+
+/**
+ * Get all variables, optionally filtered by scope (e.g., 'env').
+ * Variable paths in PowerShell can have scopes like "env:PATH", "global:x".
+ */
+export function getVariablesByScope(
+  parsed: ParsedPowerShellCommand,
+  scope: string,
+): ParsedVariable[] {
+  const prefix = scope.toLowerCase() + ':'
+  return parsed.variables.filter(v => v.path.toLowerCase().startsWith(prefix))
+}
+
+/**
+ * Check if any command in the parsed result matches a given name (case-insensitive).
+ * Handles common aliases too.
+ */
+export function hasCommandNamed(
+  parsed: ParsedPowerShellCommand,
+  name: string,
+): boolean {
+  const lowerName = name.toLowerCase()
+  const canonicalFromAlias = COMMON_ALIASES[lowerName]?.toLowerCase()
+
+  for (const cmdName of getAllCommandNames(parsed)) {
+    if (cmdName === lowerName) {
+      return true
+    }
+    // Check if the command is an alias that resolves to the requested name
+    const canonical = COMMON_ALIASES[cmdName]?.toLowerCase()
+    if (canonical === lowerName) {
+      return true
+    }
+    // Check if the requested name is an alias and the command is its canonical form
+    if (canonicalFromAlias && cmdName === canonicalFromAlias) {
+      return true
+    }
+    // Check if both resolve to the same canonical cmdlet (alias-to-alias match)
+    if (canonical && canonicalFromAlias && canonical === canonicalFromAlias) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Check if the command contains any directory-changing commands.
+ * (Set-Location, cd, sl, chdir, Push-Location, pushd, Pop-Location, popd)
+ */
+// exported for testing
+export function hasDirectoryChange(parsed: ParsedPowerShellCommand): boolean {
+  for (const cmdName of getAllCommandNames(parsed)) {
+    if (
+      DIRECTORY_CHANGE_CMDLETS.has(cmdName) ||
+      DIRECTORY_CHANGE_ALIASES.has(cmdName)
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Check if the command is a single simple command (no pipes, no semicolons, no operators).
+ */
+// exported for testing
+export function isSingleCommand(parsed: ParsedPowerShellCommand): boolean {
+  const stmt = parsed.statements[0]
+  return (
+    parsed.statements.length === 1 &&
+    stmt !== undefined &&
+    stmt.commands.length === 1 &&
+    (!stmt.nestedCommands || stmt.nestedCommands.length === 0)
+  )
+}
+
+/**
+ * Check if a specific command has a given argument/flag (case-insensitive).
+ * Useful for checking "-EncodedCommand", "-Recurse", etc.
+ */
+export function commandHasArg(
+  command: ParsedCommandElement,
+  arg: string,
+): boolean {
+  const lowerArg = arg.toLowerCase()
+  return command.args.some(a => a.toLowerCase() === lowerArg)
+}
+
+/**
+ * Tokenizer-level dash characters that PowerShell's parser accepts as
+ * parameter prefixes. SpecialCharacters.IsDash (CharTraits.cs) accepts exactly
+ * these four: ASCII hyphen-minus, en-dash, em-dash, horizontal bar. These are
+ * tokenizer-level — they apply to ALL cmdlet parameters, not just argv to
+ * powershell.exe (contrast with `/` which is an argv-parser quirk of
+ * powershell.exe 5.1 only; see PS_ALT_PARAM_PREFIXES in powershellSecurity.ts).
+ *
+ * Extent.Text preserves the raw character; transformCommandAst uses ce.text
+ * for CommandParameterAst elements, so these reach callers unchanged.
+ */
+export const PS_TOKENIZER_DASH_CHARS = new Set([
+  '-', // U+002D hyphen-minus (ASCII)
+  '\u2013', // en-dash
+  '\u2014', // em-dash
+  '\u2015', // horizontal bar
+])
+
+/**
+ * Determines if an argument is a PowerShell parameter (flag), using the AST
+ * element type as ground truth when available.
+ *
+ * The parser maps CommandParameterAst → 'Parameter' regardless of which dash
+ * character the user typed — PowerShell's tokenizer handles that. So when
+ * elementType is available, it's authoritative:
+ *   - 'Parameter' → true (covers `-Path`, `–Path`, `—Path`, `―Path`)
+ *   - anything else → false (a quoted "-Path" is StringConstant, not a param)
+ *
+ * When elementType is unavailable (backward compat / no AST detail), fall back
+ * to a char check against PS_TOKENIZER_DASH_CHARS.
+ */
+export function isPowerShellParameter(
+  arg: string,
+  elementType?: CommandElementType,
+): boolean {
+  if (elementType !== undefined) {
+    return elementType === 'Parameter'
+  }
+  return arg.length > 0 && PS_TOKENIZER_DASH_CHARS.has(arg[0]!)
+}
+
+/**
+ * Check if any argument on a command is an unambiguous abbreviation of a PowerShell parameter.
+ * PowerShell allows parameter abbreviation as long as the prefix is unambiguous.
+ * The minPrefix is the shortest unambiguous prefix for the parameter.
+ * For example, minPrefix '-en' for fullParam '-encodedcommand' matches '-en', '-enc', '-enco', etc.
+ */
+export function commandHasArgAbbreviation(
+  command: ParsedCommandElement,
+  fullParam: string,
+  minPrefix: string,
+): boolean {
+  const lowerFull = fullParam.toLowerCase()
+  const lowerMin = minPrefix.toLowerCase()
+  return command.args.some(a => {
+    // Strip colon-bound value (e.g., -en:base64value -> -en)
+    const colonIndex = a.indexOf(':', 1)
+    const paramPart = colonIndex > 0 ? a.slice(0, colonIndex) : a
+    // Strip backtick escapes — PowerShell resolves `-Member`Name` to
+    // `-MemberName` but Extent.Text preserves the backtick, causing
+    // prefix-comparison misses on the raw text.
+    const lower = paramPart.replace(/`/g, '').toLowerCase()
+    return (
+      lower.startsWith(lowerMin) &&
+      lowerFull.startsWith(lower) &&
+      lower.length <= lowerFull.length
+    )
+  })
+}
+
+/**
+ * Split a parsed command into its pipeline segments for per-segment permission checking.
+ * Returns each pipeline's commands separately.
+ */
+export function getPipelineSegments(
+  parsed: ParsedPowerShellCommand,
+): ParsedStatement[] {
+  return parsed.statements
+}
+
+/**
+ * True if a redirection target is PowerShell's `$null` automatic variable.
+ * `> $null` discards output (like /dev/null) — not a filesystem write.
+ * `$null` cannot be reassigned, so this is safe to treat as a no-op sink.
+ * `${null}` is the same automatic variable via curly-brace syntax. Spaces
+ * inside the braces (`${ null }`) name a different variable, so no regex.
+ */
+export function isNullRedirectionTarget(target: string): boolean {
+  const t = target.trim().toLowerCase()
+  return t === '$null' || t === '${null}'
+}
+
+/**
+ * Get output redirections (file redirections, not merging redirections).
+ * Returns only redirections that write to files.
+ */
+// exported for testing
+export function getFileRedirections(
+  parsed: ParsedPowerShellCommand,
+): ParsedRedirection[] {
+  return getAllRedirections(parsed).filter(
+    r => !r.isMerging && !isNullRedirectionTarget(r.target),
+  )
+}
+
+/**
+ * Derive security-relevant flags from the parsed command structure.
+ * This replaces the previous approach of computing flags in PowerShell via
+ * separate Find-AstNodes calls. Instead, the PS1 script tags each element
+ * with its AST node type, and this function walks those types.
+ */
+// exported for testing
+export function deriveSecurityFlags(
+  parsed: ParsedPowerShellCommand,
+): SecurityFlags {
+  const flags: SecurityFlags = {
+    hasSubExpressions: false,
+    hasScriptBlocks: false,
+    hasSplatting: false,
+    hasExpandableStrings: false,
+    hasMemberInvocations: false,
+    hasAssignments: false,
+    hasStopParsing: parsed.hasStopParsing,
+  }
+
+  function checkElements(cmd: ParsedCommandElement): void {
+    if (!cmd.elementTypes) {
+      return
+    }
+    for (const et of cmd.elementTypes) {
+      switch (et) {
+        case 'ScriptBlock':
+          flags.hasScriptBlocks = true
+          break
+        case 'SubExpression':
+          flags.hasSubExpressions = true
+          break
+        case 'ExpandableString':
+          flags.hasExpandableStrings = true
+          break
+        case 'MemberInvocation':
+          flags.hasMemberInvocations = true
+          break
+      }
+    }
+  }
+
+  for (const stmt of parsed.statements) {
+    if (stmt.statementType === 'AssignmentStatementAst') {
+      flags.hasAssignments = true
+    }
+    for (const cmd of stmt.commands) {
+      checkElements(cmd)
+    }
+    if (stmt.nestedCommands) {
+      for (const cmd of stmt.nestedCommands) {
+        checkElements(cmd)
+      }
+    }
+    // securityPatterns provides a belt-and-suspenders check that catches
+    // patterns elementTypes may miss (e.g. member invocations inside
+    // assignments, subexpressions in non-pipeline statements).
+    if (stmt.securityPatterns) {
+      if (stmt.securityPatterns.hasMemberInvocations) {
+        flags.hasMemberInvocations = true
+      }
+      if (stmt.securityPatterns.hasSubExpressions) {
+        flags.hasSubExpressions = true
+      }
+      if (stmt.securityPatterns.hasExpandableStrings) {
+        flags.hasExpandableStrings = true
+      }
+      if (stmt.securityPatterns.hasScriptBlocks) {
+        flags.hasScriptBlocks = true
+      }
+    }
+  }
+
+  for (const v of parsed.variables) {
+    if (v.isSplatted) {
+      flags.hasSplatting = true
+      break
+    }
+  }
+
+  return flags
+}
+
+// Raw types exported for testing (function exports are inline above)