Prepare GABS 1.0.7 release

Author: pardeike

AGENTS.md

@@ -27,7 +27,7 @@ variables first:
 - `GABP_SERVER_PORT`
 - `GABP_TOKEN`
 - `GABS_GAME_ID`
-- `GABS_BRIDGE_PATH` as fallback/debug metadata only
+- `GABS_BRIDGE_PATH` as endpoint-cache/debug metadata only
 
 `runtime.json` belongs to GABS ownership coordination. Game-side bridge code
 must ignore it.

README.md

@@ -117,9 +117,10 @@ If your client disconnects after `tools/list` because it rejects a public tool's
 [Configuration Guide](docs/CONFIGURATION.md). Mirrored game tools are discovered
 through `games_tool_names` and are not advertised in the public `tools/list`
 response.
-If a game or bridge starts slowly, you can also tune startup waits with the
-`timeouts.startup` section described in the
-[Configuration Guide](docs/CONFIGURATION.md).
+If a game or bridge starts slowly, tune the total background connection budget
+with the `timeouts.startup` section described in the
+[Configuration Guide](docs/CONFIGURATION.md). `games_start` still returns after a
+bounded initial wait so MCP clients do not time out while the game keeps loading.
 
 ### 4. Try these prompts
 
@@ -136,14 +137,23 @@ If you want a download-to-working walkthrough, use the
 - **Steam/Epic stopping**: use the real game process name, not the launcher
   name.
 - **More than one AI session**: that is fine. GABS coordinates ownership per
-  game so two live sessions do not both launch or attach to the same game by
-  accident.
-- **Game bridge cannot find bridge config**: the game-side bridge should first read
-  `GABP_SERVER_PORT`, `GABP_TOKEN`, and `GABS_GAME_ID`, and only fall back to
-  `GABS_BRIDGE_PATH` or `~/.gabs/<gameId>/bridge.json`.
+  game with a short active-owner lease. You can hop between live sessions:
+  `games_connect` takes over naturally after the previous session goes idle,
+  while active game-bound calls are still protected from competing sessions.
+- **Game bridge cannot find GABP configuration**: the game-side bridge should read
+  `GABP_SERVER_PORT`, `GABP_TOKEN`, and `GABS_GAME_ID` from its process
+  environment. The `bridge.json` file is GABS' endpoint cache/debug artifact,
+  not runtime input for game-side bridge code.
+- **Stopped game still has `bridge.json`**: this is normal. Treat it as an
+  endpoint cache/debug artifact, not a recovery target.
+- **Start says the endpoint cache port is already in use**: use
+  `games_connect` if an existing game-side bridge owns that endpoint. Use
+  `games_start` with `resetEndpoint: true` only after confirming the cache
+  should be rotated for a new process.
 - **Confusing bridge state**: start with `games_status`. It compares the
-  runtime file, bridge file, passive listener evidence, and process environment
-  where the OS allows it, then returns diagnosis details and next actions.
+  runtime state and process environment where the OS allows it. If a launcher
+  reused old GABP environment, GABS can connect through the running process
+  endpoint with `games_connect`.
 
 ## How It Works
 
@@ -229,10 +239,8 @@ Want your game to work with GABS? Add GABP support to your game-side bridge:
    - `GABS_GAME_ID` - Your game's identifier
    - `GABP_SERVER_PORT` - Port your game-side bridge should listen on
    - `GABP_TOKEN` - Authentication token for GABS connections
-   - `GABS_BRIDGE_PATH` - Optional `bridge.json` fallback/debug path
-   Environment values are authoritative when present. `bridge.json` is a
-   fallback/debug file so agents can recover or inspect state, not an override
-   for fresh `GABP_*` values.
+   The `bridge.json` file is GABS' endpoint cache/debug artifact. Do not read
+   it as game-side runtime configuration.
 2. **Start a local GABP server** to listen for GABS connections (your game-side bridge = server, GABS = client)
 3. **Implement the current GABP runtime methods** (`session/hello`, `tools/list`, `tools/call`) or use the official `gabp-runtime` library so your schemas match what GABS expects
    - For GABP v1.1 bridges, advertise optional attention support through capabilities before exposing `attention/current`, `attention/ack`, and the attention lifecycle channels

docs/AI_CLIENT_SETUP.md

@@ -138,8 +138,9 @@ args = ["server"]
 On Windows, use the full path to `gabs.exe`.
 
 Each live Codex session starts its own stdio GABS process. That is normal.
-GABS coordinates ownership per game so two live AI sessions do not both launch
-or attach to the same game by accident.
+GABS coordinates ownership per game with a short active-owner lease. You can
+hop between live sessions: `games_connect` takes over once the previous session
+is idle, while active game-bound calls are protected from competing sessions.
 
 ### Generic MCP Clients
 
@@ -231,9 +232,9 @@ Once your AI client is connected, try prompts like:
 - "Show the status of all games"
 - "Reconnect to AdventureGame and list its tools"
 
-If you have more than one live GABS session, the second session will not launch
-or connect to the same game again by default. To intentionally move ownership
-to the current session, use:
+If you have more than one live GABS session, use `games_connect` in the session
+you want to continue from. It will take ownership when the previous session's
+active lease is idle. To override an actively owned game immediately, use:
 
 ```json
 {
@@ -257,15 +258,17 @@ Per-game runtime files live under:
 - `~/.gabs/<gameId>/bridge.json`
 - `~/.gabs/<gameId>/runtime.json`
 
-`bridge.json` is fallback/debug bridge metadata. The game-side bridge should prefer
-`GABP_SERVER_PORT`, `GABP_TOKEN`, and `GABS_GAME_ID` from its process
-environment when those values exist. `runtime.json` is internal ownership
-tracking used by GABS itself.
+`bridge.json` is GABS' endpoint cache/debug artifact. The game-side bridge
+should read `GABP_SERVER_PORT`, `GABP_TOKEN`, and `GABS_GAME_ID` from its
+process environment. `runtime.json` is internal ownership tracking used by GABS
+itself.
 
 If these files look confusing, call `games_status` before editing them by hand.
-The structured `diagnostics` field reports stale runtime files, stale bridge
-files, passively detected orphan listeners, missing bridge files, and launcher
-environment mismatches, with `nextActions` for recovery.
+The structured `diagnostics` field reports runtime ownership and process
+environment readability with `nextActions` for recovery. Do not inspect or edit
+`bridge.json` as a recovery step; use `games_connect` for an already-running
+endpoint or `games_start` with `resetEndpoint: true` only after confirming the
+endpoint cache should be rotated.
 
 ## Troubleshooting
 
@@ -286,20 +289,13 @@ gabs games show <game-id>
 Launcher-based games such as Steam and Epic titles need the actual game process
 name, not just the launcher.
 
-### A Bridge Cannot Find `bridge.json`
+### A Bridge Cannot Find Configuration
 
-Make sure the game-side bridge first checks the environment variables:
+Make sure the game-side bridge checks the environment variables:
 
 - `GABP_SERVER_PORT`
 - `GABP_TOKEN`
 - `GABS_GAME_ID`
 
-and only falls back to:
-
-- `~/.gabs/<gameId>/bridge.json`
-
-or the `GABS_BRIDGE_PATH` environment variable when present.
-
-Do not patch game-side bridge code to prefer `bridge.json` over present `GABP_*`
-environment variables. That can make an old bridge file win over the actual
-running process state.
+Do not patch game-side bridge code to read `bridge.json`. That can make GABS'
+endpoint cache win over the actual running process state.

docs/AI_DYNAMIC_TOOLS_FAQ.md

@@ -188,21 +188,31 @@ console.log("Here are all available tools..."); // Group by game instead!
 3. **Discovery APIs**: `games_tool_names` and `games_tool_detail` provide structured exploration
 4. **Status Awareness**: AI can check game state before tool usage
 5. **Mirror System**: Automatic GABP→MCP tool conversion
-6. **Session Ownership Guardrails**: Duplicate `games_start` and `games_connect`
-   requests return quickly instead of racing a second live GABS session
+6. **Session Ownership Guardrails**: Duplicate `games_start`, active
+   `games_connect`, and game-bound calls return quickly instead of racing a
+   second live GABS session
 
 ## What About Multiple GABS Sessions?
 
 This matters in the real world because developers often have more than one AI
 session open.
 
-- If one live GABS session already owns a running or starting game,
+- If one live GABS session actively owns a running or starting game,
   `games_start` returns quickly instead of launching a duplicate process
 - `games_connect` also returns quickly instead of hanging on a competing bridge
-  connection
-- `games_status` can report that another GABS session owns the process
-- If takeover is intentional, `games_connect {"gameId": "adventure",
-  "forceTakeover": true}` moves ownership to the current session
+  connection while the active owner lease is still open
+- once the previous session is idle, `games_connect` moves ownership to the
+  current session without `forceTakeover`
+- game-bound calls from old sessions are blocked while another active owner
+  holds the lease
+- `games_status` can report that another GABS session owns the process and show
+  the lease expiry
+- if `games_start` reports `endpoint_cache_in_use`, use `games_connect` to
+  attach to the already-listening endpoint or `resetEndpoint: true` only after
+  confirming the endpoint cache should be rotated
+- if takeover is intentional before the active lease expires,
+  `games_connect {"gameId": "adventure", "forceTakeover": true}` moves
+  ownership to the current session
 
 ### Current State
 - **Stable public tool list is live**: mirrored game tools no longer require

docs/CONFIGURATION.md

@@ -72,21 +72,23 @@ Most users can skip this section.
 
 GABS uses local-only GABP communication for security and simplicity.
 
-When you start a game, GABS passes bridge configuration to the game-side bridge through:
+When you start a game, GABS passes GABP connection data to the game-side bridge through:
 
 1. Environment variables: `GABP_SERVER_PORT`, `GABP_TOKEN`, `GABS_GAME_ID`
-2. A bridge file fallback: `~/.gabs/{gameId}/bridge.json`
 
-The environment variables are authoritative when present. `bridge.json` is a
-fallback/debug artifact for reconnects and diagnostics; game-side bridge code
-should not let a stale bridge file override fresh `GABP_*` environment values.
+The `bridge.json` file is GABS' endpoint cache/debug artifact. Game-side bridge
+code should not read it as runtime configuration or use it as a fallback for
+missing `GABP_*` environment values.
 
 In the GABP layer, your game-side bridge listens for the connection and GABS connects
 to it.
 
 GABS also keeps an internal ownership record at `~/.gabs/{gameId}/runtime.json`
-so separate GABS sessions do not accidentally launch or attach to the same game
-at the same time. Game integrations should ignore `runtime.json`; it is for GABS itself.
+so separate GABS sessions do not accidentally launch or drive the same game at
+the same time. Ownership is an expiring active-use lease, so you can hop
+between live AI sessions by using `games_connect` after the previous session
+goes idle. Game integrations should ignore `runtime.json`; it is for GABS
+itself.
 
 ## Managing Your Games
 
@@ -184,9 +186,8 @@ not passed to the game in this mode. Put launch options such as
 
 In launcher-driven setups, an already-running platform launcher process can
 prevent GABS from proving that new environment variables reached the real game
-process. `games_status` reports this as bridge-state diagnostics, including
-stale launcher environment when the process `GABP_*` values disagree with
-`bridge.json`. For deterministic env and argument control, use `DirectPath` or
+process. `games_status` reports whether the real game process environment is
+readable. For deterministic env and argument control, use `DirectPath` or
 `CustomCommand`.
 
 ### EpicAppId
@@ -223,35 +224,40 @@ GABS uses local-only GABP communication.
 ### Local Communication (Current Implementation)
 - GABS connects to game integrations on localhost (`127.0.0.1`) only
 - Each game gets a unique port and token
-- Bridge configuration is also written to `~/.gabs/{gameId}/bridge.json`
+- GABS may write `~/.gabs/{gameId}/bridge.json` as an endpoint cache/debug artifact
 
 ### Bridge Configuration
-When you start a game, GABS creates a bridge configuration file that looks like this:
+When you start a game, GABS sends GABP configuration through environment
+variables:
 
-```json
-{
-  "port": 49234,
-  "token": "a1b2c3d4e5f6...",
-  "gameId": "factory"
-}
-```
+- `GABP_SERVER_PORT`
+- `GABP_TOKEN`
+- `GABS_GAME_ID`
 
-Game integrations can read this file, but environment variables remain the preferred source.
+Game integrations should read these environment variables directly.
 
 ## Shared Runtime Ownership
 
 When a game is already starting or running, GABS writes a per-game
-`runtime.json` file so other live GABS sessions can see that the game already
-has an owner.
+`runtime.json` file so other live GABS sessions can see whether the game
+currently has an active owner.
 
 - A second `games.start` returns immediately with "already starting" or
   "already running" instead of launching a second copy
-- A second `games.connect` also returns immediately instead of waiting for a
-  competing bridge connection
-- `games.status` can report that another GABS session owns the process
+- `games.connect` takes ownership naturally once the previous owner's lease is
+  idle
+- `games.connect` returns immediately with an active-owner result when another
+  session is still inside its lease
+- game-bound tool calls also check the lease before touching the bridge
+- `games.status` reports the runtime owner, lease expiry, and bridge diagnostics
 
-If you intentionally want a different GABS session to take over a running game,
-use `games.connect` with `forceTakeover: true`.
+If you intentionally want a different GABS session to take over before the
+active lease expires, use `games.connect` with `forceTakeover: true`.
+
+If `games.start` reports `endpoint_cache_in_use`, the cached port is already
+listening. Use `games.connect` if an already-running bridge owns that endpoint.
+Use `games.start` with `resetEndpoint: true` only after confirming the cached
+endpoint should be rotated for a new process.
 
 ## Tool Normalization Configuration
 
@@ -325,25 +331,36 @@ tool metadata, including output schema information, remains available through
 ## Startup Timeout Configuration
 
 If your game takes longer to appear in the process list or longer for its GABP
-game-side bridge to start listening, you can override the startup waits in
-`~/.gabs/config.json`.
+game-side bridge to start listening, you can override the startup process wait
+and connection budget in `~/.gabs/config.json`.
 
 ### Startup Timeout Options
 
 The `timeouts.startup` section supports these options:
 
 - **`processStartSeconds`** (integer): How long GABS waits for the launched game
   process to become detectable in the OS process list (default: `10`)
-- **`gabpConnectSeconds`** (integer): How long `games.start` waits for the
-  game's GABP server to become available before returning control to you
-  (default: `60`). You can also pass a one-off `timeout` argument to
-  `games_start` for unusually slow bridge startup without changing the
-  saved configuration.
-
-`games_start` only waits for the GABP handshake. Mirroring the connected bridge's
-full tool list can continue briefly in the background. The public `tools/list`
-response stays stable, and known startup commands can be sent immediately
-through `games_call_tool` while discovery tools refresh.
+- **`gabpConnectSeconds`** (integer): The total connection budget for the game
+  GABP server to become available (default: `60`). `games_start` waits only for
+  a bounded initial slice of that budget, returns before MCP clients hit their
+  own tool-call timeout, and continues connecting in the background. You can
+  also pass a one-off `timeout` argument to `games_start` for unusually slow
+  bridge startup without changing the saved configuration.
+
+The `timeouts.session` section supports:
+
+- **`ownerLeaseSeconds`** (integer): How long an idle GABS session remains the
+  active runtime owner after a normal game-bound action (default: `30`). Long
+  game-bound calls extend the lease to cover their requested timeout plus a
+  small safety margin, so this value controls roaming between idle sessions,
+  not the maximum duration of a running command.
+
+`games_start` only waits for an initial GABP handshake window. If the game is
+still loading, GABS keeps trying in the background for the remaining startup
+budget. Mirroring the connected bridge's full tool list can continue briefly in
+the background. The public `tools/list` response stays stable, and known startup
+commands can be sent immediately through `games_call_tool` while discovery tools
+refresh.
 
 ### Example Configuration
 
@@ -354,6 +371,9 @@ through `games_call_tool` while discovery tools refresh.
     "startup": {
       "processStartSeconds": 20,
       "gabpConnectSeconds": 120
+    },
+    "session": {
+      "ownerLeaseSeconds": 30
     }
   },
   "games": {
@@ -426,10 +446,10 @@ mandatory.
 1. Make sure your game-side bridge supports GABP
 2. Check that the game-side bridge is listening on the right port
 3. Verify the game-side bridge is using `GABP_SERVER_PORT`, `GABP_TOKEN`, and `GABS_GAME_ID`
-   from the environment or `bridge.json`
+   from the environment
 4. Run `games_status` and inspect `diagnostics.code`, `diagnostics.message`,
-   and `nextActions`; it can identify stale runtime state, stale bridge files,
-   passively detected orphan listeners, and launcher environment mismatches.
+   and `nextActions`; it can identify stale runtime state, runtime ownership,
+   and whether the real game process environment is readable.
 
 ### "Configuration not found"
 The config file is created automatically when you add your first game. If it's missing, run `gabs games add` to create a new one.