PyPI - py-ib-controller - Versions diffs - 0.1.3__tar.gz → 0.1.5__tar.gz - Mend

py-ib-controller 0.1.3tar.gz → 0.1.5tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (96) hide show

{py_ib_controller-0.1.3 → py_ib_controller-0.1.5}/.github/workflows/ci.yml RENAMED Viewed

@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@v7
       - name: Install uv and Python
-        uses: astral-sh/setup-uv@v10.1.0
+        uses: astral-sh/setup-uv@v10.2.0
         with:
           python-version: ${{ matrix.python-version }}
@@ -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.3 → py_ib_controller-0.1.5}/.github/workflows/publish.yml RENAMED Viewed

@@ -26,7 +26,7 @@ jobs:
           fetch-depth: 0
       - name: Install uv and Python
-        uses: astral-sh/setup-uv@v10.1.0
+        uses: astral-sh/setup-uv@v10.2.0
         with:
           python-version: ${{ env.PYTHON_VERSION }}

{py_ib_controller-0.1.3 → py_ib_controller-0.1.5}/Makefile RENAMED Viewed

@@ -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.3 → py_ib_controller-0.1.5}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-ib-controller
-Version: 0.1.3
+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
@@ -52,7 +52,9 @@ Give it a spin, `ib-controller run --dotenv=.env-paper --trading-mode=paper --pr
 https://github.com/user-attachments/assets/b97f7180-29d9-4e09-b32f-8be838dff0e2
-To build from source, this is the short version, for a detailed guide please check the [development guide](./docs/development.md).
+You can check the full list of [cli parameters](#cli-parameters) or [config keys](#configuration).
+To it build from source:
 ```bash
 # 0. Fetch the code
@@ -70,9 +72,11 @@ uv run ibcontroller init
 uv run ibcontroller run
 ```
+For a detailed build guide please check the [development guide](./docs/development.md).
 `ibcontroller run` scaffolds the config directory automatically the first time
 `ibcontroller.toml` is missing (same effect as running `init` first), so it can also be
-run directly on a fresh install -- it will still fail with a clear error naming whichever
+run directly on a fresh install. It will still fail with a clear error naming whichever
 setting is actually missing (in practice, just the two credential env vars).
 ### CLI parameters
@@ -121,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.                                                             │
@@ -179,6 +183,11 @@ Each also accepts a `_FILE`-suffixed variant (`IBC_USERID_FILE`,
 `IBC_PASSWORD_FILE`) that reads the value from a file instead —
 Docker/Compose secrets, so a value never has to sit in the process environment.
+The startup `IBC_*` environment dump masks any variable whose name contains
+`PASSWORD`, `USERID`, `SECRET`, `TOKEN`, `TOTP` or `KEY` (e.g.
+`IBC_PASSWORD_PAPER`, set by other tooling), except `_FILE` variants, which
+only hold a path.
 ### File location
 When environment variable `IBC_APP_DIR` is not set, then
@@ -188,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 |
@@ -199,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**
@@ -214,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` |
@@ -224,8 +240,11 @@ allowing `None`. `Config`'s schema is closed — an unknown key in
 | `log_dir` | `IBC_LOG_DIR` | Where ibcontroller's own log file lives; always resolved at startup | platform default |
 | `log_level` | `IBC_LOG_LEVEL` | `debug`/`info`/`warning`/`error` | `info` |
 | `log_sink` | `IBC_LOG_SINK` | `"std"` (console only) or `"file"` (only, under `log_dir`) — exclusive, not both. Covers `ibcontroller-{instance}.log` and `gateway-{instance}.log` only; the Java agent log and the wire trace are always file, unaffected — see "Logging" below | `"std"` |
+| `log_max_bytes` | `IBC_LOG_MAX_BYTES` | Rotate log/trace files at this size in bytes; `0` disables rotation. Only respected when `log_sink="file"` | `10485760` (10 MiB) |
+| `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
@@ -233,16 +252,19 @@ 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` | `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 |
 | `cold_restart_time` | `IBC_COLD_RESTART_TIME` | TWS and Gateway. `"HH:MM"` 24-hour local time; every Sunday, ibcontroller closes the instance tidily and relaunches with a full fresh login, forcing IBKR's weekly Sunday 01:00 US/Eastern token-invalidation reauth -- not a GUI setting, see "Scheduled shutdown" below | `None` |
 | `closedown_at` | `IBC_CLOSEDOWN_AT` | TWS and Gateway. `"HH:MM"` (daily) or `"<Weekday> HH:MM"` (weekly); closes the instance tidily at that time, no relaunch -- not a GUI setting, see "Scheduled shutdown" below | `None` |
@@ -288,7 +310,7 @@ US/Eastern invalidation window if that's the intent.
 ## Declarative configuration
-Beyond `ibcontroller.toml`, three things let you shape ibcontroller's behavior without
+Beyond `ibcontroller.toml`, two things let you shape ibcontroller's behavior without
 writing any Python: **`labels.json`** (window/button text, plus simple pop-up dismissal
 rules) and **`ibkr_settings.toml`** (Global Configuration settings applied to Gateway/TWS
 at startup). Each is covered below.
@@ -300,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
 {
@@ -317,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)
@@ -338,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:
@@ -409,10 +451,17 @@ scrollback.
 | --- | --- | --- | --- |
 | `ibcontroller-{instance}.log` | ibcontroller app control flow | `log_sink=file` (else console) | `log_level` (default `info`) |
 | `gateway-{instance}.log` | TWS/Gateway own stdout/stderr | `log_sink=file` (else console) | TWS/Gateway's own |
-| `ibcontroller-java-agent-{instance}.log` | Java agent (in-process JUL) | always file, not affected by `log_sink` | `log_level` (see mapping below) |
+| `ibcontroller-java-agent-{instance}.log` (see rotation note below) | Java agent (in-process JUL) | always file, not affected by `log_sink` | `log_level` (see mapping below) |
 | `cmd-{instance}.jsonl` | raw wire: commands sent + results, NDJSON | `trace_enabled`; always file, not affected by `log_sink` | always (DEBUG emit, gated separately) |
 | `events-{instance}.jsonl` | raw wire: every event message received, NDJSON | `trace_enabled`; always file, not affected by `log_sink` | always (DEBUG emit, gated separately) |
+**Rotation** (`IBC_LOG_MAX_BYTES`/`IBC_LOG_BACKUP_COUNT`, default 10 MiB x 5
+backups, **on by default**) applies to every file above in file mode. Set
+`IBC_LOG_MAX_BYTES=0` to disable it (unbounded files). Python's files keep
+their usual name active, with `.1`/`.2`/... as old backups. The Java agent log
+is the opposite: once rotation is on, the active file is
+`ibcontroller-java-agent-{instance}.log.0`, not the unsuffixed name.
 ### Log levels
 `IBC_LOG_LEVEL` (`debug`/`info`/`warning`/`error`, default `info`) controls
@@ -484,6 +533,80 @@ 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)
+code, grouped by what a supervisor (a container's `restart:` policy, systemd's
+`Restart=`) should do about it. The specific cause is always in the logs and in the
+`stopped: <CAUSE>` line.
+| Code | Meaning | Supervisor action |
+| --- | --- | --- |
+| `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) |
+| `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 |
+`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"/"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, 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
 ```text

{py_ib_controller-0.1.3 → py_ib_controller-0.1.5}/README.md RENAMED Viewed

@@ -30,7 +30,9 @@ Give it a spin, `ib-controller run --dotenv=.env-paper --trading-mode=paper --pr
 https://github.com/user-attachments/assets/b97f7180-29d9-4e09-b32f-8be838dff0e2
-To build from source, this is the short version, for a detailed guide please check the [development guide](./docs/development.md).
+You can check the full list of [cli parameters](#cli-parameters) or [config keys](#configuration).
+To it build from source:
 ```bash
 # 0. Fetch the code
@@ -48,9 +50,11 @@ uv run ibcontroller init
 uv run ibcontroller run
 ```
+For a detailed build guide please check the [development guide](./docs/development.md).
 `ibcontroller run` scaffolds the config directory automatically the first time
 `ibcontroller.toml` is missing (same effect as running `init` first), so it can also be
-run directly on a fresh install -- it will still fail with a clear error naming whichever
+run directly on a fresh install. It will still fail with a clear error naming whichever
 setting is actually missing (in practice, just the two credential env vars).
 ### CLI parameters
@@ -99,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.                                                             │
@@ -157,6 +161,11 @@ Each also accepts a `_FILE`-suffixed variant (`IBC_USERID_FILE`,
 `IBC_PASSWORD_FILE`) that reads the value from a file instead —
 Docker/Compose secrets, so a value never has to sit in the process environment.
+The startup `IBC_*` environment dump masks any variable whose name contains
+`PASSWORD`, `USERID`, `SECRET`, `TOKEN`, `TOTP` or `KEY` (e.g.
+`IBC_PASSWORD_PAPER`, set by other tooling), except `_FILE` variants, which
+only hold a path.
 ### File location
 When environment variable `IBC_APP_DIR` is not set, then
@@ -166,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 |
@@ -177,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**
@@ -192,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` |
@@ -202,8 +218,11 @@ allowing `None`. `Config`'s schema is closed — an unknown key in
 | `log_dir` | `IBC_LOG_DIR` | Where ibcontroller's own log file lives; always resolved at startup | platform default |
 | `log_level` | `IBC_LOG_LEVEL` | `debug`/`info`/`warning`/`error` | `info` |
 | `log_sink` | `IBC_LOG_SINK` | `"std"` (console only) or `"file"` (only, under `log_dir`) — exclusive, not both. Covers `ibcontroller-{instance}.log` and `gateway-{instance}.log` only; the Java agent log and the wire trace are always file, unaffected — see "Logging" below | `"std"` |
+| `log_max_bytes` | `IBC_LOG_MAX_BYTES` | Rotate log/trace files at this size in bytes; `0` disables rotation. Only respected when `log_sink="file"` | `10485760` (10 MiB) |
+| `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
@@ -211,16 +230,19 @@ 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` | `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 |
 | `cold_restart_time` | `IBC_COLD_RESTART_TIME` | TWS and Gateway. `"HH:MM"` 24-hour local time; every Sunday, ibcontroller closes the instance tidily and relaunches with a full fresh login, forcing IBKR's weekly Sunday 01:00 US/Eastern token-invalidation reauth -- not a GUI setting, see "Scheduled shutdown" below | `None` |
 | `closedown_at` | `IBC_CLOSEDOWN_AT` | TWS and Gateway. `"HH:MM"` (daily) or `"<Weekday> HH:MM"` (weekly); closes the instance tidily at that time, no relaunch -- not a GUI setting, see "Scheduled shutdown" below | `None` |
@@ -266,7 +288,7 @@ US/Eastern invalidation window if that's the intent.
 ## Declarative configuration
-Beyond `ibcontroller.toml`, three things let you shape ibcontroller's behavior without
+Beyond `ibcontroller.toml`, two things let you shape ibcontroller's behavior without
 writing any Python: **`labels.json`** (window/button text, plus simple pop-up dismissal
 rules) and **`ibkr_settings.toml`** (Global Configuration settings applied to Gateway/TWS
 at startup). Each is covered below.
@@ -278,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
 {
@@ -295,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)
@@ -316,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:
@@ -387,10 +429,17 @@ scrollback.
 | --- | --- | --- | --- |
 | `ibcontroller-{instance}.log` | ibcontroller app control flow | `log_sink=file` (else console) | `log_level` (default `info`) |
 | `gateway-{instance}.log` | TWS/Gateway own stdout/stderr | `log_sink=file` (else console) | TWS/Gateway's own |
-| `ibcontroller-java-agent-{instance}.log` | Java agent (in-process JUL) | always file, not affected by `log_sink` | `log_level` (see mapping below) |
+| `ibcontroller-java-agent-{instance}.log` (see rotation note below) | Java agent (in-process JUL) | always file, not affected by `log_sink` | `log_level` (see mapping below) |
 | `cmd-{instance}.jsonl` | raw wire: commands sent + results, NDJSON | `trace_enabled`; always file, not affected by `log_sink` | always (DEBUG emit, gated separately) |
 | `events-{instance}.jsonl` | raw wire: every event message received, NDJSON | `trace_enabled`; always file, not affected by `log_sink` | always (DEBUG emit, gated separately) |
+**Rotation** (`IBC_LOG_MAX_BYTES`/`IBC_LOG_BACKUP_COUNT`, default 10 MiB x 5
+backups, **on by default**) applies to every file above in file mode. Set
+`IBC_LOG_MAX_BYTES=0` to disable it (unbounded files). Python's files keep
+their usual name active, with `.1`/`.2`/... as old backups. The Java agent log
+is the opposite: once rotation is on, the active file is
+`ibcontroller-java-agent-{instance}.log.0`, not the unsuffixed name.
 ### Log levels
 `IBC_LOG_LEVEL` (`debug`/`info`/`warning`/`error`, default `info`) controls
@@ -462,6 +511,80 @@ 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)
+code, grouped by what a supervisor (a container's `restart:` policy, systemd's
+`Restart=`) should do about it. The specific cause is always in the logs and in the
+`stopped: <CAUSE>` line.
+| Code | Meaning | Supervisor action |
+| --- | --- | --- |
+| `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) |
+| `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 |
+`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"/"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, 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
 ```text

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

py-ib-controller 0.1.3tar.gz → 0.1.5tar.gz