@divebell/agent-browser 0.33.2-divebell.4 → 0.33.2-divebell.5

package/README.md

@@ -747,7 +747,7 @@ The profile directory stores:
 
 ## Session Persistence
 
-Use `--restore` with a stable `--session` to automatically save and restore cookies and localStorage across browser restarts:
+Use `--restore` with a stable `--session` to automatically save and restore cookies, localStorage, and sessionStorage across browser restarts. Restore State is a portable storage snapshot, not a complete Chrome Profile. A Profile also keeps IndexedDB, service workers, cache, extensions, browser preferences, and other Chrome-owned data.
 
 ```bash
 # Generate a stable id for this worktree and auto-save/load state
@@ -761,7 +761,11 @@ agent-browser --session "$SESSION" --restore open twitter.com
 agent-browser --session "$SESSION" --restore --restore-check-text Dashboard open twitter.com
 ```
 
-State is saved when the browser closes (explicit `close`, idle timeout, or daemon shutdown) and also periodically while the browser is open, so a browser window you close by hand still leaves a recent save behind. Periodic autosave waits for commands to settle, then saves at most once per `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` (default 30000; set to `0` to save only on close). Idle sessions keep saving on the same interval, so changes the page makes on its own (token refreshes, background requests) are captured too. It respects the `--restore-save` policy.
+The three save stages are independent. By default, agent-browser saves once after a newly launched page has been quiet for about two seconds, continues periodically while the browser is open, and saves again before explicit `close`, idle timeout, daemon shutdown, or a compatible relaunch. Disable a stage with `--restore-initial-save false`, `--restore-periodic-save false`, or `--restore-close-save false`. Periodic saves run at most once per `--restore-periodic-save-interval-ms` or `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` (default 30000); an interval of `0` disables only the periodic stage.
+
+Collecting localStorage and sessionStorage from more than one origin requires a disposable CDP target. agent-browser asks compatible browsers to create that target in the background and falls back when the CDP implementation does not support that option. In a headed browser that uses the fallback, an initial or periodic save can briefly show the temporary target. The original page is not refreshed. Disable only the post-launch save with `--restore-initial-save false` when this visual switch is undesirable; close saving remains enabled.
+
+`--restore-save auto|always|never` remains the higher-level safety policy. `auto` skips saving after restore or validation failure, `always` permits saving despite those failures, and `never` disables every stage. In contrast, disabling initial or periodic saving still preserves close-time saving unless `--restore-close-save false` is also set.
 
 ### State Encryption
 
@@ -779,7 +783,10 @@ agent-browser --session secure --restore open example.com
 | --------------------------------- | -------------------------------------------------- |
 | `AGENT_BROWSER_RESTORE`           | Auto-save/load state persistence name              |
 | `AGENT_BROWSER_RESTORE_SAVE`      | Restore save policy: `auto`, `always`, or `never`  |
-| `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` | Min ms between periodic autosaves (default: 30000, 0 disables) |
+| `AGENT_BROWSER_RESTORE_INITIAL_SAVE` | Enable the one-time post-launch save (default: true) |
+| `AGENT_BROWSER_RESTORE_PERIODIC_SAVE` | Enable periodic saves while open (default: true) |
+| `AGENT_BROWSER_RESTORE_CLOSE_SAVE` | Enable saves before close, shutdown, and relaunch (default: true) |
+| `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` | Min ms between periodic saves (default: 30000; 0 disables periodic only) |
 | `AGENT_BROWSER_NAMESPACE`         | Namespace for daemon sockets and restore state     |
 | `AGENT_BROWSER_SESSION_NAME`      | Legacy auto-save/load state persistence name       |
 | `AGENT_BROWSER_ENCRYPTION_KEY`    | 64-char hex key for AES-256-GCM encryption         |
@@ -948,6 +955,10 @@ This is useful for multimodal AI models that can reason about visual layout, unl
 | `--session <name>` | Use isolated session (or `AGENT_BROWSER_SESSION` env) |
 | `--restore [name]` | Auto-save/restore session state. Bare `--restore` uses `--session` as the key |
 | `--restore-save <policy>` | Restore save policy: `auto`, `always`, or `never` |
+| `--restore-initial-save <bool>` | Save once after the page is quiet for about two seconds (default: true) |
+| `--restore-periodic-save <bool>` | Continue saving periodically while open (default: true) |
+| `--restore-close-save <bool>` | Save before close, shutdown, or relaunch (default: true) |
+| `--restore-periodic-save-interval-ms <ms>` | Minimum periodic save interval (default: 30000; 0 disables periodic only) |
 | `--restore-check-url <glob>` | Validate restored state against a URL pattern |
 | `--restore-check-text <text>` | Validate restored state against page text |
 | `--restore-check-fn <js>` | Validate restored state against a truthy JavaScript expression |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@divebell/agent-browser",
-  "version": "0.33.2-divebell.4",
+  "version": "0.33.2-divebell.5",
   "description": "Browser automation CLI for AI agents with Divebell memory diagnostics",
   "type": "module",
   "engines": {

package/skill-data/core/SKILL.md

@@ -235,7 +235,9 @@ SESSION="$(agent-browser session id --scope worktree --prefix my-app)"
 agent-browser --session "$SESSION" --restore open https://app.example.com
 ```
 
-`--restore` with no value uses the current `--session` as the persistence key. Agent skills should prefer this over hand-built state file paths. Use `--restore-save auto` by default so a failed restore does not overwrite the previous known-good state. State is saved on close and also periodically while the browser is open (at most once per `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`, default 30000), so state survives even if the user closes the browser window by hand.
+`--restore` with no value uses the current `--session` as the persistence key. Agent skills should prefer this over hand-built state file paths. Restore State contains cookies, localStorage, and sessionStorage; it is not a complete Chrome Profile. Use `--restore-save auto` by default so a failed restore does not overwrite the previous known-good state.
+
+The initial, periodic, and close save stages are independent. agent-browser enables all three by default: it saves once after the launched page is quiet for about two seconds, continues at `--restore-periodic-save-interval-ms` intervals, and saves before close, shutdown, idle timeout, or compatible relaunch. Use `--restore-initial-save false` to avoid the initial cross-origin storage target, `--restore-periodic-save false` to stop background saves, or `--restore-close-save false` to suppress lifecycle saves. `--restore-save never` is stronger and disables every stage. The stage settings are attached to every command, so they also update an already-running daemon.
 
 ```bash
 agent-browser --session "$SESSION" --restore --restore-check-text Dashboard open https://app.example.com
@@ -450,6 +452,10 @@ EOF
 --state <path>          # load saved auth state from JSON
 --restore [name]        # auto-save/restore session state, defaults to --session
 --restore-save <policy> # auto, always, or never
+--restore-initial-save <bool> # one save after about two quiet seconds
+--restore-periodic-save <bool> # continue saving periodically
+--restore-close-save <bool> # save before close, shutdown, or relaunch
+--restore-periodic-save-interval-ms <ms> # periodic interval; 0 disables periodic only
 --namespace <name>      # isolate daemon sockets and restore-state directories
 ```
 

package/skill-data/core/references/session-management.md

@@ -57,7 +57,13 @@ SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)"
 agent-browser --session "$SESSION" --restore open https://app.example.com/dashboard
 ```
 
-When `--restore` or another restore key is configured, state is loaded before navigation and saved on close, daemon shutdown, idle timeout, and compatible relaunch. It is also saved periodically while the browser is open (after commands settle, at most once per `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`, default 30000; set to `0` to save only on close), so a browser window the user closes by hand still leaves a recent save behind. A session ID by itself only isolates the daemon and does not enable persistence; without a restore key, shutdown discards transient browser state and open tabs. Idle sessions with configured persistence keep saving on the same interval, capturing changes the page makes on its own such as token refreshes. The daemon exits after one hour without commands or dashboard input by default; `--idle-timeout <time>` or `AGENT_BROWSER_IDLE_TIMEOUT_MS` tunes this, and `0` disables it. Headed, Safari/iOS WebDriver, and user-attached browsers are exempt from the default timeout; provider-owned cloud browsers are not. The default save policy is `--restore-save auto`, which skips auto-save if restore failed or validation failed; `never` disables periodic autosave too.
+When `--restore` or another restore key is configured, state is loaded before navigation. Restore State contains cookies, localStorage, and sessionStorage; it is not a complete Chrome Profile and does not preserve IndexedDB, service workers, cache, extensions, or browser preferences.
+
+Three independent stages control saving. agent-browser enables all three by default: it saves once after a newly launched page is quiet for about two seconds, saves periodically while the browser remains open, and saves before close, daemon shutdown, idle timeout, or compatible relaunch. Use `--restore-initial-save false`, `--restore-periodic-save false`, or `--restore-close-save false` to disable an individual stage. The periodic interval comes from `--restore-periodic-save-interval-ms` or `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` (default 30000); `0` disables periodic saving only. The settings are included with every command and therefore update an already-running daemon.
+
+Cross-origin storage collection uses a disposable CDP target. agent-browser requests a background target and falls back for browsers that do not support the option. In a headed browser, the fallback can briefly show the temporary target; the original page is not refreshed. Disabling the initial stage avoids that post-launch switch while preserving close-time saving. The default higher-level policy is `--restore-save auto`, which skips saving after a failed restore or failed validation. `--restore-save never` disables all three stages, unlike disabling initial or periodic saving alone.
+
+A session ID by itself only isolates the daemon and does not enable persistence; without a restore key, shutdown discards transient browser state and open tabs. Idle sessions with periodic persistence enabled keep saving on the same interval, capturing page-driven changes such as token refreshes. The daemon exits after one hour without commands or dashboard input by default; `--idle-timeout <time>` or `AGENT_BROWSER_IDLE_TIMEOUT_MS` tunes this, and `0` disables it. Headed, Safari/iOS WebDriver, and user-attached browsers are exempt from the default timeout; provider-owned cloud browsers are not.
 
 ```bash
 agent-browser --session "$SESSION" --restore --restore-check-url "**/dashboard" open https://app.example.com/dashboard