impel-cli 0.20.37 → 0.20.39

package/README.md

@@ -180,24 +180,36 @@ impel claude --model opus
 impel codex exec "review this repository"
 ```
 
-To run one explicitly selected tenant agent in a single Codex thread, select
+To run one explicitly selected tenant agent in a single native thread, select
 it by exact agent ID (preferred) or unique exact title:
 
 ```sh
+impel claude --agent research-agent --print "answer this question"
 impel codex --agent research-agent exec "answer this question"
 ```
 
-This path loads a generated, tenant-bound profile with the ultra-fast Codex
-Spark model at low reasoning for the thin adapter turns, a read-only local
-sandbox, the exact fixed MCP binding, and only that binding's answer/run,
-resume, and recovery tools. It omits unrelated local repository, app,
-collaboration, permission, environment, and skill-catalog prompt context; the
-selected Eve agent still performs the substantive work. The path also omits
-the normal parent specialist instructions, so there is no parent spawn, parent
-wait, or relay turn. Model, profile, developer-instruction, MCP, approval,
-sandbox, and feature overrides are rejected with `--agent`. The selected
-tenant and profile integrity must match before Codex starts. Ordinary `impel
-codex` passthrough is unchanged.
+Both managed paths verify the selected tenant manifest and generated adapter
+bytes, resolve the canonical native agent name, and omit the normal parent
+specialist instructions. Claude Code receives the explicit 2.1.220 opt-in and
+session permission mode required to run only that adapter's fixed MCP
+allowlist. Impel re-declares the verified adapter under a random per-launch
+name and loads only the isolated user settings source, so project, user, plugin,
+and fixed organization agent names cannot replace it. User-authored Claude
+agents that are absent from the Impel manifest keep Claude's ordinary
+permission behavior. Model, prompt, agent-definition, tool, MCP, settings,
+plugin, worktree, and permission overrides are rejected for a verified managed
+Claude selection.
+
+Codex loads a generated, tenant-bound profile with the ultra-fast Codex Spark
+model at low reasoning for the thin adapter turns, a read-only local sandbox,
+the exact fixed MCP binding, and only that binding's answer/run, resume, and
+recovery tools. It disables host plugin and remote-plugin loading and omits
+unrelated local repository, app, collaboration, permission, environment, and
+skill-catalog prompt context; the selected Eve agent still performs the
+substantive work. Model, profile,
+developer-instruction, MCP, approval, sandbox, and feature overrides are
+rejected for its managed path. Ordinary `impel claude`, user-authored Claude
+agent, and `impel codex` passthrough are unchanged.
 
 ## Remote Fargate sessions
 
@@ -518,6 +530,7 @@ must remain explicit and destructive-state aware.
 impel setup
 impel update
 impel claude
+impel claude --agent <id|exact-title> ...
 impel codex
 impel codex --agent <id|exact-title> ...
 impel tenant list|current|use

package/RELEASE_NOTES.md

@@ -1,5 +1,26 @@
 # Release notes
 
+## 0.20.39 — Isolate fixed Codex agent adapters
+
+- Disables local and remote plugin loading, locally built plugin sharing, and
+  recommended-plugin discovery only in qualified fixed-binding Codex agent
+  profiles while preserving the direct Code Mode namespace and ordinary
+  `impel codex` plugin behavior.
+- Advances the managed-agent manifest and generated-config versions so existing
+  managed installs receive the isolated adapter profile on update.
+
+## 0.20.38 — Restore managed Claude agent permissions
+
+- Verifies an exact synchronized Claude agent and its generated file digest
+  before enabling Claude Code 2.1.220's required bypass-permission opt-in and
+  session mode for that fixed MCP-only adapter.
+- Resolves exact agent IDs and titles to a byte-verified definition, declares
+  it under a random per-launch name with user-only setting sources, omits the
+  parent delegation prompt, and rejects model, prompt, tool, MCP, settings,
+  plugin, worktree, and permission overrides on the managed path.
+- Leaves ordinary Claude launches, user-authored Claude agents, and every
+  Codex launch path unchanged.
+
 ## 0.20.37 — Resume ambiguous native answers
 
 - Retries Next's typed ambiguous direct-answer response with the exact persisted

package/bin/impel.js

@@ -13,6 +13,15 @@ if (process.platform === "win32" && process.env.IMPEL_SKIP_ENTRYPOINT_REFRESH !=
 }
 
 main(process.argv.slice(2)).catch((err) => {
-  console.error(`impel: ${err?.stack || err?.message || err}`);
+  // Intentional user-facing errors are thrown as bare `Error` with guidance in
+  // the message ("not authenticated; run `impel setup`…"); printing their stack
+  // buries the guidance in noise on end-user machines. Programming errors
+  // (TypeError, system errors with a code) keep the full stack, and
+  // IMPEL_DEBUG=1 restores it for everything.
+  const expected = err instanceof Error && err.constructor === Error && !err.code;
+  const detail = expected && process.env.IMPEL_DEBUG !== "1"
+    ? err.message
+    : (err?.stack || err?.message || err);
+  console.error(`impel: ${detail}`);
   process.exitCode = 1;
 });

package/docs/native-agent-host-capability-matrix.md

@@ -1,12 +1,12 @@
 # Native-agent host capability matrix
 
-Validated on 2026-08-08 with isolated temporary homes and tenant profiles. The
+Validated on 2026-08-09 with isolated temporary homes and tenant profiles. The
 matrix is intentionally pinned: a client upgrade must be re-qualified before it
 is treated as an eager host.
 
 | Surface | Pinned build | Exact selected tools | Selected path | Host behavior |
 | --- | --- | --- | --- | --- |
-| Claude Code | 2.1.220 | Yes, agent frontmatter `tools` | Eager | The bound run/answer, resume, and recovery tools are direct child tools. No catalog discovery or code-cell polling is required. |
+| Claude Code | 2.1.220 | Yes, agent frontmatter `tools` | Eager; optional single-thread selection | The bound run/answer, resume, and recovery tools are direct child tools. `impel claude --agent` verifies the exact managed adapter before enabling 2.1.220's bypass-permission opt-in and mode. |
 | Claude Desktop | 1.26832.0 (embedded Code 2.1.222) | Yes, agent frontmatter `tools` | Eager | Same direct-tool contract as Claude Code. |
 | Codex CLI through `impel codex` | 0.147.0 | Yes, with `features.code_mode.direct_only_tool_namespaces = ["mcp__impel_agent"]` | Eager; optional single-thread profile | Existing `@Agent` children call the fixed MCP namespace directly. `impel codex --agent` also removes the parent spawn/wait/relay thread. |
 | ChatGPT desktop Codex | 26.803.41515 (embedded Codex 0.147.0-alpha.6.5) | Yes, with the same exact native namespace | Eager child, compatible parent | Keeps the app's supported `@Agent` parent/child route, but the child no longer needs code cells or code-mode waits. |
@@ -16,6 +16,17 @@ is treated as an eager host.
 - Eager profiles expose only the exact fixed binding's answer/run, resume, and
   recovery tools. `IMPEL_NATIVE_EAGER_TRANSPORT=0` independently restores the
   legacy host-visible tool configuration without deleting profiles or runs.
+- A top-level Claude selection receives `--allow-dangerously-skip-permissions`
+  plus `--permission-mode bypassPermissions` only after its manifest record,
+  canonical definition, fixed MCP binding, and generated file bytes have been
+  verified. User-authored agents keep native Claude behavior.
+- The verified definition is passed through `--agents` under a random
+  per-launch name while `--setting-sources user` excludes project/local
+  definitions. This outranks user and plugin names and makes collisions with a
+  fixed organization-managed agent name impractical.
+- Verified Claude selections reject model, prompt, agent-definition, tool,
+  MCP, settings, plugin, worktree, and permission-policy overrides before
+  native launch.
 - Every local composite keeps one upstream MCP session for its process lifetime,
   validates the exact binding once, and persists the authoritative run handle
   before ambiguous retries.
@@ -39,8 +50,9 @@ is treated as an eager host.
   `impel_agent` is not equivalent and does not qualify as direct exposure.
 - Generated Codex fixed-binding adapters use the ultra-fast Codex Spark model
   at low reasoning for the thin tool-selection and terminal-relay turns, with
-  unrelated local host and skill-catalog context disabled. The selected Eve
-  agent, not this wrapper model, still owns the substantive task.
+  unrelated local host, plugin, remote-plugin, and skill-catalog context
+  disabled. The selected Eve agent, not this wrapper model, still owns the
+  substantive task.
 
 ## Requalification
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.20.37",
+  "version": "0.20.39",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/scripts/capture-release-fixtures.mjs

@@ -0,0 +1,56 @@
+// Capture the released-state fixture corpus (docs/testing-protocol.md §5
+// P0-2, Law 3: fixtures are captured from released artifacts, never
+// fabricated from HEAD after the fact).
+//
+// Run this AT RELEASE TIME, on the exact tree being tagged, so
+// test/fixtures/released/<version>/ honestly represents what shipped:
+//
+//   node scripts/capture-release-fixtures.mjs [--force]
+//
+// It regenerates the managed on-disk artifacts deterministically and offline
+// (see scripts/regen-managed-artifacts.mjs: fixed inputs, temp HOMEs, fake
+// impel_pat_TEST credential, double-generation byte comparison) into
+// test/fixtures/released/<package.json version>/. An existing version
+// directory is never overwritten unless --force is passed.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { REPOSITORY_ROOT, regenerateManagedArtifacts } from "./regen-managed-artifacts.mjs";
+
+export const RELEASED_FIXTURES_ROOT = path.join(REPOSITORY_ROOT, "test", "fixtures", "released");
+
+export async function captureReleaseFixtures({ force = false } = {}) {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(REPOSITORY_ROOT, "package.json"), "utf8"));
+  const version = packageJson.version;
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(version)) {
+    throw new Error(`package.json version "${version}" is not a valid release version`);
+  }
+  const outputDir = path.join(RELEASED_FIXTURES_ROOT, version);
+  if (fs.existsSync(outputDir) && !force) {
+    throw new Error(
+      `${outputDir} already exists. A released fixture is immutable once captured; `
+      + "pass --force only to re-capture a fixture that never shipped.",
+    );
+  }
+  const metadata = await regenerateManagedArtifacts(outputDir, { force });
+  return { version, outputDir, metadata };
+}
+
+const isMain = process.argv[1]
+  && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  const { version, outputDir, metadata } = await captureReleaseFixtures({
+    force: process.argv.includes("--force"),
+  });
+  console.log(
+    `captured released-state fixtures for v${version}: ${metadata.artifacts.length} artifacts `
+    + `(configVersion ${metadata.configVersion}, ${metadata.bundleFingerprint})`,
+  );
+  console.log(`  ${outputDir}`);
+  for (const excluded of metadata.excluded) {
+    console.log(`  excluded: ${excluded.path}`);
+  }
+}

package/scripts/clean-machine/README.md

@@ -0,0 +1,51 @@
+# Clean-machine protocol (P0-4)
+
+Runs the CLI the way a brand-new customer machine does — no git, no winget, no
+dev tooling, stock PATH — because that machine state is structurally
+unreachable from CI runners, and it is where an entire class of first-run
+failures shipped (see `docs/testing-protocol.md`, RC2).
+
+## Windows leg
+
+```sh
+AWS_PROFILE=useimpel scripts/clean-machine/run-clean-windows.sh
+```
+
+Launches a disposable, self-terminating Windows Server EC2 instance (no
+inbound access, no SSH key, S3-scoped instance role) that:
+
+1. asserts the machine is actually clean (git absent; winget state recorded);
+2. installs Node headless from the official MSI;
+3. global-installs the packed tarball with the bundled npm and asserts the
+   install is a real directory (the npm prepare-script symlink class);
+4. runs `impel --version`, `impel doctor`, and non-interactive `impel setup`
+   with hang guards, asserting actionable single-line failures — never a
+   stack trace, never a hang, never a silent success;
+5. runs the full ungated test suite on the git-less machine — the leg that
+   catches tests silently depending on runner tooling;
+6. uploads `results.json` + full logs to S3 and terminates itself.
+
+The runner exits 0 only when every post-condition holds and the suite has no
+failing test. First run of this harness found 18 environment-sensitive tests
+and two CLI output defects; expect it to keep earning its keep.
+
+## When to run
+
+- Before any stable release that touches install/update/setup paths
+  (protocol §4.3), and after changing anything under `src/installRecovery/`,
+  `src/selfInvocation.js`, or the skills/git provisioning chain.
+- Cost: one t3.large for ~15 minutes (well under $0.10) plus a few MB of S3.
+
+## Known limitations
+
+- Windows **Server** AMIs never ship winget, so the winget install path can't
+  be exercised here (EC2 offers no consumer Windows 11 images). That leg stays
+  covered by `test/launch.test.js` (cmd-escaping contract) and the MSIX/Store
+  contract workflow. The results record winget absence so the gap is visible.
+- The instance runs as SYSTEM at first boot, not as an interactive standard
+  user; per-user ACL behavior is covered by the `windows-standard-user-contract`
+  CI job instead.
+- macOS leg: EC2 Mac requires a 24-hour dedicated-host allocation, so the
+  macOS clean-machine equivalent (running vendor apps, name-colliding consumer
+  apps, stale Homebrew binaries) is not automated here yet; the launch-smoke
+  CI job covers the bundle/egress side on ephemeral macOS runners.

package/scripts/clean-machine/run-clean-windows.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# Clean-machine protocol (docs/testing-protocol.md P0-4), Windows leg runner.
+#
+# Launches a disposable, self-terminating Windows Server EC2 instance that has
+# no git and no dev tooling, installs Node headless, global-installs the packed
+# CLI tarball, asserts post-conditions (version/doctor/setup actionable, real
+# install dir), runs the full ungated test suite, and uploads results to S3.
+# The instance needs no inbound access and no SSH key; results come back via a
+# bucket-scoped instance role.
+#
+# Usage:
+#   AWS_PROFILE=useimpel scripts/clean-machine/run-clean-windows.sh
+#
+# Tunables (env): AWS_PROFILE, CLEAN_MACHINE_REGION (default eu-west-2),
+# CLEAN_MACHINE_BUCKET, CLEAN_MACHINE_INSTANCE_TYPE (default t3.large),
+# CLEAN_MACHINE_NODE_VERSION (default v24.19.0).
+#
+# One-time account setup (idempotent, created automatically if missing):
+# bucket, IAM role/instance-profile `clean-machine-test-role` (S3 Get/Put on
+# the bucket only), and a no-inbound security group.
+set -euo pipefail
+
+REGION="${CLEAN_MACHINE_REGION:-eu-west-2}"
+ACCOUNT="$(aws sts get-caller-identity --query Account --output text)"
+BUCKET="${CLEAN_MACHINE_BUCKET:-impel-clean-machine-tests-${ACCOUNT}}"
+INSTANCE_TYPE="${CLEAN_MACHINE_INSTANCE_TYPE:-t3.large}"
+NODE_VERSION="${CLEAN_MACHINE_NODE_VERSION:-v24.19.0}"
+ROLE="clean-machine-test-role"
+SG_NAME="impel-clean-machine-no-inbound"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$HERE/../.." && pwd)"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+export AWS_DEFAULT_REGION="$REGION"
+
+echo "== packing CLI + source from $REPO_ROOT"
+(cd "$REPO_ROOT" && pnpm pack --pack-destination "$WORK" >/dev/null)
+TARBALL="$(basename "$(find "$WORK" -maxdepth 1 -name 'impel-cli-*.tgz' -print -quit)")"
+test -n "$TARBALL"
+(cd "$REPO_ROOT" && git archive --format=tar.gz -o "$WORK/impel-cli-source.tgz" HEAD)
+
+echo "== ensuring bucket/role/security group"
+aws s3api head-bucket --bucket "$BUCKET" 2>/dev/null \
+  || aws s3api create-bucket --bucket "$BUCKET" --create-bucket-configuration "LocationConstraint=$REGION" >/dev/null
+aws iam get-role --role-name "$ROLE" >/dev/null 2>&1 || {
+  aws iam create-role --role-name "$ROLE" --assume-role-policy-document \
+    '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"ec2.amazonaws.com"},"Action":"sts:AssumeRole"}]}' >/dev/null
+  aws iam create-instance-profile --instance-profile-name "$ROLE" >/dev/null
+  aws iam add-role-to-instance-profile --instance-profile-name "$ROLE" --role-name "$ROLE"
+  sleep 10 # instance-profile eventual consistency
+}
+aws iam put-role-policy --role-name "$ROLE" --policy-name s3-scratch --policy-document \
+  "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"s3:GetObject\",\"s3:PutObject\"],\"Resource\":\"arn:aws:s3:::$BUCKET/*\"}]}"
+VPC="$(aws ec2 describe-vpcs --filters Name=is-default,Values=true --query 'Vpcs[0].VpcId' --output text)"
+SG="$(aws ec2 describe-security-groups --filters "Name=group-name,Values=$SG_NAME" --query 'SecurityGroups[0].GroupId' --output text 2>/dev/null)"
+if [ "$SG" = "None" ] || [ -z "$SG" ]; then
+  SG="$(aws ec2 create-security-group --group-name "$SG_NAME" --description "No-inbound SG for impel clean-machine tests" --vpc-id "$VPC" --query GroupId --output text)"
+fi
+SUBNET="$(aws ec2 describe-subnets --filters Name=default-for-az,Values=true --query 'Subnets[0].SubnetId' --output text)"
+AMI="$(aws ssm get-parameter --name /aws/service/ami-windows-latest/Windows_Server-2022-English-Full-Base --query 'Parameter.Value' --output text)"
+
+echo "== uploading artifacts to s3://$BUCKET"
+aws s3 rm "s3://$BUCKET/results" --recursive --only-show-errors 2>/dev/null || true
+aws s3 cp "$WORK/$TARBALL" "s3://$BUCKET/$TARBALL" --only-show-errors
+aws s3 cp "$WORK/impel-cli-source.tgz" "s3://$BUCKET/impel-cli-source.tgz" --only-show-errors
+
+sed -e "s|__BUCKET__|$BUCKET|g" -e "s|__REGION__|$REGION|g" \
+    -e "s|__CLI_TARBALL__|$TARBALL|g" -e "s|__NODE_VERSION__|$NODE_VERSION|g" \
+    "$HERE/userdata.ps1.template" > "$WORK/userdata.ps1"
+
+echo "== launching $INSTANCE_TYPE ($AMI) in $SUBNET"
+INSTANCE="$(aws ec2 run-instances --image-id "$AMI" --instance-type "$INSTANCE_TYPE" \
+  --iam-instance-profile "Name=$ROLE" --instance-initiated-shutdown-behavior terminate \
+  --user-data "file://$WORK/userdata.ps1" --security-group-ids "$SG" --subnet-id "$SUBNET" \
+  --metadata-options HttpTokens=required \
+  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=impel-clean-machine-test},{Key=purpose,Value=impel-cli-testing-protocol}]' \
+  --query 'Instances[0].InstanceId' --output text)"
+echo "instance: $INSTANCE (self-terminates when done)"
+
+echo "== waiting for results (boot + install + suite; typically 8-20 min)"
+for i in $(seq 1 45); do
+  if aws s3api head-object --bucket "$BUCKET" --key results/results.json >/dev/null 2>&1; then
+    aws s3 cp "s3://$BUCKET/results/results.json" "$WORK/results.json" --only-show-errors
+    echo "== results after ~${i} min:"
+    node -e '
+      const r = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8").replace(/^/, ""));
+      const s = r.steps;
+      const fail = [];
+      if (s.preconditions.gitPresent) fail.push("machine not clean: git present");
+      if (s.nodeMsiExit !== 0) fail.push(`node MSI exit ${s.nodeMsiExit}`);
+      if (!s.impelCmdExists) fail.push("impel.cmd missing after global install");
+      if (!s.installIsRealDir) fail.push("global install is a reparse point (npm symlink class)");
+      if (s.version && !/^\d+\.\d+\.\d+/.test((s.version.stdoutHead || "").trim())) fail.push("impel --version malformed");
+      for (const k of ["doctor", "setupNoAuth"]) {
+        const st = s[k]; if (!st) continue;
+        if (st.timedOut) fail.push(`${k} hung`);
+        if (/\n\s+at /.test(st.stderrHead || "")) fail.push(`${k} printed a stack trace`);
+      }
+      const suite = s.testSuite || {};
+      const m = (suite.stdoutHead || "").match(/# fail (\d+)/) || (suite.stdoutHead || "").match(/✖/);
+      if (suite.timedOut) fail.push("test suite hung");
+      if ((suite.stdoutHead || "").includes("✖")) fail.push("test suite has failing tests (see results/node-test.out.txt)");
+      console.log(JSON.stringify({ preconditions: s.preconditions, node: (s.nodeVersion||"").trim(), npm: (s.npmVersion||"").trim(), verdict: fail.length ? "FAIL" : "PASS", failures: fail }, null, 2));
+      process.exitCode = fail.length ? 1 : 0;
+    ' "$WORK/results.json" || { echo "full logs: s3://$BUCKET/results/"; exit 1; }
+    echo "full logs: s3://$BUCKET/results/"
+    exit 0
+  fi
+  STATE="$(aws ec2 describe-instances --instance-ids "$INSTANCE" --query 'Reservations[0].Instances[0].State.Name' --output text 2>/dev/null || echo unknown)"
+  if [ "$STATE" = "terminated" ]; then echo "instance terminated without uploading results"; exit 1; fi
+  sleep 60
+done
+echo "timed out waiting for results; terminating $INSTANCE"
+aws ec2 terminate-instances --instance-ids "$INSTANCE" >/dev/null
+exit 1

package/scripts/clean-machine/userdata.ps1.template

@@ -0,0 +1,102 @@
+<powershell>
+# Clean-machine protocol (docs/testing-protocol.md P0-4), Windows leg.
+# Rendered by run-clean-windows.sh: __BUCKET__, __REGION__, __CLI_TARBALL__,
+# __NODE_VERSION__ are substituted before launch. Runs at first boot as SYSTEM
+# on a fresh Windows Server AMI (no git, no dev tooling), self-terminates.
+$ErrorActionPreference = 'Continue'
+$root = 'C:\clean-machine'
+New-Item -ItemType Directory -Force -Path $root | Out-Null
+Start-Transcript -Path "$root\transcript.txt" -Force
+$bucket = '__BUCKET__'
+$region = '__REGION__'
+$results = [ordered]@{ startedAt = (Get-Date).ToUniversalTime().ToString('o'); steps = [ordered]@{} }
+
+function Run-Step {
+  param([string]$name, [string]$file, [string[]]$argList, [int]$timeoutSec = 180, [string]$stdin = $null)
+  $out = "$root\$name.out.txt"; $err = "$root\$name.err.txt"
+  $procArgs = @{ FilePath = $file; ArgumentList = $argList; RedirectStandardOutput = $out; RedirectStandardError = $err; NoNewWindow = $true; PassThru = $true }
+  if ($null -ne $stdin) { $inFile = "$root\$name.in.txt"; Set-Content -Path $inFile -Value $stdin; $procArgs.RedirectStandardInput = $inFile }
+  $step = [ordered]@{ timedOut = $false; exitCode = $null; stdoutHead = ''; stderrHead = '' }
+  try {
+    $p = Start-Process @procArgs
+    if (-not $p.WaitForExit($timeoutSec * 1000)) {
+      $step.timedOut = $true
+      Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue
+      Start-Sleep -Seconds 2
+    }
+    $step.exitCode = $p.ExitCode
+  } catch { $step.error = "$_" }
+  foreach ($pair in @(@('stdoutHead', $out, 3000), @('stderrHead', $err, 2000))) {
+    $key = $pair[0]; $file2 = $pair[1]; $keep = $pair[2]
+    if (Test-Path $file2) {
+      $text = Get-Content $file2 -Raw -ErrorAction SilentlyContinue
+      if ($null -eq $text) { $text = '' }
+      if ($text.Length -gt (2 * $keep)) { $text = $text.Substring(0, $keep) + "`n...TRUNCATED...`n" + $text.Substring($text.Length - $keep) }
+      $step[$key] = $text
+    }
+  }
+  return $step
+}
+
+# 1. Clean-machine preconditions: git must be absent; record winget state.
+#    (Windows Server AMIs never ship winget — the winget-specific install leg
+#    needs consumer Windows and stays covered by launch.test.js + the MSIX
+#    contract job; record the state so the gap is visible, never silent.)
+$results.steps.preconditions = [ordered]@{
+  gitPresent = [bool](Get-Command git -ErrorAction SilentlyContinue)
+  wingetPresent = [bool](Get-Command winget -ErrorAction SilentlyContinue)
+  osCaption = (Get-CimInstance Win32_OperatingSystem).Caption
+}
+
+# 2. Install Node headless from the official MSI.
+Invoke-WebRequest -Uri 'https://nodejs.org/dist/__NODE_VERSION__/node-__NODE_VERSION__-x64.msi' -OutFile "$root\node.msi" -UseBasicParsing
+$msi = Start-Process msiexec.exe -ArgumentList '/i', "$root\node.msi", '/qn', '/norestart' -Wait -PassThru
+$results.steps.nodeMsiExit = $msi.ExitCode
+$env:Path = [System.Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' + [System.Environment]::GetEnvironmentVariable('Path', 'User')
+$nodeDir = 'C:\Program Files\nodejs'
+$results.steps.nodeVersion = & "$nodeDir\node.exe" --version 2>&1 | Out-String
+$results.steps.npmVersion = & "$nodeDir\npm.cmd" --version 2>&1 | Out-String
+
+# 3. Fetch artifacts from S3 via the instance role.
+Read-S3Object -BucketName $bucket -Key '__CLI_TARBALL__' -File "$root\impel-cli.tgz" -Region $region | Out-Null
+Read-S3Object -BucketName $bucket -Key 'impel-cli-source.tgz' -File "$root\source.tgz" -Region $region | Out-Null
+
+# 4. npm global tarball install on a git-less machine (install-channel class).
+$results.steps.npmInstall = Run-Step 'npm-install' "$nodeDir\npm.cmd" @('install', '--global', "$root\impel-cli.tgz") 300
+$npmPrefix = (& "$nodeDir\npm.cmd" prefix -g 2>$null | Out-String).Trim()
+$results.steps.npmPrefix = $npmPrefix
+$impelCmd = Join-Path $npmPrefix 'impel.cmd'
+$results.steps.impelCmdExists = Test-Path $impelCmd
+$pkgDir = Join-Path $npmPrefix 'node_modules\impel-cli'
+$item = Get-Item $pkgDir -ErrorAction SilentlyContinue
+$results.steps.installIsRealDir = ($null -ne $item) -and (-not ($item.Attributes -band [IO.FileAttributes]::ReparsePoint))
+
+# 5. Post-conditions, not exit codes: version, doctor, setup must be
+#    actionable, never hang, never dump a stack trace at the user.
+if ($results.steps.impelCmdExists) {
+  $results.steps.version = Run-Step 'impel-version' $impelCmd @('--version') 60
+  $results.steps.doctor = Run-Step 'impel-doctor' $impelCmd @('doctor') 180
+  $results.steps.setupNoAuth = Run-Step 'impel-setup' $impelCmd @('setup') 180 -stdin ''
+}
+$results.steps.nodeProcsAfter = @(Get-Process -Name node -ErrorAction SilentlyContinue).Count
+$results.steps.cmdProcsAfter = @(Get-Process -Name cmd -ErrorAction SilentlyContinue).Count
+
+# 6. The full ungated test suite on a machine with no git and no dev tooling —
+#    the leg that catches environment-sensitive tests CI can never see.
+New-Item -ItemType Directory -Force -Path "$root\src" | Out-Null
+tar.exe -xzf "$root\source.tgz" -C "$root\src"
+Push-Location "$root\src"
+$env:HOME = "$root\home"; New-Item -ItemType Directory -Force -Path $env:HOME | Out-Null
+$results.steps.testSuite = Run-Step 'node-test' "$nodeDir\node.exe" @('--test') 1500
+Pop-Location
+
+$results.finishedAt = (Get-Date).ToUniversalTime().ToString('o')
+$results | ConvertTo-Json -Depth 6 | Set-Content -Path "$root\results.json" -Encoding UTF8
+Stop-Transcript
+Write-S3Object -BucketName $bucket -Key 'results/results.json' -File "$root\results.json" -Region $region
+Write-S3Object -BucketName $bucket -Key 'results/transcript.txt' -File "$root\transcript.txt" -Region $region
+foreach ($f in Get-ChildItem "$root\*.out.txt", "$root\*.err.txt" -ErrorAction SilentlyContinue) {
+  Write-S3Object -BucketName $bucket -Key "results/$($f.Name)" -File $f.FullName -Region $region
+}
+Stop-Computer -Force
+</powershell>