Retire the Polaris WSL distro: decision record (2026-09-29) - #522

Scope

• What this PR changes, in one or two sentences: adds the dated decision record for retiring the Polaris WSL distro on 2026-09-29, following the 2026-09-25 Vela/VelaNext procedure. The custody repair replaces private project labels with role descriptions, dates the distro state and shortens the credential inventory.
• Base commit: 9b0b8d6d25f9e3fb8f71770500e774170423315e (main merged into the custody branch; merge-only push path).
• Lane: lane:foundation
• Owned paths touched: docs/decisions/2026-09-29-retire-polaris.md (new).

SOTA sources

• Procedure: this repository's own precedent, docs/decisions/2026-09-25-retire-vela-velanext.md: salvage with a SHA-256 manifest verified before the unregister, credential stores neither read nor copied.
• WSL commands: Microsoft Learn, Basic commands for WSL. Sections used: "Set default Linux distribution" (wsl --set-default), "Terminate" (wsl --terminate) and "Unregister or uninstall a Linux distribution" (wsl --unregister).
• Docker cleanup: Docker Engine CLI reference, docker rm and docker network rm (docker/cli). Polaris's networks were removed through its own daemon, so moby removed its bridge rules. moby docker-v29.8.1, daemon/libnetwork/drivers/bridge/internal/iptabler/network.go.
• Shared-kernel binfmt behaviour: [WSL2][systemd][interop] Unable to Execute Windows Binary when systemd enabled microsoft/WSL#8843 and the WSL-generated systemd-binfmt override at /run/systemd/generator/systemd-binfmt.service.d/override.conf, observed on the host.
• Migrated workspace: the project's own uv.lock, applied with uv sync --frozen --python 3.13, the interpreter the Polaris venv used. The vault bind mount is the project's own fstab line from its CLAUDE.md.
• Gateway supersession: docs/decisions/2026-09-27-omniroute-account-pool.md. It lists CLIProxyAPI v7.3.19 as a rejected alternative to the OmniRoute gateway.
• Custody privacy and history rules: this repository at 9b0b8d6d25f9e3fb8f71770500e774170423315e, record_sanitizer.py (rules, assert_clean), the terminal-experience decision, and the Vela credential precedent.
• Later distribution work: the 2026-10-01 new-WSL distro recipe. This is a link to later work; it makes no NativeStack/Polaris layout claim.

Evidence-class table

Host observations below belong to the original 2026-09-29 author session. The custody builder's returned repair checks follow under Local commands run.

Local commands run

Run on the custody worktree at local HEAD 1edd0efe78226dfc838ea3e7d162ef1eabee8f65, with the R1-R3 repair in the working tree. The repair was then committed and pushed as 622b1d16850e68d68c2bf5943fcc3edc8730065a. PR522_HANDOFF resolves privately to the assigned handoff directory for the prepared-body check. The Review round section repeats the sanitizer checks on the committed head and on the published description.

$ rtk git diff --name-only origin/main...HEAD
docs/decisions/2026-09-29-retire-polaris.md
exit 0

$ rtk python3 -B -c 'import sys; sys.path.insert(0, "evidence/artifacts/terminal-lane-cross-family-review-20260930"); import record_sanitizer as s; s.assert_clean(open("docs/decisions/2026-09-29-retire-polaris.md", encoding="utf-8").read(), "record"); print("clean")'
Before repair: AssertionError: record still holds a private project label (exit 1)
After repair: clean (exit 0)
Evidence class: local_integration

$ rtk python3 -B -c 'import sys; sys.path.insert(0, "evidence/artifacts/terminal-lane-cross-family-review-20260930"); import record_sanitizer as s; s.assert_clean(sys.stdin.read(), "prepared PR body"); print("clean")' < "$PR522_HANDOFF/PR-BODY.md"
clean
exit 0
Evidence class: local_integration

$ for f in 2026-09-25-retire-vela-velanext.md 2026-09-27-omniroute-account-pool.md 2026-09-28-terminal-experience.md 2026-10-01-new-wsl-distro-recipe.md; do test -f "docs/decisions/$f" || echo "missing $f"; done
(no output)
exit 0

$ rtk git diff --quiet origin/main...HEAD -- manifests/evidence.json && echo untouched
untouched
exit 0

$ rtk git diff --check
(no output)
exit 0

$ rtk python3 -B scripts/validate.py
{"components": 69, "hashed_files": 9420, "profiles": 4, "receipts": 187, "status": "passed"}
Integrity and scope checks only; no live provider or GPU execution.
exit 0

Read-only observations of the original remote head before the coordinator applies this description and pushes the repaired content:

$ rtk gh pr view 522 --json body --jq .body | rtk python3 -B -c 'import sys; sys.path.insert(0, "evidence/artifacts/terminal-lane-cross-family-review-20260930"); import record_sanitizer as s; s.assert_clean(sys.stdin.read(), "PR body"); print("clean")'
AssertionError: PR body still holds a private project label
exit 1

$ rtk gh pr checks 522 --required
CI Checks Summary:
  [ok] Passed: 7
  [FAIL] Failed: 1

  Failed checks:
    validate-macos	fail	29m28s	https://github.com/seathatflowsinourveins/native-agent-stack/actions/runs/36667219887/job/109734351910
exit 1

$ rtk gh pr view 522 --json headRefOid,mergeStateStatus
{"headRefOid":"0700299c765258c69d1a22120d90e36e369a991d","mergeStateStatus":"BLOCKED"}
exit 0

Decision record

docs/decisions/2026-09-29-retire-polaris.md. The archive and cleanup log are private. The photo-archive pipeline is to be picked up in NativeStack later, per the user's instruction. The record retains the six-row classification table, archive contents, 343 local commits, shared-network cleanup, interop checks, 706 GB disk, consequences, procedure link and both verbatim user instructions.

Custody

Claude session native-agent-stack-0c took custody on 2026-10-03 UTC after the two-hour objection window. The retirement and its host observations retain the original 2026-09-29 Claude Code author session. R1 replaces the two private project labels with role descriptions in the record and description; R2 dates the post-unregister state to 2026-09-29 and links later distro work; R3 uses the generic private-cleanup-log credential sentence. The custody branch contains the coordinator's merge of main 9b0b8d6d25f9e3fb8f71770500e774170423315e.

CI note: the original head's validate-macos failed only on tests.test_credential_run.InjectionTests.test_strips_other_inventory_names_from_the_child, historical run 36667219887, artifact full-suite-macos.log (8,455 tests, one failure). The required checks are validate, validate-macos, token-report, secret-scan, dependency-review, osv-scanner, verdict-review-gate and sota-sources. On head 622b1d16, seven had passed by 12:20:38Z: validate, secret-scan, verdict-review-gate and sota-sources (run 37120987477), token-report (run 37120987458), dependency-review (run 37120987512) and osv-scanner (run 37120987571). validate-macos (run 37120987495) was still queued at 12:35:13Z. The independent read-only Claude Opus review of head 622b1d16, its record and this description returned "repair"; the Review round section gives each finding's disposition. If a fresh macOS run has only failures unrelated to this record, the contract permits one failed-job rerun, with both run IDs retained. A second failure or any failure touching docs/decisions/ stops the landing.

Residuals:

• Private project labels remain in this branch's public history: in the record in the trees of 40631789d2, 0700299c and 1edd0efe7, in the message body of 40631789d2, and in the description's edit history. A squash merge keeps them out of main's tree. It keeps them out of main's commit message only if the merge supplies an explicit clean subject and body, because this repository's squash default copies every PR commit message into the squash commit. The merge plan under Review round supplies both.
• The randomized-fragment flake in tests/test_credential_run.py belongs to the key-management lane.

Review round (2026-10-03)

An independent read-only Claude Opus review of head 622b1d16850e68d68c2bf5943fcc3edc8730065a, its record and this description returned "repair": one blocking finding and four minor ones. This round changes only the description. The record and head are unchanged, so there is no new commit and nothing to re-register in manifests/evidence.json; the push printed Everything up-to-date.

Sources read for finding 1:

• Repository settings, gh api repos/seathatflowsinourveins/native-agent-stack: allow_squash_merge true, merge commits and rebase merges off, squash_merge_commit_title COMMIT_OR_PR_TITLE, squash_merge_commit_message COMMIT_MESSAGES.
• Ruleset 23739774 on refs/heads/main: non_fast_forward, required_linear_history, allowed_merge_methods ["squash"], required_review_thread_resolution true and strict_required_status_checks_policy false. GitHub's rules API reference defines the last as "Whether pull requests targeting a matching branch must be tested with the latest code", so the branch need not take in main 4ced29230 before the merge.
• Main's squash commits 9b0b8d6d2 (Track GPT runtime workers, SDKs, the gateway and pi in the daily catalog-freshness report #634) and d2777ee76 (Keep the root directory as one PATH component; refuse a host HOME of /; six anti-pattern log rows #619) list each PR commit in the body as * <subject> followed by that commit's body.
• gh pr merge --help (gh 2.101.0) lists -t, --subject, -F, --body-file and --match-head-commit.
• record_sanitizer.assert_clean on this PR's four commit messages: only 40631789d2 fails ("still holds a private project label"); 0700299c7, 1edd0efe7 and 622b1d168 are clean. On the record in each commit's tree, 40631789d2, 0700299c7 and 1edd0efe7 fail and 622b1d16 is clean.

Merge plan, replacing the bare squash command in the work contract. Run it only after every required check passes on the final head and every thread is resolved:

1. Write the squash body below to a file outside the checkout, run assert_clean on its text as "squash body", and expect clean.
2. gh pr merge 522 --squash --match-head-commit <final head SHA> --subject 'Retire the Polaris WSL distro: decision record (2026-09-29) (#522)' --body-file <that file>
3. Beside acceptance check 9: run git fetch origin main, read the squash commit's SHA from gh pr view 522 --json mergeCommit --jq .mergeCommit.oid, then run this without a pipe and expect clean: python3 -B -c 'import subprocess, sys; sys.path.insert(0, "evidence/artifacts/terminal-lane-cross-family-review-20260930"); import record_sanitizer as s; s.assert_clean(subprocess.run(["git", "log", "-1", "--format=%B", sys.argv[1]], capture_output=True, text=True, check=True).stdout, "squash message"); print("clean")' <squash commit SHA>

Proposed squash body. assert_clean printed clean for it (exit 0) before this description was published. Its two trailers are the ones on this PR's commits 40631789d2 and 622b1d168.

Adds docs/decisions/2026-09-29-retire-polaris.md, the dated decision record for retiring the Polaris WSL distro on 2026-09-29, following the 2026-09-25 Vela/VelaNext procedure. Custody session native-agent-stack-0c replaced the private project labels with role descriptions, dated the post-unregister state to 2026-09-29 and shortened the credential inventory (R1-R3).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

Commands run in this round from the custody worktree at head 622b1d16, with a private TMPDIR (validate.py, validate_convergence.py and the unit tests at nice 19). Each exit code was read directly, never through a pipe.

$ python3 -B -c 'import subprocess, sys; sys.path.insert(0, "evidence/artifacts/terminal-lane-cross-family-review-20260930"); import record_sanitizer as s; s.assert_clean(subprocess.run(["git", "show", "622b1d16850e68d68c2bf5943fcc3edc8730065a:docs/decisions/2026-09-29-retire-polaris.md"], capture_output=True, text=True, check=True).stdout, "record"); print("clean")'
clean
exit 0
Acceptance check 2 on the committed head. Evidence class: local_integration

$ gh pr view 522 --json body --jq .body > <file>
$ python3 -B -c 'import sys; sys.path.insert(0, "evidence/artifacts/terminal-lane-cross-family-review-20260930"); import record_sanitizer as s; s.assert_clean(open(sys.argv[1], encoding="utf-8").read(), "PR body"); print("clean")' <file>
clean
exit 0
Acceptance check 3 on the description published before this round. The same check printed clean (exit 0) for this revision before publication. Evidence class: local_integration

$ python3 scripts/validate.py
{"components": 69, "hashed_files": 9420, "profiles": 4, "receipts": 187, "status": "passed"}
Integrity and scope checks only; no live provider or GPU execution.
exit 0

$ python3 scripts/validate_convergence.py --all-recorded --root . --json
(JSON summarized) "valid": true; 26 records, none with errors
exit 0

$ git diff --check origin/main...HEAD
(no output)
exit 0

$ python3 -B -m unittest -v tests.test_osv_lockfile_coverage.LockfileInventoryTests.test_every_tracked_lockfile_and_manifest_is_listed tests.test_blind_checkout.RepositoryClassificationTests.test_every_blueprint_value_under_a_label_key_is_classified tests.test_workflow_security_coverage.NewWorkflowSecurityCoverageTests.test_all_published_workflows_are_listed_and_covered
Ran 3 tests in 0.200s
OK
exit 0
The three registry tests from scripts/git-hooks/pre-push

$ git push origin HEAD:claude/retire-polaris-20260929
Everything up-to-date
exit 0

Residuals after this round:

• validate-macos (run 37120987495) has been queued since 11:51:30Z and was still queued at 12:35:13Z. The contract's one-rerun rule and its stop conditions still apply. A rerun is not read-only, so this round did not start one.
• The labels in this branch's public history (Custody, Residuals). The merge plan above keeps them out of main's tree and commit message.
• The coordinator runs the merge plan and updates the work contract to match.
• The original-session facts of finding 4 have no repository source.

Host evidence

Not applicable: no files under evidence/hosts/.

Checklist

• New/changed GitHub Actions are pinned to a full commit SHA with a version comment (none changed).
• New/changed workflows declare top-level permissions: contents: read (none changed).
• No secrets are printed, logged or committed; no new required secret was added without a documented owner.
• No new paid hosting, subscription or billing surface was introduced.
• Peer-owned untracked files and worktrees were preserved (not deleted, moved or overwritten).

🤖 Generated with Claude Code