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

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

@@ -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 }}
 

{py_ib_controller-0.1.2 → py_ib_controller-0.1.4}/.github/workflows/publish.yml

@@ -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 }}
 
@@ -95,21 +95,22 @@ jobs:
             ./dist/*.tar.gz ./dist/*.whl
 
       - name: Generate changelog
+        id: git-cliff
         uses: orhun/git-cliff-action@v4
         with:
           # no cliff.toml -- git-cliff's built-in default config already
           # groups Conventional Commits (feat/fix/docs/...) correctly
           args: --latest --tag ${{ github.ref_name }} --strip header
-          output: CHANGELOG_release.md
 
       - name: Assemble release notes
         env:
           TAG: ${{ github.ref_name }}
           REPO: ${{ github.repository }}
+          CHANGELOG: ${{ steps.git-cliff.outputs.content }}
         run: |
           PREV_TAG=$(git describe --tags --abbrev=0 "$TAG^" 2>/dev/null || true)
           {
-            cat CHANGELOG_release.md
+            echo "$CHANGELOG"
             echo
             echo "## Installation"
             echo

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-ib-controller
-Version: 0.1.2
+Version: 0.1.4
 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
@@ -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
@@ -224,6 +233,8 @@ 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"` |
 | (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 |
@@ -241,8 +252,10 @@ TWS/ibgateway settings
 | `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"` |
 | `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 +301,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.
@@ -409,10 +422,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 +504,32 @@ 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.
 
+## 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) | 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 |
+
+`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
+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.
+
 ## License
 
 ```text

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

@@ -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
@@ -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
@@ -202,6 +211,8 @@ 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"` |
 | (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 |
@@ -219,8 +230,10 @@ TWS/ibgateway settings
 | `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"` |
 | `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 +279,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.
@@ -387,10 +400,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 +482,32 @@ 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.
 
+## 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) | 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 |
+
+`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
+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.
+
 ## License
 
 ```text

{py_ib_controller-0.1.2 → py_ib_controller-0.1.4}/agent/src/main/java/ibcontroller/agent/AgentMain.java

@@ -133,6 +133,14 @@ public final class AgentMain {
      * Python and read here -- the agent never invents paths or levels itself. When
      * {@code ibcontroller.logfile} is absent (e.g. {@code make run}), logs go to
      * stderr only, same as before this mechanism existed.
+     *
+     * <p>Rotation (gitea #32): {@code -Dibcontroller.logfile.maxbytes=<N>} and
+     * {@code -Dibcontroller.logfile.backupcount=<N>} mirror Python's own
+     * {@code log_max_bytes}/{@code log_backup_count}. {@code FileHandler}'s own
+     * fd can't be rotated externally (the JVM keeps writing to a renamed/unlinked
+     * inode), so this uses its 4-arg constructor, which does native generation
+     * rotation on the JVM's own thread. {@code maxbytes=0} (the default if the
+     * property is absent) keeps the old unbounded, append-only file.
      */
     private static void configureLogging() throws Exception {
         Logger root = Logger.getLogger("");
@@ -145,7 +153,14 @@ public final class AgentMain {
 
         String logFile = System.getProperty("ibcontroller.logfile");
         if (logFile != null && !logFile.isEmpty()) {
-            FileHandler fileHandler = new FileHandler(logFile, true);
+            int maxBytes = Integer.parseInt(
+                    System.getProperty("ibcontroller.logfile.maxbytes", "0"));
+            int backupCount = Integer.parseInt(
+                    System.getProperty("ibcontroller.logfile.backupcount", "0"));
+            FileHandler fileHandler =
+                    maxBytes > 0
+                            ? new FileHandler(logFile, maxBytes, Math.max(backupCount, 1), true)
+                            : new FileHandler(logFile, true);
             fileHandler.setFormatter(new SimpleFormatter());
             root.addHandler(fileHandler);
         } else {

{py_ib_controller-0.1.2 → py_ib_controller-0.1.4}/docs/Configuration.md

@@ -24,6 +24,10 @@ accepts a `_FILE`-suffixed variant that reads the value from a file instead
 (Docker/Compose secrets): `IBC_USERID` / `IBC_PASSWORD`,
 `IBC_USERID_FILE` / `IBC_PASSWORD_FILE`.
 
+The startup `IBC_*` environment dump masks any variable whose name contains
+`PASSWORD`, `USERID`, `SECRET`, `TOKEN`, `TOTP` or `KEY` (e.g.
+`IBC_PASSWORD_PAPER`), except `_FILE` variants, which only hold a path.
+
 ## IBController specific settings
 
 Settings that drive the behaviour of `ibcontroller` itself.
@@ -60,6 +64,7 @@ Settings related to TWS/ibgateway.
 | `existing_session_action` | `IBC_EXISTING_SESSION_ACTION` | What to do when an existing session is detected -- see below | `"manual"` |
 | `auto_restart_time` | `IBC_AUTO_RESTART_TIME` | Daily auto-restart time, `"hh:mm AM/PM"` -- see below | `None` (unchanged) |
 | `auto_logoff_time` | `IBC_AUTO_LOGOFF_TIME` | Daily auto-logoff time, `"hh:mm AM/PM"` -- see below | `None` (unchanged) |
+| `time_zone` | `IBC_TIME_ZONE` | IANA zone name, e.g. `"Europe/Zurich"`, written to `jts.ini`'s `TimeZone` -- see below | auto-detected |
 
 ### Accept Incoming Connection
 
@@ -129,6 +134,21 @@ Time above, just selecting "Auto logoff" instead of "Auto restart". Omit this
 key (the default) to leave the existing setting unchanged. If both keys are
 set, Auto Restart Time wins -- set only one of the two in practice.
 
+### Time Zone
+
+**key:** `time_zone`
+**Environment variable:** `IBC_TIME_ZONE`
+
+IANA zone name, e.g. `"Europe/Zurich"`, written to `jts.ini`'s `TimeZone` key
+(under `[Logon]`) before every launch. No setup needed in the common case:
+auto-detected from the container's own `TZ` environment variable first, then
+from `/etc/localtime`'s zoneinfo symlink target; set `IBC_TIME_ZONE`
+explicitly only when the desired TWS/Gateway session time zone should differ
+from the host/container's own. Never overwrites a `TimeZone` line already
+present in `jts.ini` -- a value found there was set deliberately, either by
+you or by an earlier run of ibcontroller itself. Leaves the key untouched if
+nothing resolves.
+
 ### Cold Restart Time
 
 **key:** `cold_restart_time`
@@ -169,6 +189,7 @@ TWS/Gateway itself.
 | `mfa_timeout` | `IBC_MFA_TIMEOUT` | The real 2FA budget in seconds, mirroring IBKR's own external limit | `180.0` |
 | `relogin_after_mfa_timeout` | `IBC_RELOGIN_AFTER_MFA_TIMEOUT` | Restart the login attempt if 2FA times out (instead of giving up) | `false` |
 | `mfa_exit_interval` | `IBC_MFA_EXIT_INTERVAL` | Bounds the wait after a timed-out 2FA when relogin is enabled | `60.0` |
+| `mfa_timeout_action` | `IBC_MFA_TIMEOUT_ACTION` | What to do when the 2FA push goes unanswered until `mfa_timeout` or `mfa_exit_interval` expires: `exit` (exit 75) or `restart` (relaunch with a fresh login) | `exit` |
 
 ## Diagnostics
 

py_ib_controller-0.1.4/docs/development.md

@@ -0,0 +1,252 @@
+# Development environment
+
+How to get `ibcontroller` itself, and the Java agent it drives, running locally.
+
+## Target platform
+
+The supported platforms are macOS and Linux.
+
+## Python toolchain
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh   # if uv isn't already installed
+cd ibcontroller
+uv sync                                           # installs the dev dependency group too
+```
+
+Requires Python 3.12+ (pinned in `.python-version`). Day-to-day commands:
+
+```bash
+uv run pytest                # test suite (pytest-asyncio, pytest-aiohttp already in the dev group)
+uv run ruff check .          # lint
+uv run ruff format .         # format
+uv run pyrefly check         # type check
+uv run bandit -c pyproject.toml -r ibcontroller/   # security lint
+```
+
+## pre-commit
+
+`.pre-commit-config.yaml` (project root) runs ruff (lint + format), bandit, pyrefly, and basic
+hygiene hooks (trailing whitespace, end-of-file, yaml/toml checks, large-file check) on every
+commit — the same checks as the `uv run` commands above, wired to run automatically instead of by
+hand.
+
+```bash
+uv run pre-commit install    # one-time per clone: installs the git hook
+uv run pre-commit run --all-files   # run every hook against the whole tree, not just staged files
+```
+
+CI runs the same config, so a clean local `pre-commit run --all-files` is a reliable predictor of
+CI passing.
+
+## Java toolchain
+
+The agent needs to build against, and run compatibly with, the JRE TWS/Gateway bundles.
+
+**Local dev JDK, via SDKMAN:** a real Azul account/API token is needed for the exact SA-tier build
+above; without one, the closest public match is Zulu's CA (Certified Availability) tier at the
+same JDK version. SDKMAN manages that install and pins the version per project:
+
+One-time install (adds SDKMAN's init to your shell rc automatically):
+
+```bash
+curl -s "https://get.sdkman.io" | bash
+# install
+sdk install java 17.0.15-zulu
+```
+
+The pinned Java version lives in `.sdkmanrc` at the project root (checked in):
+
+```env
+java=17.0.15-zulu
+```
+
+Activate it per clone — SDKMAN then sets `JAVA_HOME` for the current shell:
+
+```bash
+sdk env use   # reads .sdkmanrc; installs the pinned JDK on first use
+java -version
+openjdk version "17.0.15" 2025-04-15 LTS
+OpenJDK Runtime Environment Zulu17.58+21-CA (build 17.0.15+6-LTS)
+OpenJDK 64-Bit Server VM Zulu17.58+21-CA (build 17.0.15+6-LTS, mixed mode, sharing)
+```
+
+Enable auto-env (`sdkman_auto_env=true` in `~/.sdkman/etc/config`) to have `JAVA_HOME` set
+automatically when entering the project directory, instead of running `sdk env use` in every new
+terminal. Either way, `JAVA_HOME` is the contract: the `Makefile` reads it (`JDK ?= $(JAVA_HOME)`),
+and CI's `actions/setup-java` (zulu 17) sets the same variable, so local and CI build with the
+same pin.
+
+This JDK is for *compiling* only — its own version doesn't need to match whatever Gateway/TWS
+happens to bundle locally . The `Makefile`'s `--release 17` tells `javac` to target Java 17
+bytecode/API regardless of which JDK compiles it, so the output runs correctly on whatever
+JRE TWS/gateway is using.
+
+The agent is small, so keep the build as plain
+as it can be: `javac` + `jar`, wired through a small `Makefile`.
+
+## TWS / IBKR Gateway itself
+
+Download from IBKR directly [gateway](https://www.interactivebrokers.com/en/trading/ibgateway-latest.php) or [TWS](https://www.interactivebrokers.com/en/trading/download-tws.php). Then install.
+
+After the first run, `ibcontroller` renames the gateway/TWS script. This is required to manage restarts.
+
+## Building and attaching the agent
+
+Java agent file structure:
+
+```text
+agent/src/main/java/ibcontroller/agent/
+  AgentMain.java         — entry point: both sockets, EventBridge installed before Gateway launches
+  Protocol.java          — command accept loop, hand-rolled JSON codec, full command dispatch
+  ComponentLookup.java   — read-only Swing tree walk, dump/get_text
+  WriteOps.java          — EDT-dispatched writes, set_text/set_checkbox/click
+  EventBridge.java       — AWTEventListener install + NDJSON event forwarding
+  Security.java          — password redaction, the credential-field boundary
+```
+
+Build using`Makefile`:
+
+```bash
+make build    # build/ibcontroller-agent.jar, then copies it into ibcontroller/ (for uv/pyproject packaging)
+make dist     # build the jar, then uv build the Python package (jar is required package-data, see Makefile)
+make clean    # rm -rf build dist
+```
+
+Day-to-day cycle: `make build` after any agent-side change, `uv run pytest` for the Python side,
+`pre-commit run --all-files` before pushing.
+
+## Running ibcontroller
+
+```bash
+# from the git repo
+source .venv/bin/activate
+ibcontroller run --dotenv=.env-paper --trading-mode=paper --program=gateway
+```
+
+## Architecture
+
+`ibcontroller` follows a layered architecture with separation of concerns between layers.
+Any contribution must follow this separation of concerns.
+
+![ibcontroller schematic architecture](Architecture.svg)
+
+### Rules for every layer
+
+- A layer talks only to the layer directly below it. The exceptions are listed per layer.
+- L3's schema types (`WindowEvent`, `WindowInfo`, `Component`, …) and exceptions are the shared
+  vocabulary of every layer above L3. Changing them is a cross-layer change.
+- Everything runs on one asyncio loop. No blocking call on the loop: file and process work goes
+  through `anyio.to_thread` or the logging listener threads.
+- One object graph per running instance (`Dispatcher`, `LoginManager`, recogniser registry, sockets,
+  settings directory). No module-level state shared between instances.
+- Every user-facing string (window titles, button and menu labels) comes from `labels.json` through
+  `labels.py`. Never a Python literal.
+- Credentials stay `Secret` until L3 builds the request line. Nothing logs or traces a credential
+  value.
+
+### L1 Process (`launcher.py`)
+
+- **Owns:** TWS/Gateway install discovery (macOS and Linux, channel filtering), JRE selection, the
+  JVM command line, the per-instance settings directory and socket paths, native-restart
+  prevention, spawning the JVM with the agent, draining its stdout, and readiness (`ping`).
+- **Provides:** `LaunchedInstance`: the process, a started `Dispatcher` (L4), socket paths,
+  settings directory.
+- **Rules:** one launch per call. Relaunch policy belongs to L6. L1 may construct L3 and L4 objects
+  ("spawn and attach").
+- **Known deviation:** `clean_shutdown` lives here and uses L5-1. It belongs to Management (L5).
+
+### L2 Java agent (`agent/`)
+
+- **Owns:** everything inside the TWS/Gateway JVM: starting the entry point, the AWT window
+  listener and window-ID registry, the command socket (request/response, one client at a time),
+  the event socket (`hello`, `snapshot`, `window_opened`/`window_closed`, `keepalive`, `overflow`),
+  running every UI read and write on the EDT, and credential redaction (`dump` redacts, `get_text`
+  refuses).
+- **Provides:** the wire protocol to L3.
+- **Rules:** the agent reports and executes; it makes no login, dialog or lifecycle decisions. Any
+  protocol change updates L3 in the same change.
+
+### L3 Agent client (`agent_client.py`)
+
+- **Owns:** the two socket connections, JSON line framing, the typed message schemas
+  (`attrs`/`cattrs`), and the typed exceptions mapping L2's error codes.
+- **Provides:** one typed method per agent command; an async iterator over event messages.
+- **Rules:** no scheduling, no fan-out, no imports from other `ibcontroller` modules. `set_text` and
+  `set_text_near_label` are the only places a `Secret` is unwrapped.
+
+### L4 Dispatcher (`dispatch.py`)
+
+- **Owns:** one `Dispatcher` per instance: both L3 connections, command serialization (one FIFO
+  worker, one command on the wire at a time), event fan-out, and the optional wire trace.
+- **Provides:** `send_command`, `window_events`, `tasks` (for L6 to detect a lost connection),
+  `start`/`stop`.
+- **Rules:** never interprets commands or events beyond routing them.
+
+### L5-1 Actions (`actions.py`, `labels.py`)
+
+- **Owns:** the action vocabulary (`click`, `type_text`, `toggle`, `navigate_menu`, `expand_tree`,
+  `dump`, `wait_for_event`, …) and the label data.
+- **Rules:** the only L5 code that calls `send_command`. L3 exceptions propagate unchanged. Actions
+  take a `window_id` wherever the agent supports one.
+
+### L5 Domains
+
+| Domain     | Code                                                          | Role                                                                          |
+| ---------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Login      | `login.py`, login-outcome recognisers in `recognisers.py`     | Fill credentials, detect success, MFA and failure, report the outcome.         |
+| Dialogs    | `RecognizerRegistry`, `watch_for_unprompted_windows`          | Recognise and handle windows nobody is waiting for.                          |
+| Settings   | `settings.py`, `builtin_settings.toml`, `ibkr_settings.toml`  | Apply declared Global Configuration settings.                                |
+| Scheduling | `schedule.py`                                                  | Wall-clock maths for cold restart and close-down. No I/O.                     |
+| Diagnostic | `diagnostics.py`                                               | Dump window structure for development and support.                           |
+| Management | not built                                                      | Graceful shutdown, restart and other lifecycle operations on the UI.          |
+
+- **Rules:**
+  - Act on the UI only through L5-1.
+  - Report outcomes to L6 as return values or typed exceptions. L6 decides relaunch, exit or
+    continue.
+  - Domains do not call each other; L6 wires them together.
+  - A recogniser acts only on the window it matched (`window_id`). The dialogs registry never acts
+    on a window with a visible credential field.
+- **Known deviations:**
+  - `recognisers.py` and `diagnostics.py` subscribe to `window_events` directly instead of through
+    L5-1.
+  - The registry construction and the settings sequence live in `control_loop.py`.
+  - Management's pieces live in L1 (`clean_shutdown`) and L6 (scheduled shutdown).
+
+### L6 Control loop (`control_loop.py`)
+
+- **Owns:** one instance's lifecycle, one cycle per JVM: launch → login (with the dialogs watcher) →
+  settings → ready → shutdown. Races every phase against process exit and connection loss,
+  classifies why the cycle ended (`ShutdownCause`), applies the relaunch policy, and owns every
+  task started during a cycle.
+- **Provides:** `run_control_loop`, cancelled to request a graceful stop. `cli.py` maps its result
+  and exceptions to exit codes.
+- **Rules:** the only layer that decides relaunch or stop. Cancellation is the only stop request.
+
+### L7 Control API (planned, not built)
+
+The contract below is provisional: it fixes the boundaries, not the interface.
+
+- **Purpose:** let something outside the process observe a running instance and request lifecycle
+  operations on it: an operator, a supervisor, a container health check.
+- **Owns:** the external interface: transport, access control, request validation, response
+  format, and mapping each request to an L6 or Management operation.
+- **Consumes:** L6, for lifecycle requests and instance state (startup state, login state, last
+  `ShutdownCause`), and Management (L5) operations, through L6.
+- **Rules:**
+  - Never reaches L4, L3 or L2 directly, and never drives the UI through L5-1 itself. A UI
+    operation is a Management operation, so serialization, window scoping and logging stay in L5.
+  - Never stops, kills or relaunches the process itself. It asks L6, which stays the only owner of
+    the cycle.
+  - Requests are intents, not blocking calls: a long operation is accepted, and its progress is
+    observable through state.
+  - Scoped to one instance, like every other layer.
+  - Local-only by default. Remote access needs explicit configuration, like IBC's `BindAddress` and
+    `ControlFrom`.
+  - Never returns credentials. Diagnostic output follows the same redaction as `dump`.
+- **Candidate operations, not committed:** status; stop; restart and cold restart; IBC
+  `CommandServer` parity (`STOP`, `EXIT`, `RESTART`, `ENABLEAPI`, `RECONNECTDATA`,
+  `RECONNECTACCOUNT`); a diagnostic dump.
+- **Open questions:** transport and access control; which IBC commands to support; whether
+  user-authored rules and plugins attach at L7 or at L5.