py-ib-controller 0.1.4__tar.gz → 0.1.5__tar.gz

{py_ib_controller-0.1.4 → py_ib_controller-0.1.5}/.github/workflows/ci.yml

@@ -40,8 +40,11 @@ jobs:
       - name: Build Java agent jar
         run: make build
 
+      - name: Test Java agent
+        run: make test-java
+
       - name: Test
-        run: uv run pytest
+        run: uv run pytest -n auto
 
       - name: Build
         run: uv build

{py_ib_controller-0.1.4 → py_ib_controller-0.1.5}/Makefile

@@ -19,6 +19,21 @@ build/ibcontroller-agent.jar: $(SRC)
 .PHONY: build
 build: build/ibcontroller-agent.jar
 
+# Dependency-free Java unit tests (plain javac + java, same toolchain as the jar).
+TEST_SRC := $(wildcard agent/src/test/java/ibcontroller/agent/*.java)
+
+.PHONY: test-java
+test-java: $(SRC) $(TEST_SRC)
+	mkdir -p build/test-classes
+	$(JAVAC) -d build/test-classes $(SRC) $(TEST_SRC)
+	$(JDK)/bin/java -Djava.awt.headless=true -cp build/test-classes ibcontroller.agent.AgentTests
+
+# Everything: build the jar, run the Java unit tests, then the Python suite (which
+# includes the tests that drive the built jar).
+.PHONY: test
+test: build test-java
+	uv run pytest -n auto
+
 # The Python package can't be built standalone -- `ibcontroller/ibcontroller-agent.jar`
 # must exist before `uv build` runs, since it's shipped via [tool.setuptools.package-data]
 # the same way ibcontroller/data/*.json is (see pyproject.toml). This target makes that

{py_ib_controller-0.1.4 → py_ib_controller-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-ib-controller
-Version: 0.1.4
+Version: 0.1.5
 Summary: Login/launch controller for TWS and IBKR Gateway, via an in-process Java agent
 Author-email: gnzsnz <8376642+gnzsnz@users.noreply.github.com>
 License-Expression: Apache-2.0
@@ -125,7 +125,7 @@ And the `ibcontroller run` parameters:
 │ --trading-mode             <live|paper>  Override Config.trading_mode ('live'/'paper') for this invocation.                                                                     │
 │ --tws-path                 <path>        Override Config.tws_path (the TWS/Gateway install-path inference) for this invocation.                                                 │
 │ --tws-channel              <str>         Override Config.tws_channel ('stable'/'latest', filters install auto-detection) for this invocation.                                   │
-│ --program                  <str>         Override Config.program ('gateway'/'tws') for this invocation.                                                                         │
+│ --program                  <gateway|tws> Override Config.program ('gateway'/'tws') for this invocation.                                                                         │
 │ --tws-settings-path        <path>        Override Config.tws_settings_path (where TWS/Gateway stores its own settings) for this invocation.                                     │
 │ --instance                 <str>         Override Config.instance (per-instance log/trace/socket names) for this invocation. Defaults to '{program}-{trading_mode}', so         │
 │                                          --trading-mode alone is usually enough to keep paper/live instances apart.                                                             │
@@ -197,7 +197,7 @@ When environment variable `IBC_APP_DIR` is not set, then
 | --- | --- | --- |
 | `config_dir` | `~/.config/ibcontroller` | Linux |
 | `config_dir` | `~/Library/Application Support/ibcontroller` | macOS |
-| `log_dir` | `~/.local/share/ibcontroller` | Linux |
+| `log_dir` | `~/.local/state/ibcontroller/log` | Linux |
 | `log_dir` | `~/Library/Logs/ibcontroller` | macOS |
 | `socket_dir` | `/run/user/<uid>/ibcontroller` | Linux |
 | `socket_dir` | `~/Library/Caches/TemporaryItems/ibcontroller` | macOS |
@@ -208,6 +208,13 @@ When `IBC_APP_DIR` is set then:
 - `log_dir`-> `IBC_APP_DIR/log`
 - `socket_dir` -> `IBC_APP_DIR/run`
 
+Socket paths (`socket_dir/ibcontroller-agent-<instance>-events.sock`) must fit
+the Unix socket limit: 102 bytes on macOS, 106 on Linux. On macOS the default
+`socket_dir` leaves room for an instance name of about 15 characters with a
+5-letter user name (each extra user-name character costs one). Over the limit,
+`ibcontroller run` stops with an error naming the path; use a shorter instance
+name or set `IBC_APP_DIR` to a shorter directory.
+
 ### Settings
 
 `ibcontroller`ships with sensible defaults.  **Only the two credential env vars below are actually mandatory**
@@ -223,7 +230,7 @@ allowing `None`. `Config`'s schema is closed — an unknown key in
 | TOML key | Env var or CLI flag | Description | Default |
 | --- | --- | --- | --- |
 | `instance` | `IBC_INSTANCE`, `--instance` | Instance name; separate log/trace files per instance | `"{program}-{trading_mode}"` (e.g. `"gateway-paper"`) |
-| `program` | `IBC_PROGRAM`, `--program` | `"gateway"` or `"tws"` | `"gateway"` |
+| `program` | `IBC_PROGRAM`, `--program` | `"gateway"` or `"tws"` (any letter case); anything else is a config error | `"gateway"` |
 | `tws_version` | `IBC_TWS_VERSION` | Installed TWS/Gateway version, e.g. `"10.50"` | `None` — auto-detected (see below) |
 | `tws_channel` | `IBC_TWS_CHANNEL`, `--tws-channel` | `"stable"`/`"latest"`; narrows auto-detection to one update channel | `"stable"` |
 | `tws_path` | `IBC_TWS_PATH`, `--tws-path` | Override TWS/gateway install-path inference | `None` |
@@ -237,6 +244,7 @@ allowing `None`. `Config`'s schema is closed — an unknown key in
 | `log_backup_count` | `IBC_LOG_BACKUP_COUNT` | Number of rotated backups to keep. Only respected when `log_sink="file"` | `5` |
 | `diagnostic_scope` | `IBC_DIAGNOSTIC_SCOPE` | `"known"`/`"unknown"`/`"all"` — which windows get a structure dump logged (see `docs/Configuration.md`'s "Diagnostics") | `"known"` |
 | `diagnostic_when` | `IBC_DIAGNOSTIC_WHEN` | `"open"`/`"openclose"`/`"never"` — when to log a structure dump | `"never"` |
+| `diagnostic_settings_sweep` | `IBC_DIAGNOSTIC_SETTINGS_SWEEP` | Log a dump of each Global Configuration tree node in `labels.settings.sweep_paths` (see `docs/Configuration.md`'s "Diagnostics") | `false` |
 | (env only) | `IBC_APP_DIR`, `--app-dir` | Override file locations (config/log/run) for container mode; `--app-dir`/`init`/`run` set the env var for the invocation, same effect |
 
 TWS/ibgateway settings
@@ -244,15 +252,16 @@ TWS/ibgateway settings
 | TOML key | Env var or CLI flag | Description | Default |
 | --- | --- | --- | --- |
 | `trading_mode` | `IBC_TRADING_MODE`, `--trading-mode` | `"live"` or `"paper"`; which account to authenticate as | `"paper"` |
-| `read_only_login` | `IBC_READ_ONLY_LOGIN` | TWS-only; **not yet wired to any behavior** (loaded, unused — see TODO.md) | `false` |
+| `read_only_login` | `IBC_READ_ONLY_LOGIN` | TWS-only (Gateway warns and logs in normally); clicks "Enter Read Only" on the 2FA frame instead of waiting for the push, no effect without 2FA (paper) | `false` |
 | `read_only_api` | `IBC_READ_ONLY_API` | `true`/`false` sets it; omit to leave unchanged. Applied to Gateway/TWS automatically -- see "Declarative configuration" below | `None` |
 | `accept_incoming_connections` | `IBC_ACCEPT_INCOMING_CONNECTIONS` | `manual`/`accept`/`reject` | `"manual"` |
 | `existing_session_action` | `IBC_EXISTING_SESSION_ACTION` | `manual`/`primary`/`primaryoverride`/`secondary` | `"manual"` |
 | `login_dialog_display_timeout` | `IBC_LOGIN_DIALOG_DISPLAY_TIMEOUT` | Seconds to wait for the login dialog | `60.0` |
-| `mfa_timeout` | `IBC_MFA_TIMEOUT` | IB's 2FA timeout in seconds | `180.0` |
-| `relogin_after_mfa_timeout` | `IBC_RELOGIN_AFTER_MFA_TIMEOUT` | Restart login if 2FA times out | `false` |
-| `mfa_exit_interval` | `IBC_MFA_EXIT_INTERVAL` | Bounds the post-2FA wait when relogin enabled | `60.0` |
-| `mfa_timeout_action` | `IBC_MFA_TIMEOUT_ACTION` | `exit` (exit 75, see "Exit codes" above) or `restart` (relaunch with a fresh login) when the 2FA push goes unanswered until `mfa_timeout` or `mfa_exit_interval` fires | `"exit"` |
+| `mfa_timeout` | `IBC_MFA_TIMEOUT` | IB's 2FA limit in seconds; a dialog closing at or after it counts as timed out | `180.0` |
+| `relogin_after_mfa_timeout` | `IBC_RELOGIN_AFTER_MFA_TIMEOUT` | Log in again after a timed-out push, and enforce `mfa_exit_interval` after an approved one | `false` |
+| `mfa_exit_interval` | `IBC_MFA_EXIT_INTERVAL` | Post-approval wait for login to complete when relogin is on | `60.0` |
+| `mfa_timeout_action` | `IBC_MFA_TIMEOUT_ACTION` | `exit` (exit 75, see "Exit codes" above) or `restart` (relaunch with a fresh login) when `mfa_exit_interval` expires after an approved push | `"exit"` |
+| `restart_cap` | `IBC_RESTART_CAP` | Max consecutive relaunches that never reach READY (login frame timeout, transient login failure, logout, crash during login); then exit 70 | `3` |
 | `auto_restart_time` | `IBC_AUTO_RESTART_TIME` | `"hh:mm AM/PM"` daily auto-restart time. Applied to Gateway/TWS automatically -- see "Declarative configuration" below | `None` |
 | `auto_logoff_time` | `IBC_AUTO_LOGOFF_TIME` | `"hh:mm AM/PM"` daily auto-logoff time; same "Lock and Exit" radio-button pair as `auto_restart_time` -- if both are set, `auto_restart_time` wins | `None` |
 | `time_zone` | `IBC_TIME_ZONE` | IANA zone name, e.g. `"Europe/Zurich"`, written to `jts.ini`'s `TimeZone`. Auto-detected from `TZ`, then `/etc/localtime` -- no setup needed in the common case; never overwrites an existing `TimeZone` line | auto-detected |
@@ -313,10 +322,19 @@ more fields of the bundled default, field by field — you only need to include
 you're changing, not the whole file. Use it when a TWS/Gateway release renames a button
 or dialog title ibcontroller matches against.
 
+A malformed file is rejected at startup (exit code 78) with a message naming the file and
+the field: a string where a list is expected, an empty list of titles or buttons, invalid
+JSON, or a `dismiss_rules` entry without `match_title`/`match_text`. A misspelled key is
+logged as a warning and ignored, so check the log if an override seems to have no effect.
+
+`generic.dismiss_buttons` lists the buttons tried, in order, to close a pop-up no specific
+handler recognises (default `OK`, `Close`, `Dismiss`).
+
 The one part of `labels.json` that isn't just text is `dismiss_rules` — a list of
 "if a window matches, click this button" entries, checked on every window that opens.
 Each entry needs at least one of `match_title`/`match_text` (both, if given, must
-match); `click` is the button's label.
+match); `click` is the button's label. `match_text` also matches message text with HTML
+tags removed and entities decoded, so copy the phrase as it shows on screen.
 
 ```json
 {
@@ -330,13 +348,18 @@ match); `click` is the button's label.
 }
 ```
 
-`dismiss_rules` is a list, not a map — an override *replaces the whole list*, so if you
-want to keep the bundled entries (the non-brokerage-account warning, the auto-restart
-confirmation notice) alongside your own, copy them into your override file too rather
-than starting from an empty list. Good for any pop-up that's always handled the same
+`dismiss_rules` entries are merged by `name`: an entry with a bundled rule's name replaces
+that rule, an entry with a new name is added, and bundled rules (the non-brokerage-account
+warning, the auto-restart confirmation notice) you don't name are kept. Removing a bundled
+rule is not supported. Good for any pop-up that's always handled the same
 simple way; a dialog needing real logic (parsing a value out of its text, retrying,
 raising an error) isn't expressible this way and needs actual code.
 
+Login-outcome dialogs ("Login failed", "Unrecognized Username or Password", the connection
+and too-many-attempts warnings) and the "Shutdown progress" / "Restart in progress" windows
+are always handled first. A `dismiss_rules` entry that matches one of them never runs, so a
+credential rejection still exits with code 77 and a restart is still recognised as one.
+
 ### `ibkr_settings.toml` — Global Configuration settings
 
 Global Configuration settings (the "Configure" / "Settings" dialog inside Gateway/TWS)
@@ -351,7 +374,13 @@ are applied once, right after login, from two layers combined into one list:
 - **Your own `ibkr_settings.toml`** — anything else: any other Global Configuration
   checkbox or text field, activated by pointing `[settings] file = "..."` (or
   `IBC_SETTINGS_FILE`) at a real file (rename `ibkr_settings.toml.example` to
-  start from the bundled worked examples, e.g. the `api_precautions_*` toggles).
+  start from the bundled worked examples: the `api_precautions_*` toggles, plus commented
+  entries for the API socket port, the master API client ID and "Send market data in lots
+  for US stocks" under `API/Settings`).
+
+When no entry resolves to a value (the default), the dialog is not opened. Only the TWS Mosaic
+layout is supported: on TWS Classic no setting is applied and the attempt waits for
+`mfa_timeout` (default 180s) before failing. Gateway is not affected.
 
 An entry looks like this:
 
@@ -504,6 +533,42 @@ or both.
   instances (e.g. `paper` and `live`) can run in parallel and each tail its own files
   without interleaving, even if copied or globbed out of their directory.
 
+## Finding the TWS / Gateway installation
+
+ibcontroller does not install anything: it launches the TWS or Gateway you already
+installed with IBKR's own installer, using that install's jars and bundled JRE. It
+resolves the installation in three steps.
+
+1. **Install root** (`tws_path`). Unless set, it defaults to:
+
+   | OS | Default root |
+   | --- | --- |
+   | macOS | `~/Applications` |
+   | Linux | `~/Jts` |
+
+2. **Version** (`tws_version`). A pinned `tws_version` is used as-is. Otherwise
+   ibcontroller scans the root, picks the greatest installed version and logs the
+   choice; `tws_channel` narrows the scan first. See "`tws_version` auto-detection"
+   above.
+
+3. **Install directory.** Version and `program` select the directory below the root:
+
+   | OS | Gateway | TWS |
+   | --- | --- | --- |
+   | macOS | `IB Gateway <version>/` | `Trader Workstation <version>/` |
+   | Linux | `ibgateway/<version>/` | `<version>/` |
+
+   A directory counts as an installation only if it has a `jars/` subfolder. The
+   classpath is built from those jars plus the install's `.install4j/i4jruntime.jar`,
+   and the JVM options come from its `ibgateway.vmoptions` / `tws.vmoptions`.
+
+If nothing matches, ibcontroller exits with an error naming `tws_path` and
+`tws_channel`. A `program = "tws"` request with no TWS install falls back to a
+Gateway install; the reverse does not (details above).
+
+Settings (`tws_settings_path`) are separate from the install root: each instance
+defaults to its own `~/Jts/<instance>`, so `paper` and `live` do not share state.
+
 ## Exit codes
 
 `ibcontroller run` exits with a [BSD sysexits](https://man.freebsd.org/cgi/man.cgi?query=sysexits)
@@ -513,22 +578,34 @@ code, grouped by what a supervisor (a container's `restart:` policy, systemd's
 
 | Code | Meaning | Supervisor action |
 | --- | --- | --- |
-| `0` | Intentional stop (Ctrl-C, `closedown_at`, Gateway/TWS closed normally, e.g. File>Close) | Do not restart |
+| `0` | Intentional stop (Ctrl-C, `closedown_at`, Gateway/TWS closed normally, e.g. File>Close, or this session yielded to another via `existing_session_action`: `stopped: SESSION_CEDED`) | Do not restart |
 | `1` | Unhandled exception (a bug) | Restart, report |
 | `2` | CLI usage error | Fix the command |
 | `78` (`EX_CONFIG`) | Deployment error (bad config, install not found) | Do not retry |
 | `77` (`EX_NOPERM`) | Credentials rejected | Do not retry (lockout risk) |
-| `75` (`EX_TEMPFAIL`) | 2FA not approved in time, `mfa_timeout_action=exit` | Retry per policy |
-| `69` (`EX_UNAVAILABLE`) | Transient runtime failure (process crashed or killed, connection lost, JVM exited before becoming ready, login timed out with no 2FA dialog) | Retry |
+| `76` (`EX_PROTOCOL`) | A dialog `existing_session_action` rules out (Trading Login Handoff with `secondary`/`primaryoverride`) | Do not retry |
+| `75` (`EX_TEMPFAIL`) | Login did not complete after 2FA, `mfa_timeout_action=exit` | Retry per policy |
+| `70` (`EX_SOFTWARE`) | `restart_cap` consecutive relaunches never reached READY | Do not retry |
+| `69` (`EX_UNAVAILABLE`) | Transient runtime failure (process crashed or killed, connection lost, JVM exited before becoming ready) | Retry |
 
-`77`/`78` work with systemd's `RestartPreventExitStatus=`.
+`70`/`76`/`77`/`78` work with systemd's `RestartPreventExitStatus=`.
 
 Some login-blocking dialogs IB reports as a server-side condition -- not a credential
-rejection -- never reach this table at all: a "Login failed"/"Login Error" dialog, or a
+rejection -- never reach this table at all: a "Login failed"/"Login Error"/"not currently available" dialog, or a
 Gateway "Connection to server failed" reason other than a known credential/account one
 (e.g. a stale restart token), make ibcontroller relaunch in-process with a full fresh
-login, unbounded, the same way a scheduled `cold_restart_time` does -- the container
-itself never exits or restarts for these.
+login, the same way a scheduled `cold_restart_time` does -- the container
+itself does not exit for these, until `restart_cap` consecutive relaunches never reach READY
+(exit 70).
+
+## Stopping under Docker
+
+On SIGTERM (`docker stop`, Ctrl-C) a logged-in instance closes through File > Exit/Close so
+TWS/Gateway can save its session and upload settings. Measured over 88 shutdowns: mean 1.3 s,
+p99 4.3 s, max 4.9 s. A slow path (a dialog open, a stuck menu) can take longer: the menu retry
+waits up to 5 s, the exit up to 8 s, then SIGTERM gets 5 s. Docker sends SIGKILL after 10 s by
+default, which loses the graceful close. Set `stop_grace_period: 30s` (Compose) or
+`docker stop -t 30` to keep it.
 
 ## License
 

{py_ib_controller-0.1.4 → py_ib_controller-0.1.5}/README.md

@@ -103,7 +103,7 @@ And the `ibcontroller run` parameters:
 │ --trading-mode             <live|paper>  Override Config.trading_mode ('live'/'paper') for this invocation.                                                                     │
 │ --tws-path                 <path>        Override Config.tws_path (the TWS/Gateway install-path inference) for this invocation.                                                 │
 │ --tws-channel              <str>         Override Config.tws_channel ('stable'/'latest', filters install auto-detection) for this invocation.                                   │
-│ --program                  <str>         Override Config.program ('gateway'/'tws') for this invocation.                                                                         │
+│ --program                  <gateway|tws> Override Config.program ('gateway'/'tws') for this invocation.                                                                         │
 │ --tws-settings-path        <path>        Override Config.tws_settings_path (where TWS/Gateway stores its own settings) for this invocation.                                     │
 │ --instance                 <str>         Override Config.instance (per-instance log/trace/socket names) for this invocation. Defaults to '{program}-{trading_mode}', so         │
 │                                          --trading-mode alone is usually enough to keep paper/live instances apart.                                                             │
@@ -175,7 +175,7 @@ When environment variable `IBC_APP_DIR` is not set, then
 | --- | --- | --- |
 | `config_dir` | `~/.config/ibcontroller` | Linux |
 | `config_dir` | `~/Library/Application Support/ibcontroller` | macOS |
-| `log_dir` | `~/.local/share/ibcontroller` | Linux |
+| `log_dir` | `~/.local/state/ibcontroller/log` | Linux |
 | `log_dir` | `~/Library/Logs/ibcontroller` | macOS |
 | `socket_dir` | `/run/user/<uid>/ibcontroller` | Linux |
 | `socket_dir` | `~/Library/Caches/TemporaryItems/ibcontroller` | macOS |
@@ -186,6 +186,13 @@ When `IBC_APP_DIR` is set then:
 - `log_dir`-> `IBC_APP_DIR/log`
 - `socket_dir` -> `IBC_APP_DIR/run`
 
+Socket paths (`socket_dir/ibcontroller-agent-<instance>-events.sock`) must fit
+the Unix socket limit: 102 bytes on macOS, 106 on Linux. On macOS the default
+`socket_dir` leaves room for an instance name of about 15 characters with a
+5-letter user name (each extra user-name character costs one). Over the limit,
+`ibcontroller run` stops with an error naming the path; use a shorter instance
+name or set `IBC_APP_DIR` to a shorter directory.
+
 ### Settings
 
 `ibcontroller`ships with sensible defaults.  **Only the two credential env vars below are actually mandatory**
@@ -201,7 +208,7 @@ allowing `None`. `Config`'s schema is closed — an unknown key in
 | TOML key | Env var or CLI flag | Description | Default |
 | --- | --- | --- | --- |
 | `instance` | `IBC_INSTANCE`, `--instance` | Instance name; separate log/trace files per instance | `"{program}-{trading_mode}"` (e.g. `"gateway-paper"`) |
-| `program` | `IBC_PROGRAM`, `--program` | `"gateway"` or `"tws"` | `"gateway"` |
+| `program` | `IBC_PROGRAM`, `--program` | `"gateway"` or `"tws"` (any letter case); anything else is a config error | `"gateway"` |
 | `tws_version` | `IBC_TWS_VERSION` | Installed TWS/Gateway version, e.g. `"10.50"` | `None` — auto-detected (see below) |
 | `tws_channel` | `IBC_TWS_CHANNEL`, `--tws-channel` | `"stable"`/`"latest"`; narrows auto-detection to one update channel | `"stable"` |
 | `tws_path` | `IBC_TWS_PATH`, `--tws-path` | Override TWS/gateway install-path inference | `None` |
@@ -215,6 +222,7 @@ allowing `None`. `Config`'s schema is closed — an unknown key in
 | `log_backup_count` | `IBC_LOG_BACKUP_COUNT` | Number of rotated backups to keep. Only respected when `log_sink="file"` | `5` |
 | `diagnostic_scope` | `IBC_DIAGNOSTIC_SCOPE` | `"known"`/`"unknown"`/`"all"` — which windows get a structure dump logged (see `docs/Configuration.md`'s "Diagnostics") | `"known"` |
 | `diagnostic_when` | `IBC_DIAGNOSTIC_WHEN` | `"open"`/`"openclose"`/`"never"` — when to log a structure dump | `"never"` |
+| `diagnostic_settings_sweep` | `IBC_DIAGNOSTIC_SETTINGS_SWEEP` | Log a dump of each Global Configuration tree node in `labels.settings.sweep_paths` (see `docs/Configuration.md`'s "Diagnostics") | `false` |
 | (env only) | `IBC_APP_DIR`, `--app-dir` | Override file locations (config/log/run) for container mode; `--app-dir`/`init`/`run` set the env var for the invocation, same effect |
 
 TWS/ibgateway settings
@@ -222,15 +230,16 @@ TWS/ibgateway settings
 | TOML key | Env var or CLI flag | Description | Default |
 | --- | --- | --- | --- |
 | `trading_mode` | `IBC_TRADING_MODE`, `--trading-mode` | `"live"` or `"paper"`; which account to authenticate as | `"paper"` |
-| `read_only_login` | `IBC_READ_ONLY_LOGIN` | TWS-only; **not yet wired to any behavior** (loaded, unused — see TODO.md) | `false` |
+| `read_only_login` | `IBC_READ_ONLY_LOGIN` | TWS-only (Gateway warns and logs in normally); clicks "Enter Read Only" on the 2FA frame instead of waiting for the push, no effect without 2FA (paper) | `false` |
 | `read_only_api` | `IBC_READ_ONLY_API` | `true`/`false` sets it; omit to leave unchanged. Applied to Gateway/TWS automatically -- see "Declarative configuration" below | `None` |
 | `accept_incoming_connections` | `IBC_ACCEPT_INCOMING_CONNECTIONS` | `manual`/`accept`/`reject` | `"manual"` |
 | `existing_session_action` | `IBC_EXISTING_SESSION_ACTION` | `manual`/`primary`/`primaryoverride`/`secondary` | `"manual"` |
 | `login_dialog_display_timeout` | `IBC_LOGIN_DIALOG_DISPLAY_TIMEOUT` | Seconds to wait for the login dialog | `60.0` |
-| `mfa_timeout` | `IBC_MFA_TIMEOUT` | IB's 2FA timeout in seconds | `180.0` |
-| `relogin_after_mfa_timeout` | `IBC_RELOGIN_AFTER_MFA_TIMEOUT` | Restart login if 2FA times out | `false` |
-| `mfa_exit_interval` | `IBC_MFA_EXIT_INTERVAL` | Bounds the post-2FA wait when relogin enabled | `60.0` |
-| `mfa_timeout_action` | `IBC_MFA_TIMEOUT_ACTION` | `exit` (exit 75, see "Exit codes" above) or `restart` (relaunch with a fresh login) when the 2FA push goes unanswered until `mfa_timeout` or `mfa_exit_interval` fires | `"exit"` |
+| `mfa_timeout` | `IBC_MFA_TIMEOUT` | IB's 2FA limit in seconds; a dialog closing at or after it counts as timed out | `180.0` |
+| `relogin_after_mfa_timeout` | `IBC_RELOGIN_AFTER_MFA_TIMEOUT` | Log in again after a timed-out push, and enforce `mfa_exit_interval` after an approved one | `false` |
+| `mfa_exit_interval` | `IBC_MFA_EXIT_INTERVAL` | Post-approval wait for login to complete when relogin is on | `60.0` |
+| `mfa_timeout_action` | `IBC_MFA_TIMEOUT_ACTION` | `exit` (exit 75, see "Exit codes" above) or `restart` (relaunch with a fresh login) when `mfa_exit_interval` expires after an approved push | `"exit"` |
+| `restart_cap` | `IBC_RESTART_CAP` | Max consecutive relaunches that never reach READY (login frame timeout, transient login failure, logout, crash during login); then exit 70 | `3` |
 | `auto_restart_time` | `IBC_AUTO_RESTART_TIME` | `"hh:mm AM/PM"` daily auto-restart time. Applied to Gateway/TWS automatically -- see "Declarative configuration" below | `None` |
 | `auto_logoff_time` | `IBC_AUTO_LOGOFF_TIME` | `"hh:mm AM/PM"` daily auto-logoff time; same "Lock and Exit" radio-button pair as `auto_restart_time` -- if both are set, `auto_restart_time` wins | `None` |
 | `time_zone` | `IBC_TIME_ZONE` | IANA zone name, e.g. `"Europe/Zurich"`, written to `jts.ini`'s `TimeZone`. Auto-detected from `TZ`, then `/etc/localtime` -- no setup needed in the common case; never overwrites an existing `TimeZone` line | auto-detected |
@@ -291,10 +300,19 @@ more fields of the bundled default, field by field — you only need to include
 you're changing, not the whole file. Use it when a TWS/Gateway release renames a button
 or dialog title ibcontroller matches against.
 
+A malformed file is rejected at startup (exit code 78) with a message naming the file and
+the field: a string where a list is expected, an empty list of titles or buttons, invalid
+JSON, or a `dismiss_rules` entry without `match_title`/`match_text`. A misspelled key is
+logged as a warning and ignored, so check the log if an override seems to have no effect.
+
+`generic.dismiss_buttons` lists the buttons tried, in order, to close a pop-up no specific
+handler recognises (default `OK`, `Close`, `Dismiss`).
+
 The one part of `labels.json` that isn't just text is `dismiss_rules` — a list of
 "if a window matches, click this button" entries, checked on every window that opens.
 Each entry needs at least one of `match_title`/`match_text` (both, if given, must
-match); `click` is the button's label.
+match); `click` is the button's label. `match_text` also matches message text with HTML
+tags removed and entities decoded, so copy the phrase as it shows on screen.
 
 ```json
 {
@@ -308,13 +326,18 @@ match); `click` is the button's label.
 }
 ```
 
-`dismiss_rules` is a list, not a map — an override *replaces the whole list*, so if you
-want to keep the bundled entries (the non-brokerage-account warning, the auto-restart
-confirmation notice) alongside your own, copy them into your override file too rather
-than starting from an empty list. Good for any pop-up that's always handled the same
+`dismiss_rules` entries are merged by `name`: an entry with a bundled rule's name replaces
+that rule, an entry with a new name is added, and bundled rules (the non-brokerage-account
+warning, the auto-restart confirmation notice) you don't name are kept. Removing a bundled
+rule is not supported. Good for any pop-up that's always handled the same
 simple way; a dialog needing real logic (parsing a value out of its text, retrying,
 raising an error) isn't expressible this way and needs actual code.
 
+Login-outcome dialogs ("Login failed", "Unrecognized Username or Password", the connection
+and too-many-attempts warnings) and the "Shutdown progress" / "Restart in progress" windows
+are always handled first. A `dismiss_rules` entry that matches one of them never runs, so a
+credential rejection still exits with code 77 and a restart is still recognised as one.
+
 ### `ibkr_settings.toml` — Global Configuration settings
 
 Global Configuration settings (the "Configure" / "Settings" dialog inside Gateway/TWS)
@@ -329,7 +352,13 @@ are applied once, right after login, from two layers combined into one list:
 - **Your own `ibkr_settings.toml`** — anything else: any other Global Configuration
   checkbox or text field, activated by pointing `[settings] file = "..."` (or
   `IBC_SETTINGS_FILE`) at a real file (rename `ibkr_settings.toml.example` to
-  start from the bundled worked examples, e.g. the `api_precautions_*` toggles).
+  start from the bundled worked examples: the `api_precautions_*` toggles, plus commented
+  entries for the API socket port, the master API client ID and "Send market data in lots
+  for US stocks" under `API/Settings`).
+
+When no entry resolves to a value (the default), the dialog is not opened. Only the TWS Mosaic
+layout is supported: on TWS Classic no setting is applied and the attempt waits for
+`mfa_timeout` (default 180s) before failing. Gateway is not affected.
 
 An entry looks like this:
 
@@ -482,6 +511,42 @@ or both.
   instances (e.g. `paper` and `live`) can run in parallel and each tail its own files
   without interleaving, even if copied or globbed out of their directory.
 
+## Finding the TWS / Gateway installation
+
+ibcontroller does not install anything: it launches the TWS or Gateway you already
+installed with IBKR's own installer, using that install's jars and bundled JRE. It
+resolves the installation in three steps.
+
+1. **Install root** (`tws_path`). Unless set, it defaults to:
+
+   | OS | Default root |
+   | --- | --- |
+   | macOS | `~/Applications` |
+   | Linux | `~/Jts` |
+
+2. **Version** (`tws_version`). A pinned `tws_version` is used as-is. Otherwise
+   ibcontroller scans the root, picks the greatest installed version and logs the
+   choice; `tws_channel` narrows the scan first. See "`tws_version` auto-detection"
+   above.
+
+3. **Install directory.** Version and `program` select the directory below the root:
+
+   | OS | Gateway | TWS |
+   | --- | --- | --- |
+   | macOS | `IB Gateway <version>/` | `Trader Workstation <version>/` |
+   | Linux | `ibgateway/<version>/` | `<version>/` |
+
+   A directory counts as an installation only if it has a `jars/` subfolder. The
+   classpath is built from those jars plus the install's `.install4j/i4jruntime.jar`,
+   and the JVM options come from its `ibgateway.vmoptions` / `tws.vmoptions`.
+
+If nothing matches, ibcontroller exits with an error naming `tws_path` and
+`tws_channel`. A `program = "tws"` request with no TWS install falls back to a
+Gateway install; the reverse does not (details above).
+
+Settings (`tws_settings_path`) are separate from the install root: each instance
+defaults to its own `~/Jts/<instance>`, so `paper` and `live` do not share state.
+
 ## Exit codes
 
 `ibcontroller run` exits with a [BSD sysexits](https://man.freebsd.org/cgi/man.cgi?query=sysexits)
@@ -491,22 +556,34 @@ code, grouped by what a supervisor (a container's `restart:` policy, systemd's
 
 | Code | Meaning | Supervisor action |
 | --- | --- | --- |
-| `0` | Intentional stop (Ctrl-C, `closedown_at`, Gateway/TWS closed normally, e.g. File>Close) | Do not restart |
+| `0` | Intentional stop (Ctrl-C, `closedown_at`, Gateway/TWS closed normally, e.g. File>Close, or this session yielded to another via `existing_session_action`: `stopped: SESSION_CEDED`) | Do not restart |
 | `1` | Unhandled exception (a bug) | Restart, report |
 | `2` | CLI usage error | Fix the command |
 | `78` (`EX_CONFIG`) | Deployment error (bad config, install not found) | Do not retry |
 | `77` (`EX_NOPERM`) | Credentials rejected | Do not retry (lockout risk) |
-| `75` (`EX_TEMPFAIL`) | 2FA not approved in time, `mfa_timeout_action=exit` | Retry per policy |
-| `69` (`EX_UNAVAILABLE`) | Transient runtime failure (process crashed or killed, connection lost, JVM exited before becoming ready, login timed out with no 2FA dialog) | Retry |
+| `76` (`EX_PROTOCOL`) | A dialog `existing_session_action` rules out (Trading Login Handoff with `secondary`/`primaryoverride`) | Do not retry |
+| `75` (`EX_TEMPFAIL`) | Login did not complete after 2FA, `mfa_timeout_action=exit` | Retry per policy |
+| `70` (`EX_SOFTWARE`) | `restart_cap` consecutive relaunches never reached READY | Do not retry |
+| `69` (`EX_UNAVAILABLE`) | Transient runtime failure (process crashed or killed, connection lost, JVM exited before becoming ready) | Retry |
 
-`77`/`78` work with systemd's `RestartPreventExitStatus=`.
+`70`/`76`/`77`/`78` work with systemd's `RestartPreventExitStatus=`.
 
 Some login-blocking dialogs IB reports as a server-side condition -- not a credential
-rejection -- never reach this table at all: a "Login failed"/"Login Error" dialog, or a
+rejection -- never reach this table at all: a "Login failed"/"Login Error"/"not currently available" dialog, or a
 Gateway "Connection to server failed" reason other than a known credential/account one
 (e.g. a stale restart token), make ibcontroller relaunch in-process with a full fresh
-login, unbounded, the same way a scheduled `cold_restart_time` does -- the container
-itself never exits or restarts for these.
+login, the same way a scheduled `cold_restart_time` does -- the container
+itself does not exit for these, until `restart_cap` consecutive relaunches never reach READY
+(exit 70).
+
+## Stopping under Docker
+
+On SIGTERM (`docker stop`, Ctrl-C) a logged-in instance closes through File > Exit/Close so
+TWS/Gateway can save its session and upload settings. Measured over 88 shutdowns: mean 1.3 s,
+p99 4.3 s, max 4.9 s. A slow path (a dialog open, a stuck menu) can take longer: the menu retry
+waits up to 5 s, the exit up to 8 s, then SIGTERM gets 5 s. Docker sends SIGKILL after 10 s by
+default, which loses the graceful close. Set `stop_grace_period: 30s` (Compose) or
+`docker stop -t 30` to keep it.
 
 ## License