Unattended launch
/wizard:generate is for a step a human has to perform: a dashboard click, a
2FA code, an unplug. This skill is the other case. The work is fully
scriptable, and a human is in the loop only because the agent lacks the
privilege or a policy reserves the run for the operator. The human launches
the script once. The script does the work and writes a result file. The agent
reads that file. The human does not paste a terminal log back into the chat.
An irreversible step (wsl --unregister, git push --force) still asks the
human, in this skill or in generate. That is a consent prompt, not a reason
to make the rest of the script interactive.
When to use which
| Reason a human is involved |
Owner |
| Agent lacks the privilege (UAC, elevated shell) |
this skill |
| Agent is forbidden by policy |
this skill |
| Dashboard, 2FA, or another step no script can perform |
/wizard:generate |
| Irreversible and needs consent |
Confirm-Irreversible in the script |
Process
1. Scope
List the steps, the inputs, and why the agent cannot launch the script. Read
the repo for commands and key names. From a live .env, take key names only.
Never values. Mark each irreversible step with the exact name the human will
type (wsl --unregister Ubuntu-26.04); step 2 passes those names to
-Irreversible. Show the ordered stages and wait for the user to confirm them.
Done when: every stage is named, each input has a resolution rung, and
each irreversible step is marked and listed as an -Irreversible name.
2. Author
Copy template.ps1 with exactly
cat "${CLAUDE_SKILL_DIR}/template.ps1" > <target>.ps1, then edit the copy;
never retype it. Leave the library above # STAGES unchanged.
Replace the example Invoke-UnattendedRun body with the procedure, using only
these helpers:
Invoke-UnattendedRun -ResultDirectory -Stages -Irreversible <names> -Secrets <declarations>.
Runs the stages and writes the result. -Irreversible is the declared list of
irreversible steps, for example 'wsl --unregister Ubuntu-26.04'. It is
printed to the transcript before the stages run (irreversible actions: none when empty; not under -Test) and recorded as irreversible_actions,
on success and on failure. -Secrets is the declared list of secrets, each
@{ Name = 'API_TOKEN'; FilePath = 'C:\ops\token.txt' } (FilePath is
optional). Every declared name resolves once, before the first stage, so the
human answers every hidden prompt up front and the rest of the run is
unattended. The names are printed (secrets: none when empty; not under
-Test) and recorded as secrets, names only, on success and on failure.
Assert-Elevation -Mode Required or Forbidden. Elevation is a constraint
with two failure directions.
Assert-NotInside -Name <wsl-distro>. The script must not be running inside
the WSL distro it restarts. It compares Name with WSL_DISTRO_NAME only: a
service, container or process is not detected. A WSL login cutover cannot be a
script running inside that distro; emit PowerShell so it runs on the Windows
host.
Resolve-UnattendedSecret -Name <ENV> -FilePath <optional>. First hit wins:
environment variable, then the file, then a Microsoft.PowerShell.SecretManagement
vault, then the native store (macOS Keychain through security find-generic-password -s <name> -w; Linux pass show <name> for an entry file <name>.gpg, first line
only), then one hidden prompt. Each store rung is skipped silently when its
module, command or the name is absent. The vault uses only a string secret
(see the store gotchas). A name declared in
-Secrets returns the value resolved before the first stage; declaring a name
twice fails the run. An undeclared name runs the ladder at this call, with its
own prompt. The value is redacted out of the transcript.
Assert-PriorResult -Path <result-latest.json>. Do not start until the
previous script's result is ok.
Add-Preflight -Name -Test -Fix. Fail before later steps, and carry the
remediation command in the result.
Invoke-IdempotentStep -Name -Done -Action. A re-run after a partial failure
skips work that is already done.
Wait-ForState -Name -Predicate -TimeoutSeconds 300 -IntervalSeconds 5. The
preferred way to prove a requested state: poll the outcome, never the exit
code of the request. It polls the predicate, prints one progress line per
poll, and returns once the predicate's last output is truthy; otherwise it
throws timed out waiting for <Name> with the last value or error. A
predicate that throws counts as not yet, because ephemeral targets race. The
predicate must first assert a non-empty observation ($pools.Count -gt 0 -and ...): a vacuous pass is the author's bug, so a drain proof that sees no pools
must fail, not pass. It records a wait <Name> step. It emits $true, so
standing alone it is written $null = Wait-ForState ....
Use-GuardedResource -Name -Take -Prove -Release [-TolerateTakeExit]. Take a
shared resource out of service and release it only after proof. Prove must
throw on failure or emit a truthy value as its last output; $false, no
output, or a nonzero native exit all count as failed proof and keep the
resource held. A failure leaves it listed in held_resources.
-TolerateTakeExit records a nonzero native exit from Take as a warning
instead of throwing (a thrown exception still fails), so Prove is the only
gate. Drain example: the request exits 5 while the drain proceeds, so use
-TolerateTakeExit with -Prove { Wait-ForState -Name drain -Predicate { $pools.Count -gt 0 -and -not ($pools | Where-Object Active) } }.
Assert-ParsedState -Name -Value. Throws when a parsed listing is $null, an
empty array, or only whitespace, and otherwise prints the item count.
Unknown state is a stop, not already absent.
Invoke-NativeUtf8 -Block. Runs the block with WSL_UTF8=1 and UTF-8
console decoding, restores both afterwards (also when the block throws), and
returns the block's output. It is the pin for wsl.exe listings (see
Gotchas). A CLI that has --json should use that instead of parsing human
output.
Confirm-Irreversible -Name. The human types the name. Anything else aborts.
It refuses before prompting when the name is not in -Irreversible
(irreversible step X was not declared) and while any guarded resource is
still held (refusing irreversible step X while resources are held: ...).
A confirmed step is recorded as irreversible <Name>.
Set the result directory to a path the agent can read after the human runs the
script. The envelope is cutover.result/1: per-step status and detail,
mode, warnings, held_resources, irreversible_actions, secrets,
transcript, and a result-latest.json copy. The schema string is unchanged,
and irreversible_actions, secrets and mode are additive fields: read their
absence in an older result as an empty list and run.
Order and unknowns
- Irreversible steps go last, after every precondition is proven in the same
run. A proof from an earlier run or an answer typed at a prompt is not one.
Confirm-Irreversible enforces the resource half: it refuses while any
Use-GuardedResource is still held.
- Every guard whose false branch skips a destructive step
(
-Done { $names -notcontains 'Ubuntu-26.04' }) reads a listing that is empty
when the read failed. Pass the parsed listing through Assert-ParsedState
first, so an unknown state stops the run instead of reading as already absent.
- After the destructive step, re-verify the outcome with
Wait-ForState (the
distro is gone, the port is closed). The destructive command's exit code is
not that proof.
Dry run
The script takes -WhatIf and -Test. Neither invokes a mutating block, and
both write only the result directory, as result-dry-latest.json, so a
preview never replaces a real run's result-latest.json.
-WhatIf narrates the plan: one What if: line per step, including steps
already done, then the blast radius as counts: steps that would run,
resources that would be taken out of service, declared irreversible actions.
-Test reports the delta: nothing is printed but one final line. The result's
delta array holds only the steps that would run plus failed preflights.
With both switches, -Test wins.
- The result gains
mode (run, whatif, test) and, in a dry run,
planned with the counts steps, resources, irreversible and secrets.
Read-only helpers run in every mode, so a missing prerequisite fails a dry run
with no side effects: Assert-Elevation, Assert-NotInside,
Assert-PriorResult, Add-Preflight, Assert-ParsedState,
Invoke-NativeUtf8, the -Done probe of Invoke-IdempotentStep, and the
environment, file and store rungs of secret resolution (vault, Keychain, pass). Each
probe, preflight test and wrapped read must only read. The vault rung reads
every registered vault, and a locked vault, Keychain or pass can ask the human
for a password during a dry run (see the store gotchas).
Mutating helpers skip their blocks and record a would-run step, or skipped
when -Done is already true: Invoke-IdempotentStep -Action,
Use-GuardedResource (Take, Prove and Release), Confirm-Irreversible (no
prompt), Wait-ForState (no polling), and secret resolution, declared or not (no
hidden prompt for a secret; each name that the environment, the file and every store
miss records a would prompt step and yields the placeholder <NAME>).
A dry run does not exercise success detection inside a step: no Prove block or
Wait-ForState predicate runs, so it checks the plan and the prerequisites, not
that the state is reached, and it does not replace Wait-ForState. Put every
effect inside a helper's block: a bare native command in -Stages runs in every
mode.
3. Hand off
Do not launch the script. Print the # STAGES block and get explicit approval
first: the agent runs nothing before the human has seen the stages. Check that
every effect sits inside a helper's block, because -Test runs a bare native
command. After approval the agent's own entry is pwsh -File <script> -Test,
which changes nothing when every effect is inside a helper: read
result-dry-latest.json (status, delta, planned) and fix what it
reports; if a fix changes the stages, print them and get approval again. Then
tell the human to launch it. Say which elevation mode it demands, that it requires PowerShell 7 (pwsh),
launched with pwsh -File <script> (Windows PowerShell 5.1 fails at
#requires), and the result path. Tell the human to run -WhatIf first, read
its narration and blast radius, and only then make the real launch. After the
real run, read result-latest.json. Do not ask them to paste the transcript.
Next
/wizard:generate when a step is a dashboard click, a one-time code, or another action no script can perform.
Gotchas
Assert-NotInside reads WSL_DISTRO_NAME. WIZARD_INSIDE_MARKER, when set,
replaces it: that is the test seam template.test.sh uses, not an operator
setting. A script running inside a service or container passes the guard.
- The agent never launches the real run. A pipeline or an agent shell is the
wrong principal.
-Test is the one exception, because it invokes no mutating
block. It also sets -WhatIf, so a cmdlet outside a helper that honors
-WhatIf is skipped too; a native command outside a helper is not.
- Dry-run behavior worth knowing: a standalone
Wait-ForState is not polled,
because the state it waits for follows a mutation the dry run skipped;
Use-GuardedResource never lists the resource
in held_resources, because nothing was taken; Resolve-UnattendedSecret
and a declared secret return the placeholder <NAME> when they would prompt;
Confirm-Irreversible
still refuses an undeclared name, before it would prompt. A -Done probe that
throws fails a dry run as it fails a real one, so write probes that tolerate a
target that does not exist yet.
-Test from the agent's own shell stops at Assert-Elevation -Mode Required
with status failed and refusing to run unelevated: the shell lacks the
privilege, and that is the expected result. The human's elevated -WhatIf
reaches the rest of the script.
- A
Take that asks a system to reach a state (a drain with --wait) can exit
nonzero while the state is reached. Do not trust that exit code either way:
pass -TolerateTakeExit and prove the state with Wait-ForState.
wsl.exe writes its listings (--list, --status) as UTF-16, which a
PowerShell capture decodes as text with embedded NULs, so a -contains 'Ubuntu' guard never matches and reads absent. WSL_UTF8=1 makes it emit
UTF-8 (WSL 0.64.0 and later); wrap the call in Invoke-NativeUtf8. Verified
2026-09-29 against the 0.64.0 release notes
(https://github.com/microsoft/WSL/releases/tag/0.64.0), WslClient.cpp in
microsoft/WSL (reads WSL_UTF8; only the value 1 enables UTF-8), and
Microsoft's diagnostics/collect-wsl-logs.ps1 (sets it beside
[Console]::OutputEncoding). The Microsoft Learn WSL pages do not mention
it. Recheck when a WSL release note changes or drops WSL_UTF8, or the Learn
basic-commands page documents a different switch for wsl.exe output
encoding.
- The store rung calls
Get-Secret -AsPlainText with no -Vault, so it searches
every registered vault, the default vault first and remote ones included, on any
platform where the module and a vault are present. Nothing gates it to Windows. A
locked SecretStore whose Interaction is Prompt asks for its password in an
interactive session, so -WhatIf and -Test can prompt for it too; with
Interaction set to None the read fails and the rung is skipped.
-AsPlainText converts only a String or SecureString, so a PSCredential,
hashtable or byte[] secret is skipped with a warning and the ladder goes on
to the hidden prompt. SecretStore encrypts with .NET Core cryptographic APIs,
not DPAPI. Verified 2026-09-29 against the SecretManagement
overview
(SecretStore "uses .NET Core cryptographic APIs to encrypt file contents" and
"works on all platforms that support PowerShell 7"; the modules are "feature
complete" with the repository archived, at SecretManagement 1.1.2 and
SecretStore 1.0.6),
Get-Secret
(with no vault named, "all registered vaults are searched"; -AsPlainText "has
no effect" on a secret that is not a String or SecureString) and
Set-SecretStoreConfiguration
(-Interaction). Recheck when the PowerShell Gallery lists a release of either
module after those versions, or the overview page drops its "feature complete"
notice.
- The native store rungs can block an unattended run. The Keychain can raise an
access dialog for an item the calling app is not trusted for or in a locked
keychain, and
pass runs gpg, which asks for a passphrase through pinentry
when the agent has none cached. Before an unattended run, unlock the keychain
(security unlock-keychain) or add the calling app to the item's trusted
applications, and start gpg-agent with the passphrase cached (for example by
running pass show <name> once). pass show prints the whole file; the rung
takes the first line. Verified 2026-09-30 against the Apple
security man page
(find-generic-password: -s matches the service string, -w displays the
password only; unlock-keychain) and the passwordstore.org
pass man page (show
decrypts and prints the named password; gpg-agent is recommended so batch
decryption needs less intervention). Recheck when either man page changes
those flags or commands.
- A secret resolved at runtime stays in the human's process. Do not ask for
the value in chat.
Confirm-Irreversible is the consent prompt. Do not skip it because the
rest of the script is unattended.
- Redaction runs when the script completes or throws. A run killed before
that (Ctrl+C, a closed window, a reboot) leaves the transcript unredacted,
so never print a secret, and tell the human to delete the transcript of an
interrupted run.
Assert-PriorResult trusts the file it reads. When a lower-privilege stage
feeds an elevated one, put the result directory where only the elevated
principal can write.
1---2name: unattended3description: "Author an unattended PowerShell script for work that is fully scriptable but not agent-launchable: the human is only the privilege or policy boundary (UAC, an elevated shell, or a run the repo reserves for the operator). The agent authors the script and never launches the real run. The human launches it once. The script writes cutover.result/1 JSON the agent reads back. Use when: 'run this elevated', 'I have to launch it', 'UAC', 'operator must apply', 'unattended cutover', 'scriptable but I cannot run it'. Don't use it for a dashboard click, a 2FA code, or anything the agent can already run itself."4argument-hint: "<scriptable procedure a human must launch>"5user-invocable: true6disable-model-invocation: false7metadata:8 source: https://skillmd.com/skills/melodic-software/unattended9 workflow-stage: anytime10 summary: Author an unattended script a human launches once for a privilege or policy boundary11---1213# Unattended launch1415`/wizard:generate` is for a step a human has to perform: a dashboard click, a162FA code, an unplug. This skill is the other case. The work is fully17scriptable, and a human is in the loop only because the agent lacks the18privilege or a policy reserves the run for the operator. The human launches19the script once. The script does the work and writes a result file. The agent20reads that file. The human does not paste a terminal log back into the chat.2122An irreversible step (`wsl --unregister`, `git push --force`) still asks the23human, in this skill or in `generate`. That is a consent prompt, not a reason24to make the rest of the script interactive.2526## When to use which2728| Reason a human is involved | Owner |29|---|---|30| Agent lacks the privilege (UAC, elevated shell) | this skill |31| Agent is forbidden by policy | this skill |32| Dashboard, 2FA, or another step no script can perform | `/wizard:generate` |33| Irreversible and needs consent | `Confirm-Irreversible` in the script |3435## Process3637### 1. Scope3839List the steps, the inputs, and why the agent cannot launch the script. Read40the repo for commands and key names. From a live `.env`, take key names only.41Never values. Mark each irreversible step with the exact name the human will42type (`wsl --unregister Ubuntu-26.04`); step 2 passes those names to43`-Irreversible`. Show the ordered stages and wait for the user to confirm them.4445**Done when:** every stage is named, each input has a resolution rung, and46each irreversible step is marked and listed as an `-Irreversible` name.4748### 2. Author4950Copy [template.ps1](template.ps1) with exactly51`cat "${CLAUDE_SKILL_DIR}/template.ps1" > <target>.ps1`, then edit the copy;52never retype it. Leave the library above `# STAGES` unchanged.53Replace the example `Invoke-UnattendedRun` body with the procedure, using only54these helpers:5556- `Invoke-UnattendedRun -ResultDirectory -Stages -Irreversible <names> -Secrets <declarations>`.57 Runs the stages and writes the result. `-Irreversible` is the declared list of58 irreversible steps, for example `'wsl --unregister Ubuntu-26.04'`. It is59 printed to the transcript before the stages run (`irreversible actions:60 none` when empty; not under `-Test`) and recorded as `irreversible_actions`,61 on success and on failure. `-Secrets` is the declared list of secrets, each62 `@{ Name = 'API_TOKEN'; FilePath = 'C:\ops\token.txt' }` (`FilePath` is63 optional). Every declared name resolves once, before the first stage, so the64 human answers every hidden prompt up front and the rest of the run is65 unattended. The names are printed (`secrets: none` when empty; not under66 `-Test`) and recorded as `secrets`, names only, on success and on failure.67- `Assert-Elevation -Mode Required` or `Forbidden`. Elevation is a constraint68 with two failure directions.69- `Assert-NotInside -Name <wsl-distro>`. The script must not be running inside70 the WSL distro it restarts. It compares `Name` with `WSL_DISTRO_NAME` only: a71 service, container or process is not detected. A WSL login cutover cannot be a72 script running inside that distro; emit PowerShell so it runs on the Windows73 host.74- `Resolve-UnattendedSecret -Name <ENV> -FilePath <optional>`. First hit wins:75 environment variable, then the file, then a `Microsoft.PowerShell.SecretManagement`76 vault, then the native store (macOS Keychain through `security77 find-generic-password -s <name> -w`; Linux `pass show <name>` for an entry file `<name>.gpg`, first line78 only), then one hidden prompt. Each store rung is skipped silently when its79 module, command or the name is absent. The vault uses only a string secret80 (see the store gotchas). A name declared in81 `-Secrets` returns the value resolved before the first stage; declaring a name82 twice fails the run. An undeclared name runs the ladder at this call, with its83 own prompt. The value is redacted out of the transcript.84- `Assert-PriorResult -Path <result-latest.json>`. Do not start until the85 previous script's result is `ok`.86- `Add-Preflight -Name -Test -Fix`. Fail before later steps, and carry the87 remediation command in the result.88- `Invoke-IdempotentStep -Name -Done -Action`. A re-run after a partial failure89 skips work that is already done.90- `Wait-ForState -Name -Predicate -TimeoutSeconds 300 -IntervalSeconds 5`. The91 preferred way to prove a requested state: poll the outcome, never the exit92 code of the request. It polls the predicate, prints one progress line per93 poll, and returns once the predicate's last output is truthy; otherwise it94 throws `timed out waiting for <Name>` with the last value or error. A95 predicate that throws counts as not yet, because ephemeral targets race. The96 predicate must first assert a non-empty observation (`$pools.Count -gt 0 -and97 ...`): a vacuous pass is the author's bug, so a drain proof that sees no pools98 must fail, not pass. It records a `wait <Name>` step. It emits `$true`, so99 standing alone it is written `$null = Wait-ForState ...`.100- `Use-GuardedResource -Name -Take -Prove -Release [-TolerateTakeExit]`. Take a101 shared resource out of service and release it only after proof. `Prove` must102 throw on failure or emit a truthy value as its last output; `$false`, no103 output, or a nonzero native exit all count as failed proof and keep the104 resource held. A failure leaves it listed in `held_resources`.105 `-TolerateTakeExit` records a nonzero native exit from `Take` as a warning106 instead of throwing (a thrown exception still fails), so `Prove` is the only107 gate. Drain example: the request exits 5 while the drain proceeds, so use108 `-TolerateTakeExit` with `-Prove { Wait-ForState -Name drain -Predicate {109 $pools.Count -gt 0 -and -not ($pools | Where-Object Active) } }`.110- `Assert-ParsedState -Name -Value`. Throws when a parsed listing is `$null`, an111 empty array, or only whitespace, and otherwise prints the item count.112 Unknown state is a stop, not `already absent`.113- `Invoke-NativeUtf8 -Block`. Runs the block with `WSL_UTF8=1` and UTF-8114 console decoding, restores both afterwards (also when the block throws), and115 returns the block's output. It is the pin for `wsl.exe` listings (see116 Gotchas). A CLI that has `--json` should use that instead of parsing human117 output.118- `Confirm-Irreversible -Name`. The human types the name. Anything else aborts.119 It refuses before prompting when the name is not in `-Irreversible`120 (`irreversible step X was not declared`) and while any guarded resource is121 still held (`refusing irreversible step X while resources are held: ...`).122 A confirmed step is recorded as `irreversible <Name>`.123124Set the result directory to a path the agent can read after the human runs the125script. The envelope is `cutover.result/1`: per-step `status` and `detail`,126`mode`, `warnings`, `held_resources`, `irreversible_actions`, `secrets`,127`transcript`, and a `result-latest.json` copy. The schema string is unchanged,128and `irreversible_actions`, `secrets` and `mode` are additive fields: read their129absence in an older result as an empty list and `run`.130131#### Order and unknowns132133- Irreversible steps go last, after every precondition is proven in the same134 run. A proof from an earlier run or an answer typed at a prompt is not one.135 `Confirm-Irreversible` enforces the resource half: it refuses while any136 `Use-GuardedResource` is still held.137- Every guard whose false branch skips a destructive step138 (`-Done { $names -notcontains 'Ubuntu-26.04' }`) reads a listing that is empty139 when the read failed. Pass the parsed listing through `Assert-ParsedState`140 first, so an unknown state stops the run instead of reading as `already141 absent`.142- After the destructive step, re-verify the outcome with `Wait-ForState` (the143 distro is gone, the port is closed). The destructive command's exit code is144 not that proof.145146#### Dry run147148The script takes `-WhatIf` and `-Test`. Neither invokes a mutating block, and149both write only the result directory, as `result-dry-latest.json`, so a150preview never replaces a real run's `result-latest.json`.151152- `-WhatIf` narrates the plan: one `What if:` line per step, including steps153 already done, then the blast radius as counts: steps that would run,154 resources that would be taken out of service, declared irreversible actions.155- `-Test` reports the delta: nothing is printed but one final line. The result's156 `delta` array holds only the steps that would run plus failed preflights.157 With both switches, `-Test` wins.158- The result gains `mode` (`run`, `whatif`, `test`) and, in a dry run,159 `planned` with the counts `steps`, `resources`, `irreversible` and `secrets`.160161Read-only helpers run in every mode, so a missing prerequisite fails a dry run162with no side effects: `Assert-Elevation`, `Assert-NotInside`,163`Assert-PriorResult`, `Add-Preflight`, `Assert-ParsedState`,164`Invoke-NativeUtf8`, the `-Done` probe of `Invoke-IdempotentStep`, and the165environment, file and store rungs of secret resolution (vault, Keychain, `pass`). Each166probe, preflight test and wrapped read must only read. The vault rung reads167every registered vault, and a locked vault, Keychain or `pass` can ask the human168for a password during a dry run (see the store gotchas).169170Mutating helpers skip their blocks and record a `would-run` step, or `skipped`171when `-Done` is already true: `Invoke-IdempotentStep -Action`,172`Use-GuardedResource` (Take, Prove and Release), `Confirm-Irreversible` (no173prompt), `Wait-ForState` (no polling), and secret resolution, declared or not (no174hidden prompt for a secret; each name that the environment, the file and every store175miss records a `would prompt` step and yields the placeholder `<NAME>`).176177A dry run does not exercise success detection inside a step: no Prove block or178`Wait-ForState` predicate runs, so it checks the plan and the prerequisites, not179that the state is reached, and it does not replace `Wait-ForState`. Put every180effect inside a helper's block: a bare native command in `-Stages` runs in every181mode.182183### 3. Hand off184185Do not launch the script. Print the `# STAGES` block and get explicit approval186first: the agent runs nothing before the human has seen the stages. Check that187every effect sits inside a helper's block, because `-Test` runs a bare native188command. After approval the agent's own entry is `pwsh -File <script> -Test`,189which changes nothing when every effect is inside a helper: read190`result-dry-latest.json` (`status`, `delta`, `planned`) and fix what it191reports; if a fix changes the stages, print them and get approval again. Then192tell the human to launch it. Say which elevation mode it demands, that it requires PowerShell 7 (`pwsh`),193launched with `pwsh -File <script>` (Windows PowerShell 5.1 fails at194`#requires`), and the result path. Tell the human to run `-WhatIf` first, read195its narration and blast radius, and only then make the real launch. After the196real run, read `result-latest.json`. Do not ask them to paste the transcript.197198## Next199200`/wizard:generate` when a step is a dashboard click, a one-time code, or another action no script can perform.201202## Gotchas203204- `Assert-NotInside` reads `WSL_DISTRO_NAME`. `WIZARD_INSIDE_MARKER`, when set,205 replaces it: that is the test seam `template.test.sh` uses, not an operator206 setting. A script running inside a service or container passes the guard.207- The agent never launches the real run. A pipeline or an agent shell is the208 wrong principal. `-Test` is the one exception, because it invokes no mutating209 block. It also sets `-WhatIf`, so a cmdlet outside a helper that honors210 `-WhatIf` is skipped too; a native command outside a helper is not.211- Dry-run behavior worth knowing: a standalone `Wait-ForState` is not polled,212 because the state it waits for follows a mutation the dry run skipped;213 `Use-GuardedResource` never lists the resource214 in `held_resources`, because nothing was taken; `Resolve-UnattendedSecret`215 and a declared secret return the placeholder `<NAME>` when they would prompt;216 `Confirm-Irreversible`217 still refuses an undeclared name, before it would prompt. A `-Done` probe that218 throws fails a dry run as it fails a real one, so write probes that tolerate a219 target that does not exist yet.220- `-Test` from the agent's own shell stops at `Assert-Elevation -Mode Required`221 with status `failed` and `refusing to run unelevated`: the shell lacks the222 privilege, and that is the expected result. The human's elevated `-WhatIf`223 reaches the rest of the script.224- A `Take` that asks a system to reach a state (a drain with `--wait`) can exit225 nonzero while the state is reached. Do not trust that exit code either way:226 pass `-TolerateTakeExit` and prove the state with `Wait-ForState`.227- `wsl.exe` writes its listings (`--list`, `--status`) as UTF-16, which a228 PowerShell capture decodes as text with embedded NULs, so a `-contains229 'Ubuntu'` guard never matches and reads `absent`. `WSL_UTF8=1` makes it emit230 UTF-8 (WSL 0.64.0 and later); wrap the call in `Invoke-NativeUtf8`. Verified231 2026-09-29 against the 0.64.0 release notes232 (<https://github.com/microsoft/WSL/releases/tag/0.64.0>), `WslClient.cpp` in233 `microsoft/WSL` (reads `WSL_UTF8`; only the value `1` enables UTF-8), and234 Microsoft's `diagnostics/collect-wsl-logs.ps1` (sets it beside235 `[Console]::OutputEncoding`). The Microsoft Learn WSL pages do not mention236 it. Recheck when a WSL release note changes or drops `WSL_UTF8`, or the Learn237 basic-commands page documents a different switch for `wsl.exe` output238 encoding.239- The store rung calls `Get-Secret -AsPlainText` with no `-Vault`, so it searches240 every registered vault, the default vault first and remote ones included, on any241 platform where the module and a vault are present. Nothing gates it to Windows. A242 locked SecretStore whose `Interaction` is `Prompt` asks for its password in an243 interactive session, so `-WhatIf` and `-Test` can prompt for it too; with244 `Interaction` set to `None` the read fails and the rung is skipped.245 `-AsPlainText` converts only a `String` or `SecureString`, so a `PSCredential`,246 hashtable or `byte[]` secret is skipped with a warning and the ladder goes on247 to the hidden prompt. SecretStore encrypts with .NET Core cryptographic APIs,248 not DPAPI. Verified 2026-09-29 against the SecretManagement249 [overview](https://learn.microsoft.com/en-us/powershell/utility-modules/secretmanagement/overview)250 (SecretStore "uses .NET Core cryptographic APIs to encrypt file contents" and251 "works on all platforms that support PowerShell 7"; the modules are "feature252 complete" with the repository archived, at SecretManagement 1.1.2 and253 SecretStore 1.0.6),254 [Get-Secret](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.secretmanagement/get-secret?view=ps-modules)255 (with no vault named, "all registered vaults are searched"; `-AsPlainText` "has256 no effect" on a secret that is not a `String` or `SecureString`) and257 [Set-SecretStoreConfiguration](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.secretstore/set-secretstoreconfiguration?view=ps-modules)258 (`-Interaction`). Recheck when the PowerShell Gallery lists a release of either259 module after those versions, or the overview page drops its "feature complete"260 notice.261- The native store rungs can block an unattended run. The Keychain can raise an262 access dialog for an item the calling app is not trusted for or in a locked263 keychain, and `pass` runs `gpg`, which asks for a passphrase through pinentry264 when the agent has none cached. Before an unattended run, unlock the keychain265 (`security unlock-keychain`) or add the calling app to the item's trusted266 applications, and start `gpg-agent` with the passphrase cached (for example by267 running `pass show <name>` once). `pass show` prints the whole file; the rung268 takes the first line. Verified 2026-09-30 against the Apple269 [`security` man page](https://keith.github.io/xcode-man-pages/security.1.html)270 (`find-generic-password`: `-s` matches the service string, `-w` displays the271 password only; `unlock-keychain`) and the passwordstore.org272 [pass man page](https://git.zx2c4.com/password-store/plain/man/pass.1) (`show`273 decrypts and prints the named password; `gpg-agent` is recommended so batch274 decryption needs less intervention). Recheck when either man page changes275 those flags or commands.276- A secret resolved at runtime stays in the human's process. Do not ask for277 the value in chat.278- `Confirm-Irreversible` is the consent prompt. Do not skip it because the279 rest of the script is unattended.280- Redaction runs when the script completes or throws. A run killed before281 that (Ctrl+C, a closed window, a reboot) leaves the transcript unredacted,282 so never print a secret, and tell the human to delete the transcript of an283 interrupted run.284- `Assert-PriorResult` trusts the file it reads. When a lower-privilege stage285 feeds an elevated one, put the result directory where only the elevated286 principal can write.