Forge playbook: Windows 11 shell safety for agents
Every Boss that touches a shell on this machine runs on Windows 11 with two shells side by side: the Bash
tool (Git Bash, POSIX syntax) and the PowerShell tool (Windows PowerShell 5.1, not PowerShell 7; pwsh
is not installed). Most "the command failed" moments here are a shell mix-up, not a bug in the code. This
skill is the short list of traps, the safe way around each, and the one correct way to stop a process.
When to use
- Use for: writing or debugging a command line or script that runs on Windows; a command that works in one
shell and fails in the other; a path with spaces or a
! (this project folder is my project!);
garbled or double-encoded log files; "file name too long"; $'\r': command not found; EPERM, EBUSY or
"access denied" on a rename or delete; a copy that hangs; a port that is already in use ("poort bezet").
- Not for: the bug behind a failing test or build (
forge-debug, which may send you here when the cause is
a shell trap); parallel worktree isolation itself (forge-worktrees); CI pipelines and Docker
(forge-devops); Electron packaging (forge-electron); a security review (forge-security-review).
Hard rules
- Never kill processes by image name. Only an exact PID you own: the one from your own spawn result,
or the one PID resolved from a port and checked (see "Stop exactly one process"). No name filters, no
wildcard filters, no "stop everything called node". A name-based kill took down the live Forge gateway
on port 4100 on 2026-07-29; the project gate hook now blocks the
common name-based forms (a classifier, not a proof).
- Recursive deletes are not yours to run. The gate hook blocks recursive or forced deletes, except a
provable target inside a scratch area,
node_modules or dist (or the OS temp folder, for targets outside
the project). Anything else goes to the owner with the exact path. Never route around the gate with an inline Node or other interpreter
one-liner, an alias, or a pipeline.
- No opaque execution. Do not pipe text into a shell, do not evaluate a variable as code, do not pass
an encoded PowerShell command. Write the command out in full, or put it in a script file you can read.
- No execution-policy, PATH, registry or system-setting changes. A command that is "not recognised"
gets an absolute path (
& "C:\Program Files\nodejs\node.exe"), never a PATH edit. Turning on Windows
long-path support system-wide is an owner action.
- robocopy always with
/R:1 /W:1. The default is one million retries of 30 seconds; an orphan
robocopy once hung 5.7 hours unseen. /MIR and /PURGE delete files in the target: treat them as a
delete and ask the owner first.
- No push, tag, publish or deploy from a shell step; those stay owner-gated. Outreach is drafted only.
- Never print a secret file's contents to the transcript (the gate blocks it). Check that a key
exists, never what it holds.
- Long CLIs get a watchdog and a log. Start a long-running service with its output captured to a log
file and its PID recorded; never fire-and-forget hidden. Bounded retries only.
Pick the shell first
| Task |
Shell |
Why |
| git, grep/sed, Node tools, POSIX scripts |
Bash tool (Git Bash) |
Unix tools, && works, single quotes are literal |
| Windows cmdlets: ports, processes, services, ACLs |
PowerShell tool |
Get-NetTCPConnection, Stop-Process -Id, objects |
robocopy, taskkill, other /switch exes |
PowerShell tool |
Git Bash rewrites /switch arguments (/R:1 loses its slash, /PID becomes a path) |
| Writing a file other tools will read |
the Write/Edit tool |
No shell encoding surprises at all |
Detect the shell when a script must know: MSYSTEM is set in Git Bash (MINGW64); in PowerShell
$PSVersionTable.PSVersion answers (5.1 here). Forge tooling uses Node. When a step needs Python, probe the
candidate first (python --version, py -3 --version, python3 --version, each with a timeout): a
WindowsApps\python*.exe alias can be a real install manager or a Store stub that hangs, and both happened
here (a stub spun for hours unseen in 2026-10; on 2026-11-05 all three answered 3.14.6).
The ten traps (short form; detail in references)
| # |
Trap |
Safe form |
| 1 |
&& / || in PowerShell 5.1 is a parser error |
A; if ($?) { B } (or run it in Git Bash) |
| 2 |
$VAR vs $env:VAR vs %VAR% |
PowerShell $env:NAME; Bash $NAME; cmd %NAME%; set per call in PS with $env:NAME = 'x'; cmd |
| 3 |
Paths with spaces or ! |
Quote every path. PowerShell: single quotes are literal, & 'C:\path\tool.exe'. Bash: single quotes, or double quotes in a non-interactive script |
| 4 |
Here-strings |
@' ... '@ with the closing '@ at column 0; single-quoted so $ and backticks stay literal |
| 5 |
2>&1 on a native exe in 5.1 |
Wraps every stderr line in an error record and sets $? false even on exit 0 (git writes progress to stderr). Judge by $LASTEXITCODE |
| 6 |
File encoding from PowerShell 5.1 |
Measured here: > and Out-File write UTF-8 with BOM (a profile default; stock 5.1 writes UTF-16), Set-Content writes the ANSI code page. Pass -Encoding utf8 explicitly, or write with the Write tool or Node |
| 7 |
Long paths (over 260 characters) |
git -c core.longpaths=true worktree add/remove ...; deep node_modules and worktrees hit it first |
| 8 |
CRLF vs LF |
A CRLF shell script fails in Bash with $'\r'; byte-compared fixtures differ. Compare after normalising \r\n, keep .gitattributes the authority |
| 9 |
EPERM / EBUSY on rename or delete |
Another handle (editor, indexer, antivirus, a running node) holds the file: retry with bounded backoff, then report the holder. Never kill to free it unless you own that PID |
| 10 |
Aliases that are not the tool |
In 5.1 curl is Invoke-WebRequest, where is Where-Object, sc is Set-Content: call curl.exe, where.exe, sc.exe |
Also in 5.1: -ErrorAction SilentlyContinue hides the message but the tool still reports exit 1; make a
cmdlet failure truly non-fatal with try { ... -ErrorAction Stop } catch { <say why it is fine> } (never an empty catch: it swallows the error), and
native arguments that contain double quotes lose them on the way in, so put inline code in a script file.
Stop exactly one process
- Prefer your own PID. A process you started yourself has its PID in the spawn result
(
Start-Process -PassThru gives .Id; Node gives child.pid). Record it in the run log when you start.
- Otherwise resolve the one PID from the port (PowerShell tool):
Get-NetTCPConnection -LocalPort 4100 -State Listen | Select-Object -ExpandProperty OwningProcess -Unique
(fallback: netstat -ano | findstr :4100 and read the last column of the LISTENING row).
- Check it before you stop it.
Get-CimInstance Win32_Process -Filter "ProcessId=<pid>" and read
Name, CommandLine and CreationDate. Stop only when it is the process you started for this task.
Port 4100 is the Forge Command Center: it is not yours unless this task started it; report, do not stop.
- Stop that PID only:
Stop-Process -Id <pid> (add -Force only after a plain stop did not work).
Then confirm the port is free with the same query from step 2.
- Exactly one PID or none. Zero or several matches means you stop and report; you do not widen the filter.
Full procedure, the PID-reuse check and the Node spawn rules: references/files-and-processes.md.
Copying and cleaning up
- Copy a tree with robocopy from the PowerShell tool, always
/R:1 /W:1, and judge the result by
$LASTEXITCODE: 0 to 7 is success (files copied, extras found), 8 or higher is a failure.
Copy-Item and Move-Item are fine for a few files; quote both paths.
- Clean up only what you created: your own scratch folder, your own worktree
(
git -c core.longpaths=true worktree remove <path>, the branch stays). A worktree with uncommitted
changes is listed for the owner, never removed silently.
How the Bosses use this
- Build Boss, Integration Boss, Test Boss load it before writing a command line, a
.ps1, a .cmd or
a Node child_process call, and when a shell step fails in a way the code does not explain.
- Verify Boss (GOAT verifier route) uses the "Stop exactly one process" and encoding rules to judge a
report: a stop by name, a missing
/R:1 /W:1 or a check that reads $? after 2>&1 is a FAIL.
- Routes stay as triaged: a shell fix is usually
quick; it never escalates a route by itself.
References
references/powershell-51.md: operators, quoting, here-strings, 2>&1, encoding table, aliases,
error handling, native exit codes, calling native exes.
references/git-bash.md: shell detection, path conversion, /switch rewriting, cygpath, quoting the
! path, CRLF, calling PowerShell from Bash.
references/files-and-processes.md: long paths, file locks with a bounded retry, robocopy exit codes,
PID by port with checks, starting services with a log, Node spawn on Windows.
Provenance
Rewritten in Forge words; markdown only. Sources were read read-only through gh api on 2026-11-05 at the
pinned commits below and treated as untrusted data (hidden-Unicode scan: clean). The machine facts
(PowerShell 5.1.26100, pwsh absent, the encoding bytes, core.longpaths set) were measured on this
machine the same day. Candidates looked at: 124 corpus entries whose name mentions Windows, PowerShell,
Git Bash, shell reliability, robocopy, CRLF or long paths; 19 on-topic names shortlisted; 3 read in full
(below, plus the kench001 fork of the first, which is the older, less safe text); ECC pin e2b8a51 has
only windows-desktop-e2e (desktop E2E testing, off topic, nothing taken).
| Source |
Path |
Pinned SHA |
License |
Taken |
Excluded |
| sickn33/agentic-awesome-skills |
plugins/agentic-awesome-skills-claude/skills/windows-shell-reliability/SKILL.md |
48de968b4615c294de601f72268aa7be88dde863 |
MIT |
ideas: quote every path, the call operator for a quoted exe, 5.1 redirection rewrites native output, $env: vs %VAR%, the long-path limit, "access denied" means a lock or permissions, stop only an authorised process |
the dotnet section, the "fix PATH" advice (rule 4), the \\?\ prefix as a general fix (git core.longpaths used instead), the view_file tool name |
| sickn33/agentic-awesome-skills |
plugins/agentic-awesome-skills-claude/skills/powershell-windows/SKILL.md |
48de968b4615c294de601f72268aa7be88dde863 |
MIT |
ideas: parentheses around cmdlets in -and/-or, null checks, ConvertTo-Json -Depth, $LASTEXITCODE after native exes, UTF-8 with BOM for 5.1 scripts |
the script template and its exit handling, the ASCII log-marker table |
| JosiahSiegel/claude-plugin-marketplace |
plugins/powershell-master/skills/powershell-shell-detection/SKILL.md |
5a1b1123b9e50aa9a66a61005ca6fe012cc7442d |
MIT |
ideas: detection by MSYSTEM / PSModulePath / $PSVersionTable, the env-var table, MSYS path conversion and MSYS_NO_PATHCONV, cygpath, alias conflicts |
its "Process Management" example (both the PowerShell and the Git Bash form) kills every process of one image name: removed (HARD MUST 4); the cloud VM stop example (production action); the e-mail extraction example; all helper functions and sed path converters; the pwsh install advice |
MIT notice for the three adapted texts: "Permission is hereby granted, free of charge, to any person
obtaining a copy of this software ... The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT
WARRANTY OF ANY KIND." Copyright (c) 2026 Antigravity User (sickn33 LICENSE at the pinned SHA) and
Copyright (c) 2025 Josiah Siegel (LICENSE at the pinned SHA). No script, hook, binary, install command or
MCP config was copied or run.
1---2name: forge-windows-shell3description: "Use when running or writing commands on Windows (PowerShell, Git Bash); stop one PID by port (poort bezet)."4# W2-BUDGET original description (listing budget): "Use when running or writing commands on Windows (PowerShell 5.1, Git Bash): quoting, encoding, long paths, CRLF, file locks, robocopy, stop one PID by port (commando faalt op Windows, poort bezet)."5metadata:6 source: https://skillmd.com/skills/forgeyclap/forge-windows-shell7---89# Forge playbook: Windows 11 shell safety for agents1011Every Boss that touches a shell on this machine runs on Windows 11 with two shells side by side: the Bash12tool (Git Bash, POSIX syntax) and the PowerShell tool (Windows PowerShell **5.1**, not PowerShell 7; `pwsh`13is not installed). Most "the command failed" moments here are a shell mix-up, not a bug in the code. This14skill is the short list of traps, the safe way around each, and the one correct way to stop a process.1516## When to use17- Use for: writing or debugging a command line or script that runs on Windows; a command that works in one18 shell and fails in the other; a path with spaces or a `!` (this project folder is `my project!`);19 garbled or double-encoded log files; "file name too long"; `$'\r': command not found`; EPERM, EBUSY or20 "access denied" on a rename or delete; a copy that hangs; a port that is already in use ("poort bezet").21- Not for: the bug behind a failing test or build (`forge-debug`, which may send you here when the cause is22 a shell trap); parallel worktree isolation itself (`forge-worktrees`); CI pipelines and Docker23 (`forge-devops`); Electron packaging (`forge-electron`); a security review (`forge-security-review`).2425## Hard rules261. **Never kill processes by image name.** Only an exact PID you own: the one from your own spawn result,27 or the one PID resolved from a port and checked (see "Stop exactly one process"). No name filters, no28 wildcard filters, no "stop everything called node". A name-based kill took down the live Forge gateway29 on port 4100 on 2026-07-29; the project gate hook now blocks the30 common name-based forms (a classifier, not a proof).312. **Recursive deletes are not yours to run.** The gate hook blocks recursive or forced deletes, except a32 provable target inside a scratch area, `node_modules` or `dist` (or the OS temp folder, for targets outside33 the project). Anything else goes to the owner with the exact path. Never route around the gate with an inline Node or other interpreter34 one-liner, an alias, or a pipeline.353. **No opaque execution.** Do not pipe text into a shell, do not evaluate a variable as code, do not pass36 an encoded PowerShell command. Write the command out in full, or put it in a script file you can read.374. **No execution-policy, PATH, registry or system-setting changes.** A command that is "not recognised"38 gets an absolute path (`& "C:\Program Files\nodejs\node.exe"`), never a PATH edit. Turning on Windows39 long-path support system-wide is an owner action.405. **robocopy always with `/R:1 /W:1`.** The default is one million retries of 30 seconds; an orphan41 robocopy once hung 5.7 hours unseen. `/MIR` and `/PURGE` delete files in the target: treat them as a42 delete and ask the owner first.436. **No push, tag, publish or deploy** from a shell step; those stay owner-gated. Outreach is drafted only.447. **Never print a secret file's contents** to the transcript (the gate blocks it). Check that a key45 exists, never what it holds.468. **Long CLIs get a watchdog and a log.** Start a long-running service with its output captured to a log47 file and its PID recorded; never fire-and-forget hidden. Bounded retries only.4849## Pick the shell first50| Task | Shell | Why |51|---|---|---|52| git, grep/sed, Node tools, POSIX scripts | Bash tool (Git Bash) | Unix tools, `&&` works, single quotes are literal |53| Windows cmdlets: ports, processes, services, ACLs | PowerShell tool | `Get-NetTCPConnection`, `Stop-Process -Id`, objects |54| robocopy, taskkill, other `/switch` exes | PowerShell tool | Git Bash rewrites `/switch` arguments (`/R:1` loses its slash, `/PID` becomes a path) |55| Writing a file other tools will read | the Write/Edit tool | No shell encoding surprises at all |5657Detect the shell when a script must know: `MSYSTEM` is set in Git Bash (`MINGW64`); in PowerShell58`$PSVersionTable.PSVersion` answers (5.1 here). Forge tooling uses Node. When a step needs Python, probe the59candidate first (`python --version`, `py -3 --version`, `python3 --version`, each with a timeout): a60`WindowsApps\python*.exe` alias can be a real install manager or a Store stub that hangs, and both happened61here (a stub spun for hours unseen in 2026-10; on 2026-11-05 all three answered 3.14.6).6263## The ten traps (short form; detail in references)64| # | Trap | Safe form |65|---|---|---|66| 1 | `&&` / `\|\|` in PowerShell 5.1 is a parser error | `A; if ($?) { B }` (or run it in Git Bash) |67| 2 | `$VAR` vs `$env:VAR` vs `%VAR%` | PowerShell `$env:NAME`; Bash `$NAME`; cmd `%NAME%`; set per call in PS with `$env:NAME = 'x'; cmd` |68| 3 | Paths with spaces or `!` | Quote every path. PowerShell: single quotes are literal, `& 'C:\path\tool.exe'`. Bash: single quotes, or double quotes in a non-interactive script |69| 4 | Here-strings | `@'` ... `'@` with the closing `'@` at column 0; single-quoted so `$` and backticks stay literal |70| 5 | `2>&1` on a native exe in 5.1 | Wraps every stderr line in an error record and sets `$?` false even on exit 0 (git writes progress to stderr). Judge by `$LASTEXITCODE` |71| 6 | File encoding from PowerShell 5.1 | Measured here: `>` and `Out-File` write UTF-8 **with BOM** (a profile default; stock 5.1 writes UTF-16), `Set-Content` writes the ANSI code page. Pass `-Encoding utf8` explicitly, or write with the Write tool or Node |72| 7 | Long paths (over 260 characters) | `git -c core.longpaths=true worktree add/remove ...`; deep `node_modules` and worktrees hit it first |73| 8 | CRLF vs LF | A CRLF shell script fails in Bash with `$'\r'`; byte-compared fixtures differ. Compare after normalising `\r\n`, keep `.gitattributes` the authority |74| 9 | EPERM / EBUSY on rename or delete | Another handle (editor, indexer, antivirus, a running node) holds the file: retry with bounded backoff, then report the holder. Never kill to free it unless you own that PID |75| 10 | Aliases that are not the tool | In 5.1 `curl` is `Invoke-WebRequest`, `where` is `Where-Object`, `sc` is `Set-Content`: call `curl.exe`, `where.exe`, `sc.exe` |7677Also in 5.1: `-ErrorAction SilentlyContinue` hides the message but the tool still reports exit 1; make a78cmdlet failure truly non-fatal with `try { ... -ErrorAction Stop } catch { <say why it is fine> }` (never an empty catch: it swallows the error), and79native arguments that contain double quotes lose them on the way in, so put inline code in a script file.8081## Stop exactly one process821. **Prefer your own PID.** A process you started yourself has its PID in the spawn result83 (`Start-Process -PassThru` gives `.Id`; Node gives `child.pid`). Record it in the run log when you start.842. **Otherwise resolve the one PID from the port** (PowerShell tool):85 `Get-NetTCPConnection -LocalPort 4100 -State Listen | Select-Object -ExpandProperty OwningProcess -Unique`86 (fallback: `netstat -ano | findstr :4100` and read the last column of the LISTENING row).873. **Check it before you stop it.** `Get-CimInstance Win32_Process -Filter "ProcessId=<pid>"` and read88 `Name`, `CommandLine` and `CreationDate`. Stop only when it is the process you started for this task.89 Port 4100 is the Forge Command Center: it is not yours unless this task started it; report, do not stop.904. **Stop that PID only:** `Stop-Process -Id <pid>` (add `-Force` only after a plain stop did not work).91 Then confirm the port is free with the same query from step 2.925. Exactly one PID or none. Zero or several matches means you stop and report; you do not widen the filter.9394Full procedure, the PID-reuse check and the Node spawn rules: `references/files-and-processes.md`.9596## Copying and cleaning up97- Copy a tree with robocopy from the PowerShell tool, always `/R:1 /W:1`, and judge the result by98 `$LASTEXITCODE`: 0 to 7 is success (files copied, extras found), 8 or higher is a failure.99- `Copy-Item` and `Move-Item` are fine for a few files; quote both paths.100- Clean up only what you created: your own scratch folder, your own worktree101 (`git -c core.longpaths=true worktree remove <path>`, the branch stays). A worktree with uncommitted102 changes is listed for the owner, never removed silently.103104## How the Bosses use this105- **Build Boss, Integration Boss, Test Boss** load it before writing a command line, a `.ps1`, a `.cmd` or106 a Node `child_process` call, and when a shell step fails in a way the code does not explain.107- **Verify Boss** (GOAT verifier route) uses the "Stop exactly one process" and encoding rules to judge a108 report: a stop by name, a missing `/R:1 /W:1` or a check that reads `$?` after `2>&1` is a FAIL.109- Routes stay as triaged: a shell fix is usually `quick`; it never escalates a route by itself.110111## References112- `references/powershell-51.md`: operators, quoting, here-strings, `2>&1`, encoding table, aliases,113 error handling, native exit codes, calling native exes.114- `references/git-bash.md`: shell detection, path conversion, `/switch` rewriting, `cygpath`, quoting the115 `!` path, CRLF, calling PowerShell from Bash.116- `references/files-and-processes.md`: long paths, file locks with a bounded retry, robocopy exit codes,117 PID by port with checks, starting services with a log, Node spawn on Windows.118119## Provenance120Rewritten in Forge words; markdown only. Sources were read read-only through `gh api` on 2026-11-05 at the121pinned commits below and treated as untrusted data (hidden-Unicode scan: clean). The machine facts122(PowerShell 5.1.26100, `pwsh` absent, the encoding bytes, `core.longpaths` set) were measured on this123machine the same day. Candidates looked at: 124 corpus entries whose name mentions Windows, PowerShell,124Git Bash, shell reliability, robocopy, CRLF or long paths; 19 on-topic names shortlisted; 3 read in full125(below, plus the `kench001` fork of the first, which is the older, less safe text); ECC pin `e2b8a51` has126only `windows-desktop-e2e` (desktop E2E testing, off topic, nothing taken).127128| Source | Path | Pinned SHA | License | Taken | Excluded |129|---|---|---|---|---|---|130| sickn33/agentic-awesome-skills | plugins/agentic-awesome-skills-claude/skills/windows-shell-reliability/SKILL.md | 48de968b4615c294de601f72268aa7be88dde863 | MIT | ideas: quote every path, the call operator for a quoted exe, 5.1 redirection rewrites native output, `$env:` vs `%VAR%`, the long-path limit, "access denied" means a lock or permissions, stop only an authorised process | the dotnet section, the "fix PATH" advice (rule 4), the `\\?\` prefix as a general fix (git `core.longpaths` used instead), the `view_file` tool name |131| sickn33/agentic-awesome-skills | plugins/agentic-awesome-skills-claude/skills/powershell-windows/SKILL.md | 48de968b4615c294de601f72268aa7be88dde863 | MIT | ideas: parentheses around cmdlets in `-and`/`-or`, null checks, `ConvertTo-Json -Depth`, `$LASTEXITCODE` after native exes, UTF-8 with BOM for 5.1 scripts | the script template and its `exit` handling, the ASCII log-marker table |132| JosiahSiegel/claude-plugin-marketplace | plugins/powershell-master/skills/powershell-shell-detection/SKILL.md | 5a1b1123b9e50aa9a66a61005ca6fe012cc7442d | MIT | ideas: detection by `MSYSTEM` / `PSModulePath` / `$PSVersionTable`, the env-var table, MSYS path conversion and `MSYS_NO_PATHCONV`, `cygpath`, alias conflicts | **its "Process Management" example (both the PowerShell and the Git Bash form) kills every process of one image name: removed (HARD MUST 4)**; the cloud VM stop example (production action); the e-mail extraction example; all helper functions and `sed` path converters; the pwsh install advice |133134MIT notice for the three adapted texts: "Permission is hereby granted, free of charge, to any person135obtaining a copy of this software ... The above copyright notice and this permission notice shall be136included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT137WARRANTY OF ANY KIND." Copyright (c) 2026 Antigravity User (sickn33 `LICENSE` at the pinned SHA) and138Copyright (c) 2025 Josiah Siegel (`LICENSE` at the pinned SHA). No script, hook, binary, install command or139MCP config was copied or run.