IBKR paper gateway signs in by itself: stored paper login by pointer, rootless container owner rule in the credential checker, adopted recreate script

[seathatflowsinourveins]

Scope

• What this PR changes, in one or two sentences: the IBKR paper gateway on NativeStack2604 now signs in by itself, by the user's decision of 2026-10-06 (about 01:50Z). The user prefers a passwordless, LLM-native and frictionless workflow and extended that to the IBKR paper login. The command center applied it on the host, and this PR brings the repository in line: the credential policy and inventory, a rootless-container owner rule in the credential checker, the secret guard's pointer list, the adopted recreate script, and a dated decision record. The user is described, not quoted.
• Base commit: ecfa112764c664d35377dd66b8cfcb67e5a94d60 (origin/main when the branch was cut, and still main at this head)
• Lane: lane:shared. It touches trading paths (blueprints/us-equities/runtime-2604/, the trading test tests/test_ibkr_gateway_recreate.py) and foundation paths (docs/, scripts/, adoption/, tests/), and re-registers files in the shared hot file manifests/evidence.json (last commit). The trading lane (5f) must acknowledge before merge; the items it covers are listed under "Acknowledgement requested from the trading lane". The PR stays a draft until then.
• Owned paths touched:
  • adoption/credential-inventory.json
  • adoption/hooks/claude/SHA256SUMS
  • adoption/bootstrap.md
  • adoption/platforms/linux-wsl2-new-distro.md
  • blueprints/us-equities/runtime-2604/README.md
  • blueprints/us-equities/runtime-2604/ibkr-gateway-recreate-durable.sh (new)
  • docs/decisions/2026-10-06-ibkr-paper-passwordless-login.md (new)
  • docs/secret-storage.md
  • scripts/credential_status.py
  • scripts/hooks/secret_path_guard.py
  • tests/test_credential_run.py
  • tests/test_credential_status.py
  • tests/test_credential_tools.py
  • tests/test_ibkr_gateway_recreate.py (new)
  • tests/test_secret_path_guard.py
  • catalogs/foundation/upstream-surface-dispositions.json (five line citations follow the shifted docs/secret-storage.md lines)
  • docs/new-wsl-handbook.md
  • docs/new-wsl-handbook.json
  • evidence/artifacts/new-wsl-handbook-20261001/receipt.json (regenerated; the edited adoption page's digest)
  • manifests/evidence.json (registration only, last commit)

Commits: 80340ee3 (content), bc5064e7 (review fixes for the command center's read at e0c260ca) and b444d148 (registration, last).

What changes

1. docs/secret-storage.md. The ibkr-gateway row (line 28) said the login is typed at sign-in and nothing is stored. It now says the paper login is stored:

   • It sits in three 0600 files with one link each, named by pointer only: IBKR_PAPER_LOGIN_ENV, IBKR_PAPER_TWS_FILE and IBKR_PAPER_VNC_FILE.
   • The two password files are owned by the rootless container user.
   • A weekly second-factor approval on the user's phone keeps it signed in.
   • The row links rotation, and states that live trading stays out of scope.

   A new section, "IBKR paper gateway sign-in (2026-10-06)", covers the rest. The pickup block gains the three pointer exports, and the Checker and Rotation sections are updated.

2. adoption/credential-inventory.json. ibkr-gateway becomes the stored user ID: class broker_login, status optional, a private_file store and pointer IBKR_PAPER_LOGIN_ENV. Two new rows, ibkr-gateway-tws-password and ibkr-gateway-vnc-password, declare rootless_container_uid: 1000. TWS_USERID joins must_not_be_set. Rotation replaces a file (write a new 0600 file, move it over the old one), because the user cannot open the chowned password files. The rule that TWS_* and IBKR_* values never reach workers is kept:

   • no IBKR row is injectable (credential_run.py) or writable (set_credential.py);
   • the runner strips all three pointers from every command it starts;
   • the guard refuses a reader on each pointer and any TWS_USERID reference.

3. scripts/credential_status.py. For a row that declares rootless_container_uid (only the two password files), the owner may be the host uid that rootless Docker maps that container uid to: this user's first /etc/subuid start plus 999 for uid 1000.

   • The start comes from /etc/subuid at run time, parsed as rootlesskit v3.1.0's static source parses it. A missing or malformed file fails closed.
   • Mode 0600 is still required. Every private_file store, the IBKR login env file included, needs exactly one link; a second name is the new finding hard_link.
   • Only /etc/subuid is opened, never a credential file. --subuid PATH serves the test fixtures.

4. blueprints/us-equities/runtime-2604/ibkr-gateway-recreate-durable.sh adopts the command center's host script. The user or an agent runs it from an interactive shell (bash -i); only typing the stored values, once, at the user's private prompt is the user's own step. It keeps the client-connection refusal, the rollback rename and the chown inside the user namespace, and adds:

   • umask 077;
   • refusals for a non-rootless daemon and a record directory inside any Git worktree;
   • every refusal now runs before the first change;
   • the rollback command is printed before the new container starts, so a failed start still shows it.

   It runs the paper account with orders enabled (TRADING_MODE=paper, READ_ONLY_API=no). Its docker inspect records hold the user ID. They go to a new 0700 directory of 0600 files under ${XDG_STATE_HOME:-$HOME/.local/state}/native-agent-stack/ibkr-gateway/, never inside a checkout.

5. scripts/hooks/secret_path_guard.py. The three pointers join POINTER_VARIABLE, as tests/test_secret_path_guard.py:2337-2346 (at ecfa1127) requires for every inventory pointer, and TWS_USERID joins the base SECRET_NAMES. The SHA256SUMS pin moves. The two adoption pages mark it as changed after v2026.10.05.1.

6. docs/decisions/2026-10-06-ibkr-paper-passwordless-login.md records the decision, the upstream sources (with the vendor-organization check), what is stored and where (by pointer), the orders-enabled setting, the weekly second factor, the accepted paper-only risk, the alternatives and what would overturn it.

Pointer-convention finding (no rename, no user item). The question was whether worker_env_check.sh or credential_status.py treats the IBKR_PAPER_* pointer names as forbidden. Line numbers are at base ecfa1127.

• credential_status.py does not. It compares must_not_be_set by exact name (scripts/credential_status.py:550) against TWS_USERNAME, TWS_PASSWORD, TWS_ACCOUNT and IBKR_ACCOUNT_ID (adoption/credential-inventory.json:406).
• worker_env_check.sh records any ^(APCA|ALPACA|TWS|IBKR)_ name as a broker variable (blueprints/gap-wave2-20260923/us-equities__security-supply-chain/worker_env_check.sh lines 24, 49 and 61). That is a names-only measurement with no gate, and it is the recorded command of the gap-wave2 receipts 8 and 14, so it stays unchanged.
• The secret guard's SECRET_NAMES is exact too. Its POINTER_VARIABLE must list every inventory pointer.
• The documented convention in docs/secret-storage.md:
  • lines 33-37 name TWS_* and IBKR_ACCOUNT_ID as the IBKR names that stay unset;
  • lines 281-299 make pointers file paths that the shell startup file exports;
  • lines 71-75 say the runner strips every other entry's pointers.
• The three names match neither unset rule, so they are kept as documented pointer names and the exemption is written into the inventory row and the runbook. No rename, so the user has no ~/.bashrc change.

Acknowledgement requested from the trading lane (5f)

docs/lanes.md:148-150 requires the trading lane's acknowledgement, as a comment or review on this PR, before merge. It should cover:

1. Orders enabled on the paper account. The recreate script starts the gateway with TRADING_MODE=paper and READ_ONLY_API=no (blueprints/us-equities/runtime-2604/ibkr-gateway-recreate-durable.sh), so any API client on 127.0.0.1:4002 can place paper orders from the moment the container starts.
   • The IBKR paper-orders harness needs Read-Only API off (blueprints/us-equities/engine-nautilus/ibkr-paper-orders/README.md L121). Before this, the user unticked it by hand (L246-L249 for 2026-09-23, L345 for 2026-10-05).
   • The 2026-10-05 read-only acceptance ran with READ_ONLY_API=yes (blueprints/us-equities/engine-nautilus/ibkr-acceptance/README.md L15-L16).
   • Now stated in the decision record, the runtime-2604 README and the runbook.
2. The trading test tests/test_ibkr_gateway_recreate.py, which docs/lanes.md:50 classes as a trading test (test_ibkr_*.py).
3. The trading path blueprints/us-equities/runtime-2604/: the adopted script and its README section.

Review round: the command center's read at e0c260ca (ACK_AFTER)

Finding	Fix	Where
P2: CodeQL gate, two high py/clear-text-storage-sensitive-data alerts (#95, #96) on a synthetic fixture	The fake paper-password fixture is renamed (self.password → self.tws_fake), so CodeQL's name heuristic no longer sees a password. No suppression comment, following docs/decisions/2026-09-29-key-management.md:589-598. Verified on b444d148 at 06:08Z: all six CodeQL analyses report 0 results, #95 and #96 are fixed on refs/pull/769/head, and the CodeQL check reads "No new alerts in code changed by this pull request". GitHub resolved both github-advanced-security review threads itself.	tests/test_ibkr_gateway_recreate.py
P2: recreate script documented as user-run	Reworded: the user or an agent runs it from an interactive shell. Typing the stored values once, at the user's private prompt, stays the user's step.	script header; runtime-2604 README; runbook; decision record
P2: trading-lane acknowledgement missing, PR still a draft	Not closable by this worker: the acknowledgement is 5f's, and the coordinator keeps the draft. Prepared: the orders-enabled setting is now written into the decision record, the README and the runbook, and the section above lists what the acknowledgement should cover.	decision record; runtime-2604 README; runbook; this body
P3: inventory rotation says "rewrite" files the user can no longer write	All three rotation strings now say: write a new 0600 file, move it over the old one, rerun the script. The runbook adds a "replace, never edit in place" line.	adoption/credential-inventory.json; runbook
P3: "one link" claimed for three files, checked for two	The hard_link check now covers every private_file store, including the IBKR login env file and the generated host keys. A new test fails against the previous checker (2 subtests) and passes now. Docs updated.	scripts/credential_status.py; tests/test_credential_status.py; runbook Checker section
P3: idtools.go citation L48-L85 runs past the end of the file	Changed to L48-L83 (the file has 83 lines at 62d2101f). The comment now says the checker mirrors rootlesskit's static source only; the auto branch (parent.go L375-L381) asks getsubids first.	scripts/credential_status.py; tests/test_credential_status.py; decision record; this body
P3: decision record does not record the vendor-org check	Added: the InteractiveBrokers GitHub org ships no gateway container or login automation (gh api 'orgs/InteractiveBrokers/repos?per_page=100' on 2026-10-06 returns only tws-api-public, last pushed 2018-01-23).	decision record, SOTA sources
P3: no rollback command printed if the new container fails to start	The script prints the rollback command right after the rename and before docker run -d. The command works with or without a new container. A new test with a failing stub start fails against the previous script and passes now.	script; tests/test_ibkr_gateway_recreate.py; README; runbook; decision record

The five upstream-surface disposition citations follow the shifted docs/secret-storage.md lines (now 1799, 1801 and 1812).

SOTA sources

• gnzsnz/ib-gateway-docker at 8a22deaa6cab86f9ad5c86ff4f0d6efbef718f10, which is tag ibgateway-latest@10.51.1b (gh api repos/gnzsnz/ib-gateway-docker/git/matching-refs/tags/ibgateway-latest@10.51):
  • README "Configuration" table, L175-L203: TWS_USERID L181, TWS_PASSWORD_FILE L183, VNC_SERVER_PASSWORD_FILE L190, TWOFA_TIMEOUT_ACTION L191, AUTO_RESTART_TIME L195, RELOGIN_AFTER_TWOFA_TIMEOUT L199, EXISTING_SESSION_DETECTED_ACTION L200 and TWS_SETTINGS_PATH L203.
  • README "Credentials", L511-L545: the _FILE form.
  • latest/Dockerfile: IBC_VERSION=3.24.2 at L13 and USER_ID 1000 at L67.
• Vendor organization first. The InteractiveBrokers GitHub organization ships no gateway container and no login automation: only InteractiveBrokers/tws-api-public, last pushed 2018-01-23 (gh api 'orgs/InteractiveBrokers/repos?per_page=100', 2026-10-06). gnzsnz/ib-gateway-docker with IBC fills that gap.
• IbcAlpha/IBC 3.24.2 at 2be2ecd05d7707f97479fda9ad098fdcc15ab807:
  • userguide.md L586-L601: AutoRestart restarts without re-authentication, giving "a single authentication at the start of the week", and the session expires on Sunday.
  • L508-L551: second-factor authentication.
• rootless-containers/rootlesskit v3.1.0 at 62d2101fbbe4f79bc845a337c4e868d27ff602c9. This host's rootless Docker Engine 29.8.2 reports rootlesskit 3.1.0.
  • pkg/parent/parent.go L401-L432: container uid 0 maps to the user, and the subordinate ranges follow from container uid 1.
  • L363-L385: the subid source; L375-L381 is the default auto branch, which asks getsubids first.
  • pkg/parent/idtools/idtools.go L48-L83: the static /etc/subuid parser, which the checker mirrors.
• ShellCheck 0.11.0, from PyPI shellcheck-py, run through uvx with a scratch-only cache: no findings in the adopted script. The command center's original exits 1 under the same check.
• Repository precedents:
  • #481 (c26800f3) added a pointer to POINTER_VARIABLE together with its inventory row, and moved the SHA256SUMS pin.
  • docs/decisions/2026-09-29-key-management.md:589-598 renamed a CodeQL-flagged fixture variable without a suppression comment.

Evidence-class table

Claim	Evidence class	Command / receipt
After the cold boot, the gateway signed in by itself at 02:25:37Z on 2026-10-06	reported by the command center; not observed again for this PR	the command center's handover
On NativeStack2604 at 06:04:50Z (head of the review fixes, before registration), ibkr-gateway is ok, ibkr-gateway-tws-password and ibkr-gateway-vnc-password are ok with owner=rootless_container_user, all three with one link; result ok, values_read: false. At base the three files were undeclared store files and the IBKR row was not_local	host execution on NativeStack2604; no receipt retained, so not native_proven	python3 scripts/credential_status.py --json → exit 0
The mapped owner is accepted only for the two declared rows; any other owner, a mode other than 0600, or a second link is refused; every private_file row needs one link; no credential file is opened	synthetic	python3 -m unittest tests.test_credential_status
The recreate script refuses before any change (worktree record directory, rootful daemon, missing ss, connected client, empty pointer target), keeps the rollback rename and the namespace chown, prints the rollback before the new start, and writes its records 0600	synthetic (stub docker, ss and sleep; the real daemon is never reached)	python3 -m unittest tests.test_ibkr_gateway_recreate
A reader on each pointer and a TWS_USERID reference are refused; docker loaders, stat and wc pass; bare docker reads are recorded pass-throughs; still a superset of the pinned baselines	local_integration	python3 -m unittest tests.test_secret_path_guard: 89 of 90 pass. The one failure compares this host's installed guard and is skipped in CI
No IBKR row is injectable or writable; every inventory pointer, the IBKR three included, is stripped from injected commands	local_integration	python3 -m unittest tests.test_credential_run tests.test_credential_tools

Local commands run

All commands ran on NativeStack2604 in the owned worktree. The head is b444d148.

This round, on the review fixes (bc5064e7) and their registration:

$ python3 scripts/validate.py
exit 0: {"components": 69, "hashed_files": 10275, "profiles": 4, "receipts": 212, "status": "passed"}
$ git diff --check origin/main...HEAD
exit 0
$ python3 scripts/build_new_wsl_handbook.py --check
exit 0
$ python3 scripts/catalog_decisions.py --check
exit 0
$ python3 scripts/component_matrix.py --write; python3 scripts/new_host_grand_list.py --write
exit 0, exit 0: both reports unchanged
$ python3 -m unittest tests.test_credential_status
exit 0: 53 tests OK (1 new: every private_file row needs one link; fails against the previous checker with 2 subtest failures)
$ python3 -m unittest tests.test_ibkr_gateway_recreate
exit 0: 7 tests OK (1 new: a failed start still shows the rollback; errors against the previous script)
$ python3 -m unittest tests.test_credential_run
exit 0: 92 tests OK
$ python3 -m unittest tests.test_credential_tools
exit 0: 34 tests OK
$ python3 -m unittest tests.test_upstream_surface_watch
exit 0: 114 tests OK (6 skipped)
$ python3 -m unittest tests.test_canary_proof
exit 0: 143 tests OK (134 skipped on this host)
$ python3 -m unittest tests.test_credential_boot_receipt
exit 0: 21 tests OK
$ python3 -m unittest tests.test_runtime_worker_openhands_push_gate
exit 0: 122 tests OK
$ python3 -m unittest tests.test_runtime_worker_openhands_resolver
exit 0: 138 tests OK (1 skipped)
$ python3 -m unittest tests.test_adoption_docs_consistency
exit 0: 39 tests OK (1 skipped)
$ python3 -m unittest tests.test_practice_references tests.test_landscape tests.test_foundation_catalog tests.test_component_matrix tests.test_gap_crosswalk tests.test_catalog_freshness_trading
exit 0 each: 32, 95, 19, 63, 8 and 49 tests OK
$ python3 -m unittest tests.test_ibkr_paper_orders
exit 0: 79 tests OK (13 skipped)
$ python3 -m unittest tests.test_new_wsl_handbook
exit 0: 76 tests OK
$ python3 -m unittest tests.test_secret_path_guard
exit 1: 90 tests, 1 failure (2 skipped), test_host_profile_copy_is_verbatim.
  It compares this host's installed user-scope guard, still the base pin fd516d8b, with the changed guard.
  CI skips this test, and it passes after the guard reinstall listed below.
$ bash -n blueprints/us-equities/runtime-2604/ibkr-gateway-recreate-durable.sh
exit 0
$ uvx --from shellcheck-py shellcheck -x -s bash blueprints/us-equities/runtime-2604/ibkr-gateway-recreate-durable.sh
exit 0: ShellCheck 0.11.0, run with a scratch-only uv cache; no findings
$ python3 scripts/credential_status.py --json   # 2026-10-06T06:04:50Z
exit 0: all three IBKR rows ok, the two password files owner=rootless_container_user; result ok; values_read false

Earlier rounds.

• The full suite ran on bf1d143c (1516 s): exit 1, with 10357 tests, failures=12, errors=18 and skipped=903.
  • 29 of the 30 failing tests fail the same way at base ecfa1127 on this host. I re-ran each failing module in a detached base worktree:
    • 18 errors: exchange_calendars is not installed here (16 adaptive-paper and trading modules, plus 2 test_ingest_snapshot tests);
    • the test_adoption_launchd, test_adoption_bootstrap, test_adoption_guarded_runners and test_windows_terminal_defaults failures;
    • five test_adaptive_paper_credential_race failures;
    • a cross-device git clone --local in test_token_e2e_grader.
  • The 30th is the host-guard comparison above.
• CI's validate on e0c260ca succeeded (check run 112109930442, 05:05:37Z). The command center's read reports that its suite ran 11361 tests, OK with 1026 skipped.
• Failed attempts, retained, all fixed in 80340ee3:
  • validate.py exited 1 on a literal home path in the script.
  • test_adoption_docs_consistency exited 1 twice: first a missing "changed after" marker, then a link to the decision record before it existed.
  • The first full suite caught two regressions: five shifted disposition citations and the stale new-WSL handbook digest.

CI that this PR does not cause. The required osv-scanner check fails repo-wide on new advisories in lockfiles that this PR does not touch:

• mako 1.4.1
• fsspec 2025.9.0
• multidict 6.7.0
• werkzeug 3.1.8
• source-map-js 1.2.1

Main needs a fix, and this PR then needs a new head.

Decision record

docs/decisions/2026-10-06-ibkr-paper-passwordless-login.md names the evidence, the alternatives (typing at each sign-in, a TWS_PASSWORD environment value, Compose secrets, the kernel keyring, renaming the pointers) and what would overturn it.

Host evidence

Not applicable: no file under evidence/hosts/ changes.

• python3 scripts/host_receipts.py validate passes for every new/changed receipt. (No receipt changes.)
• Independent review is recorded (scripts/host_receipts.py review) or explicitly requested in this PR. (No receipt changes.)
• No platform_status change is made from a host receipt alone.

Items for the coordinator and the user

• User: none. The pointers keep their names, so ~/.bashrc needs no change.
• Trading lane (5f): acknowledge on this PR, covering the three items under "Acknowledgement requested from the trading lane". Then the PR can leave draft.
• Coordinator, before merge: get osv-scanner fixed on main, then give this PR a new head through the hot-file protocol.
• Coordinator, after merge: reinstall the user-scope guard on NativeStack2604 with python3 tools/adoption/install_claude_profile.py --only guard from the merged checkout.
  • Until then, the host's frozen guard (fd516d8b) does not refuse readers on the three pointers.
  • credential_status.py --client-guards and the boot receipt report claude_user_guard_matches_pin=false, and the local test_host_profile_copy_is_verbatim fails. CI skips that test.
• Coordinator: write the report and ack ledger rows.
• Follow-ups, not in this PR:
  • adopt the two private-prompt scripts that wrote the files, so rotation is reproducible on a new host;
  • add a receipt file for the host check above.

Checklist

• New/changed GitHub Actions are pinned to a full commit SHA with a version comment (no floating tags). (No workflow changes.)
• New/changed workflows declare top-level permissions: {} and grant each job only what it needs (contents: read, or an explicitly justified addition). (No workflow changes.)
• No secrets are printed, logged or committed; no new required secret was added without a documented owner. No credential value was read: the host check uses lstat and /etc/subuid only, and the command center's inspect records were never opened.
• 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

[seathatflowsinourveins]

Trading-lane acknowledgement (lane:shared), for the trading path at e0c260c

The trading lane acknowledges these changes:

• blueprints/us-equities/runtime-2604/README.md (+29)
• blueprints/us-equities/runtime-2604/ibkr-gateway-recreate-durable.sh
• tests/test_ibkr_gateway_recreate.py

Checked against the trading lane's paper rules:

• Paper only. TRADING_MODE=paper is fixed in the script (:104). No live mode, endpoint or key path is added.
• Pinned image. It is digest-pinned to the image of the 2026-10-05 IBKR acceptance receipt (:27).
• Loopback ports. Both are published on 127.0.0.1 only: 4002 to the container's 4004, and VNC 5900 (:99).
• Orders enabled. READ_ONLY_API=no matches the qualified rc5 order path.
• Restart outside paper sessions. The nightly restart at 11:00 PM ET (:31) falls after every paper session; the latest unit ends about 8:05 PM ET.
• No disruption of a live client. It refuses while an API client is connected to 127.0.0.1:4002 (:71-75).
• Rollback. The old container is kept stopped for rollback.

P2 (trading): add a host guard that refuses unless WSL_DISTRO_NAME is the distro that owns the paper gateway. The same container name exists, stopped, on the other distro, and it must stay stopped. Run there, the script would start a second gateway on the same paper user. With EXISTING_SESSION_DETECTED_ACTION=primary (:107), that gateway would take over the session from the 2604 gateway. Today nothing but the README wording prevents that. This does not block the acknowledgement.

The acknowledgement covers this head only. A later head needs a new look at the trading path.

[seathatflowsinourveins]

Trading-lane acknowledgement (lane:shared), at b444d14 and at 17a06de

17a06de changes nothing on the trading path. git diff b444d148 17a06de05 over blueprints/us-equities/ and tests/test_ibkr_gateway_recreate.py is empty; that head only refreshes the evidence registry.

What changed on the trading path since my acknowledgement at e0c260c:

• The script's wording now says the user or an agent runs it, and only typing the stored values is the user's step.
• The rollback is printed before the new container starts. It also tolerates a container that was never created or never started.
• The tests are updated to match.

The paper-only properties still hold at this head:

• TRADING_MODE=paper (:109);
• the digest-pinned image of the 2026-10-05 acceptance receipt (:28);
• ports on 127.0.0.1 only (:104);
• the nightly restart at 11:00 PM ET, outside every paper session (:32);
• refusal while an API client is connected to 127.0.0.1:4002 (:72-76).

Residual (P2, non-blocking, unchanged): nothing in the script refuses outside the distro that owns the paper gateway. The same container name sits stopped on the other distro, and with EXISTING_SESSION_DETECTED_ACTION=primary (:112), a second gateway started there would take over the 2604 session. The trading lane records this residual for a follow-up.

This acknowledgement covers the trading path at these two heads only.