@ai-digital-factory/lmt-web-cli 0.1.3 → 0.1.4

package/README.md

@@ -25,14 +25,15 @@ separately from `lmt-cli` and does not use profiles:
 npx --yes @ai-digital-factory/lmt-web-cli@latest credential provision --env dev --credential-stdin
 ```
 
-Start a fresh desktop session against Dev and keep the returned `sessionId` for every
+Start or restore a desktop session against Dev and keep the returned `sessionId` for every
 later command:
 
 ```sh
 npx --yes @ai-digital-factory/lmt-web-cli@latest start --env dev --device desktop
 ```
 
-The session starts on the Home Page. Use the same session to log into the Operator;
+A new session starts on the Home Page; a restored session follows Web’s existing
+authentication state. Use the same session to log into the Operator when required;
 if a Zerodha login is required, start that flow and submit the current OTP through
 standard input only, using the `attemptId` returned by `zerodha-login`:
 
@@ -68,7 +69,7 @@ complete command list.
 
 ## Install
 
-Requires Node.js 22 or later, Chromium, and a macOS or Linux session owner.
+Requires Node.js 22.13 or later, Chromium, and a macOS or Linux session owner.
 Install the CLI and its browser:
 
 ```sh
@@ -106,7 +107,8 @@ Use `--device desktop` for the 1440 × 900 desktop preset or `--headed` to show
 the browser window. Desktop uses scale 1, no touch emulation, and the installed
 Chromium runtime's desktop user agent. Results report the actual preset,
 viewport, scale, touch support, and user agent. Changing device or browser
-visibility requires a new session; these options are accepted only by `start`.
+visibility is selected by `start`. Mobile and desktop keep independent saved sessions.
+To change visibility for an already-live device, close its browser first or use `--fresh`.
 A visible browser requires an active desktop display. All automated browser tests
 run headlessly, including mobile and desktop acceptance. `pnpm test` requires no
 desktop display or Xvfb.
@@ -133,18 +135,70 @@ the page or taking a final screenshot. It also works after the browser window ha
 been closed manually. Supply the session ID returned by `start`; other sessions
 remain running. Like `close`, it does not log out or stop Broker activity.
 
-`start` opens the Home Page and returns a session ID. Every later command needs
-that ID and talks to the same local browser process without reloading the page.
-Concurrent commands within a session run in order. Different session IDs have
-separate in-memory browser contexts and storage. A session is owned by the local
-user who started it; closing it, losing its owner process, or restarting the
-machine requires a new session. The Web CLI does not import `lmt` cookies or
-save browser authentication. Closing a browser does not log out, revoke an
-Operator Session, or stop Broker activity.
+`start` automatically restores saved authentication for the selected environment,
+Web Origin, and device, or reuses that device's live browser and returns its session
+ID. Every later command needs that ID. Reusing a live browser preserves its current
+page; concurrent commands run in order. Separate mobile and desktop sessions each
+need their own initial login and restore independently thereafter.
+
+Closing, stopping, losing the owner process, or restarting the machine preserves
+saved authentication. A subsequent `start` creates a new browser owner and restores
+the same Operator Session cookies when still valid. Gate's expiry, daily-visit
+renewal, revocation, and per-Operator-Session Zerodha authentication remain authoritative.
+Restoration never submits credentials or starts an OTP Challenge. Results include
+`authentication.status` when a recognized Web surface is visible: `operator_login_required`,
+`zerodha_login_required`, or `authenticated`. Follow that state before logging in.
+
+Use `start --env dev --device desktop --fresh` for temporary, isolated login-flow
+testing. It neither reads nor overwrites the normal saved session, and its own
+login is not retained after closure. Closing a browser does not log out, revoke an
+Operator Session, or stop Broker activity. Explicit Zerodha logout is retained;
+Operator logout removes that browser's saved Operator Session. Neither logs out
+another device.
+
+The CLI saves only cookies applicable to the configured Web Origin, during the
+live session and before successful commands return. It does not persist page
+content, passwords, OTPs, localStorage, or third-party Kite cookies, and never imports
+`lmt` authentication. Saved cookies are replayable authentication stored in private
+SQLite files under `~/.lmt-web/sessions` (directory mode 0700, files 0600). Anyone
+acting as the same OS user can reuse them; keychain encryption is not required.
+`LMT_WEB_STATE_DIRECTORY` overrides the private parent directory for isolated setups.
+Unsafe ownership/permissions, symlinks, or corrupt state fail explicitly with
+`saved_session_unavailable`; there is no silent fallback that overwrites bad state.
+Cookies already committed before a process failure can be restored; a failure between
+a server change and its local checkpoint can still require login. Server-side logout
+or revocation cannot be reversed by an older saved cookie.
+
+Results distinguish action completion from the browser's authentication state.
+For example, a successful `operator-login` can return:
+
+```json
+{"outcome":"success","authentication":{"status":"zerodha_login_required","nextAction":"zerodha-login"}}
+```
+
+`authentication.status` is `operator_login_required`, `zerodha_login_required`,
+`zerodha_session_restoring`, `authenticated`, or `unknown`. It observes the
+rendered session surface, including Settings, rather than inferring admission
+from a URL or saved token presence.
+Unrecognized, conflicting, or unavailable page observations return `unknown`;
+a generic loading screen that exceeds the command deadline also returns
+`unknown` alongside the existing action error. `stop` has no page observation
+and returns `unknown`.
+
+When present, `authentication.nextAction` names `operator-login`, `zerodha-login`,
+or `zerodha-otp`. The OTP action includes `authentication.attemptId` for the active
+challenge, also available through `inspect`. It is omitted while an attempt is
+submitting or is no longer accepting OTPs; inspect the page and its error before
+deciding to retry. Supply the OTP through `--stdin` with that attempt ID in the
+same browser session. No login or OTP submission is performed by inspection.
+After successful OTP submission, `authentication.status` is `authenticated`.
+Keep that session alive for Market Watch and pairing QA; `lmt` authentication
+does not transfer to a new `lmt-web` session.
 
 Each command writes one versioned JSON result to stdout and diagnostics to
 stderr. Results contain the action outcome, current URL, visible page text and
-controls, emulated device and actual viewport, and screenshot outcome. Images
+controls, `authentication`, emulated device and actual viewport, and screenshot
+outcome. Images
 are written to unique absolute paths in an owner-only temporary directory;
 screenshots solid-mask only Zerodha access-token value fields marked with
 `data-lmt-sensitive="zerodha-access-token"`; other controls and metadata stay visible.
@@ -155,8 +209,11 @@ session-loading or busy indicators, fonts, visible images, and finite animations
 to finish. The page must render text, controls, or visual content; an empty app
 root is not ready. Pages that remain empty reach the command deadline without a
 captured screenshot. Infinite animations do not block capture. `--timeout` sets one deadline for the command's browser action and
-screenshot, from `1ms` through `10m`. If an operation exceeds it, the session is
-closed. Action failures return nonzero; invalid commands and targets return exit code 2.
+screenshot, from `1ms` through `10m`. A recoverable action timeout stops pending loading, waits for the operation to
+settle, and retains a responsive browser. Unsettled work, an unresponsive renderer,
+or an overall inspection/capture deadline can close the owner; use `start` to
+restore saved authentication. Submitted actions remain uncertain and are never
+automatically replayed. Action failures return nonzero; invalid commands and targets return exit code 2.
 The JSON `error.code` is machine-readable:
 
 | Code | Exit | Meaning |
@@ -165,7 +222,8 @@ The JSON `error.code` is machine-readable:
 | `browser_unavailable` | 1 | Install Chromium with `lmt-web install-browser`, then retry. |
 | `browser_start_failed` | 1 | The local browser owner exited before its session became ready. |
 | `service_unavailable` | 1 | The selected Web URL could not be reached; start/check that service. |
-| `session_not_found`, `session_unavailable` | 1 | The browser owner ended; start a fresh session. |
+| `session_not_found`, `session_unavailable` | 1 | The browser owner ended; use `start` to restore it. |
+| `saved_session_unavailable` | 1 | Check ownership, private permissions, and integrity of saved-session storage. |
 | `deadline_exceeded`, `action_failed` | 1 | The action failed or exceeded its finite deadline. |
 
 Screenshots cover the viewport by default. `inspect --full-page` and

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { spawn as spawn2 } from "node:child_process";
 import { createRequire } from "node:module";
-import path5 from "node:path";
+import path6 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // ../cli/src/profile-store.ts
@@ -477,6 +477,147 @@ function resolveCliTarget(env = process.env, configPath = DEFAULT_CONFIG_PATH) {
   };
 }
 
+// src/saved-session.ts
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants as constants2 } from "node:fs";
+import { lstat as lstat2, mkdir as mkdir2, open as open2 } from "node:fs/promises";
+import os from "node:os";
+import path3 from "node:path";
+import { DatabaseSync } from "node:sqlite";
+var SavedSessionError = class extends Error {
+  constructor() {
+    super("Could not access protected Web CLI session storage. Check its ownership, permissions, and integrity.");
+  }
+};
+async function assertPrivate(filename, directory) {
+  const entry = await lstat2(filename);
+  if ((directory ? !entry.isDirectory() : !entry.isFile()) || entry.isSymbolicLink() || entry.uid !== process.getuid?.() || (entry.mode & 511) !== (directory ? 448 : 384)) {
+    throw new SavedSessionError();
+  }
+}
+var SavedSession = class _SavedSession {
+  constructor(database, target) {
+    this.database = database;
+    this.target = target;
+  }
+  database;
+  target;
+  static async open(target) {
+    let database;
+    try {
+      const root = process.env.LMT_WEB_STATE_DIRECTORY || path3.join(os.homedir(), ".lmt-web");
+      await mkdir2(root, { recursive: true, mode: 448 });
+      await assertPrivate(root, true);
+      const directory = path3.join(root, "sessions");
+      await mkdir2(directory, { mode: 448 }).catch((error) => {
+        if (error.code !== "EEXIST") throw error;
+      });
+      await assertPrivate(directory, true);
+      const key = createHash("sha256").update(JSON.stringify([target.environment, target.origin, target.mode])).digest("hex");
+      const filename = path3.join(directory, `${key}.sqlite`);
+      const file = await open2(filename, constants2.O_CREAT | constants2.O_EXCL | constants2.O_WRONLY | constants2.O_NOFOLLOW, 384).catch((error) => {
+        if (error.code !== "EEXIST") throw error;
+      });
+      await file?.close();
+      await assertPrivate(filename, false);
+      database = new DatabaseSync(filename);
+      database.exec("PRAGMA busy_timeout = 25; PRAGMA secure_delete = ON;");
+      const store = new _SavedSession(database, target);
+      await store.reserve(Date.now() + 5e3, () => {
+        database.exec("CREATE TABLE IF NOT EXISTS session (id INTEGER PRIMARY KEY CHECK(id=1), state TEXT, owner TEXT)");
+        database.exec("INSERT OR IGNORE INTO session VALUES (1, NULL, NULL)");
+      });
+      return store;
+    } catch {
+      database?.close();
+      throw new SavedSessionError();
+    }
+  }
+  async reserve(deadlineAt, action) {
+    while (true) {
+      try {
+        this.database.exec("BEGIN IMMEDIATE");
+        break;
+      } catch (error) {
+        if (!/locked|busy/i.test(String(error)) || Date.now() >= deadlineAt) throw new SavedSessionError();
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      }
+    }
+    try {
+      const result = action();
+      this.database.exec("COMMIT");
+      return result;
+    } catch (error) {
+      this.database.exec("ROLLBACK");
+      throw error;
+    }
+  }
+  owner() {
+    try {
+      const row = this.database.prepare("SELECT owner FROM session WHERE id=1").get();
+      if (!row?.owner) return void 0;
+      const owner = JSON.parse(String(row.owner));
+      if (!/^[a-f0-9]{32}$/.test(owner.sessionId) || !Number.isSafeInteger(owner.pid) || owner.pid < 1 || typeof owner.headless !== "boolean" || typeof owner.processStartedAt !== "string") throw new SavedSessionError();
+      try {
+        process.kill(owner.pid, 0);
+      } catch (error) {
+        if (error.code !== "ESRCH") throw error;
+        return void 0;
+      }
+      try {
+        return this.processStartedAt(owner.pid) === owner.processStartedAt ? owner : void 0;
+      } catch {
+        try {
+          process.kill(owner.pid, 0);
+        } catch (error) {
+          if (error.code === "ESRCH") return void 0;
+        }
+        throw new SavedSessionError();
+      }
+    } catch {
+      throw new SavedSessionError();
+    }
+  }
+  processStartedAt(pid) {
+    const startedAt = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+      encoding: "utf8",
+      timeout: 1e3,
+      stdio: ["ignore", "pipe", "ignore"],
+      env: { ...process.env, LC_ALL: "C", TZ: "UTC" }
+    }).trim();
+    if (!startedAt) throw new SavedSessionError();
+    return startedAt;
+  }
+  setOwner(owner) {
+    this.database.prepare("UPDATE session SET owner=? WHERE id=1").run(JSON.stringify({ ...owner, processStartedAt: this.processStartedAt(owner.pid) }));
+  }
+  load() {
+    try {
+      const row = this.database.prepare("SELECT state FROM session WHERE id=1").get();
+      if (!row?.state) return void 0;
+      const state = JSON.parse(String(row.state));
+      if (!Array.isArray(state.cookies) || !Array.isArray(state.origins)) throw new Error();
+      return state;
+    } catch {
+      throw new SavedSessionError();
+    }
+  }
+  async save(state) {
+    const hostname = new URL(this.target.origin).hostname;
+    const scoped = {
+      cookies: state.cookies.filter((cookie) => cookie.domain === hostname || cookie.domain === `.${hostname}`),
+      origins: state.origins.filter((origin) => origin.origin === this.target.origin)
+    };
+    await this.reserve(Date.now() + 2e3, () => {
+      this.database.prepare("UPDATE session SET state=? WHERE id=1").run(JSON.stringify(scoped));
+    });
+  }
+  close() {
+    this.database.close();
+  }
+};
+
 // src/actions.ts
 var InvocationError = class extends Error {
   constructor(message, code = "invalid_invocation", action) {
@@ -493,7 +634,7 @@ function required(input, option) {
   return value;
 }
 var ACTIONS = {
-  start: { control: false, flags: ["--headed"], values: ["--env", "--device"], build: () => ({ action: "start" }) },
+  start: { control: false, flags: ["--headed", "--fresh"], values: ["--env", "--device"], build: () => ({ action: "start" }) },
   inspect: { control: false, flags: [], values: [], build: () => ({ action: "inspect" }) },
   close: { control: false, flags: [], values: [], build: () => ({ action: "close" }) },
   stop: { control: false, flags: [], values: [], build: () => ({ action: "stop" }) },
@@ -548,14 +689,14 @@ function isControlAction(action) {
 
 // src/config.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import path3 from "node:path";
+import path4 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-var repositoryRoot = path3.resolve(
-  path3.dirname(fileURLToPath2(import.meta.url)),
+var repositoryRoot = path4.resolve(
+  path4.dirname(fileURLToPath2(import.meta.url)),
   "../../../../"
 );
 var packagedConfig = fileURLToPath2(new URL("../lmt-web.config.json", import.meta.url));
-var DEFAULT_CONFIG_PATH2 = existsSync2(packagedConfig) ? packagedConfig : path3.join(repositoryRoot, "lmt.config.json");
+var DEFAULT_CONFIG_PATH2 = existsSync2(packagedConfig) ? packagedConfig : path4.join(repositoryRoot, "lmt.config.json");
 function canonicalOrigin(value, environment) {
   if (typeof value !== "string" || !value.trim()) {
     throw new Error(`lmt-web.config.json does not contain the ${environment} Web URL.`);
@@ -605,6 +746,7 @@ function failureResult(action, code, message, sessionId = null) {
     sessionId,
     action,
     outcome: "failure",
+    authentication: { status: "unknown" },
     url: null,
     visibleState: null,
     device: null,
@@ -615,10 +757,10 @@ function failureResult(action, code, message, sessionId = null) {
 
 // src/session.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
-import { chmod as chmod2, lstat as lstat2, mkdir as mkdir2, unlink as unlink2 } from "node:fs/promises";
+import { chmod as chmod2, lstat as lstat3, mkdir as mkdir3, unlink as unlink2 } from "node:fs/promises";
 import net from "node:net";
-import os from "node:os";
-import path4 from "node:path";
+import os2 from "node:os";
+import path5 from "node:path";
 import { chromium as chromium2 } from "playwright";
 
 // ../../packages/crawler/src/full-content.ts
@@ -1829,7 +1971,7 @@ async function operatorLogout(page, timeoutMs, onSubmit = () => void 0) {
 }
 
 // src/session.ts
-var SOCKET_DIRECTORY = path4.join(os.tmpdir(), `lmt-web-${process.getuid?.() ?? "user"}`);
+var SOCKET_DIRECTORY = path5.join(os2.tmpdir(), `lmt-web-${process.getuid?.() ?? "user"}`);
 var SESSION_ID_PATTERN = /^[a-f0-9]{32}$/;
 var OWNER_RESPONSE_GRACE_MS = 1e3;
 var OWNER_CLEANUP_GRACE_MS = 2e3;
@@ -1844,19 +1986,19 @@ async function ensureSessionDirectory() {
   if (process.platform === "win32") {
     throw new Error("lmt-web session sockets are supported on macOS and Linux.");
   }
-  await mkdir2(SOCKET_DIRECTORY, { recursive: true, mode: 448 });
+  await mkdir3(SOCKET_DIRECTORY, { recursive: true, mode: 448 });
   await chmod2(SOCKET_DIRECTORY, 448);
-  const directory = await lstat2(SOCKET_DIRECTORY);
+  const directory = await lstat3(SOCKET_DIRECTORY);
   const uid = process.getuid?.();
   if (!directory.isDirectory() || uid !== void 0 && directory.uid !== uid) {
     throw new Error("The lmt-web session directory is not owned by the invoking user.");
   }
 }
 function socketPathFor(sessionId) {
-  return path4.join(SOCKET_DIRECTORY, `${sessionId}.sock`);
+  return path5.join(SOCKET_DIRECTORY, `${sessionId}.sock`);
 }
 function artifactsDirectory(sessionId) {
-  return path4.join(SOCKET_DIRECTORY, "artifacts", sessionId);
+  return path5.join(SOCKET_DIRECTORY, "artifacts", sessionId);
 }
 function redactSecrets(value) {
   return value.replace(
@@ -1874,6 +2016,7 @@ function safeUrl(value) {
   }
 }
 function failureCode(error) {
+  if (error instanceof SavedSessionError) return "saved_session_unavailable";
   if (error instanceof ControlError) return error.code;
   const message = error instanceof Error ? error.message : "";
   if (/timed out|timeout|deadline/i.test(message)) return "deadline_exceeded";
@@ -1993,6 +2136,26 @@ async function inspectPage(page, mode, crawler) {
       const style = getComputedStyle(element);
       return rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
     };
+    const hasVisible = (selector) => Array.from(document.querySelectorAll(selector)).some(visible);
+    const operatorLogin2 = hasVisible('[data-operator-login-gate="true"]');
+    const zerodhaLogin = hasVisible('[data-zerodha-login-page="true"]');
+    const operatorPage = hasVisible('[data-operator-page="true"]');
+    const restoring = hasVisible('[data-zerodha-restoration="pending"]');
+    let authentication = { status: "unknown" };
+    if (Number(operatorLogin2) + Number(zerodhaLogin) + Number(operatorPage) + Number(restoring) === 1 && !hasVisible('[data-session-loading], [aria-busy="true"]')) {
+      if (operatorLogin2) authentication = { status: "operator_login_required", nextAction: "operator-login" };
+      if (operatorPage) authentication = { status: "authenticated" };
+      if (restoring) authentication = { status: "zerodha_session_restoring" };
+      if (zerodhaLogin) {
+        authentication = { status: "zerodha_login_required" };
+        const attempt = document.querySelector('[data-zerodha-login-page="true"] [data-operator-login-attempt]');
+        if (!attempt) authentication = { status: "zerodha_login_required", nextAction: "zerodha-login" };
+        else if (visible(attempt) && attempt.getAttribute("data-operator-login-status") === "awaiting_otp" && attempt.getAttribute("data-operator-login-submitting-otp") !== "true") {
+          const attemptId = attempt.getAttribute("data-operator-login-attempt-id");
+          if (attemptId) authentication = { status: "zerodha_login_required", nextAction: "zerodha-otp", attemptId };
+        }
+      }
+    }
     const controls2 = Array.from(
       document.querySelectorAll("button, a[href], input, select, textarea, [role=button]")
     ).filter(visible).slice(0, 100).map((element, index) => {
@@ -2006,6 +2169,7 @@ async function inspectPage(page, mode, crawler) {
       };
     });
     return {
+      authentication,
       title: document.title,
       text: document.body?.innerText ?? "",
       controls: controls2,
@@ -2019,6 +2183,7 @@ async function inspectPage(page, mode, crawler) {
   const redact = (value) => redactSecrets(crawler?.controls().redact(value) ?? value);
   const viewport = page.viewportSize?.() ?? result.viewport;
   return {
+    authentication: "attemptId" in result.authentication ? { ...result.authentication, attemptId: redact(result.authentication.attemptId) } : result.authentication,
     url: safeUrl(redact(page.url())),
     visibleState: {
       title: redact(result.title).slice(0, 300),
@@ -2047,12 +2212,12 @@ async function captureScreenshot(page, sessionId, action, fullPage, timeoutMs, o
   if (!page.screenshot) return { outcome: "failed", error: "The browser does not support screenshots." };
   const directory = artifactsDirectory(sessionId);
   const filename = `${Date.now()}-${action}-${randomBytes2(4).toString("hex")}.png`;
-  const screenshotPath = path4.resolve(directory, filename);
+  const screenshotPath = path5.resolve(directory, filename);
   if (timeoutMs < 1) {
     return { outcome: "failed", error: "The action deadline elapsed before screenshot capture." };
   }
   try {
-    await mkdir2(directory, { recursive: true, mode: 448 });
+    await mkdir3(directory, { recursive: true, mode: 448 });
     await chmod2(directory, 448);
     await withDeadline(
       (async () => {
@@ -2103,6 +2268,23 @@ async function runSessionOwner(options) {
   await ensureSessionDirectory();
   const socketPath = socketPathFor(options.sessionId);
   const device = deviceContext(options.mode);
+  const saved = options.persist ? await SavedSession.open({ environment: options.environment ?? "local", origin: options.origin, mode: options.mode }) : void 0;
+  const storageState = saved?.load();
+  let checkpointQueue = Promise.resolve();
+  let checkpointError;
+  function checkpoint() {
+    if (!saved || !page) return Promise.resolve();
+    const context = page.context();
+    const save = async () => {
+      const cookies = await context.cookies(options.origin);
+      await saved.save({ cookies, origins: [] });
+    };
+    checkpointQueue = checkpointQueue.then(save, save);
+    checkpointQueue.catch(() => {
+      checkpointError = new SavedSessionError();
+    });
+    return checkpointQueue;
+  }
   let crawler;
   let page;
   let startupError;
@@ -2112,6 +2294,7 @@ async function runSessionOwner(options) {
   let operationQueue = Promise.resolve();
   let shutdownPromise;
   let initializationPromise;
+  let startupLease;
   let crawlerClosePromise;
   let expirationCleanup;
   let forceClosePendingBrowser;
@@ -2164,7 +2347,12 @@ async function runSessionOwner(options) {
         return;
       }
       const run = async () => {
-        const response = await handleRequest(request);
+        let response;
+        try {
+          response = await handleRequest(request);
+        } catch (error) {
+          response = failureResult(request.action, error instanceof SavedSessionError ? "saved_session_unavailable" : "action_failed", "The browser action could not complete safely. Inspect before retrying.", options.sessionId);
+        }
         socket.end(`${JSON.stringify(response)}
 `);
         if (closing) socket.once("close", () => void shutdown());
@@ -2178,7 +2366,7 @@ async function runSessionOwner(options) {
         baseUrl: options.origin,
         headless: options.headless,
         timeoutMs: Math.min(options.timeoutMs, Math.max(1, remainingMs(deadlineAt))),
-        contextOptions: device.contextOptions,
+        contextOptions: { ...device.contextOptions, ...storageState ? { storageState } : {} },
         launch: () => {
           const onServerReady = (forceClose) => {
             forceClosePendingBrowser = forceClose;
@@ -2193,11 +2381,23 @@ async function runSessionOwner(options) {
         }
       });
       page = crawler.getPage();
+      if (saved) {
+        page.context().on("requestfinished", (request) => {
+          if (new URL(request.url()).origin !== options.origin) return;
+          void request.response().then(async (response) => {
+            const headers = await response?.allHeaders();
+            if (headers?.["set-cookie"] && !closing) await checkpoint();
+          }).catch(() => {
+            checkpointError = new SavedSessionError();
+          });
+        });
+      }
       if (closing) {
         await closeCrawler();
         return;
       }
       await crawler.openHomePage();
+      await withDeadline(checkpoint(), remainingMs(deadlineAt), expireSession);
     } catch (error) {
       startupError = error;
     }
@@ -2206,17 +2406,16 @@ async function runSessionOwner(options) {
     if (!request || request.sessionId !== options.sessionId || !isAction(request.action) || !Number.isFinite(request.timeoutMs) || request.timeoutMs < 1 || !Number.isFinite(request.deadlineAt)) {
       return failureResult("inspect", "invalid_request", "The session request was invalid.", options.sessionId);
     }
+    if (closing) return failureResult(request.action, "session_unavailable", "The browser owner is closing. Start to restore the saved session.", options.sessionId);
     const deadlineAt = request.deadlineAt;
     if (remainingMs(deadlineAt) === 0) {
       return failureResult(request.action, "deadline_exceeded", "The browser action exceeded its deadline.", options.sessionId);
     }
     if (request.action === "start" && startComplete) {
-      return failureResult("start", "session_already_started", "This browser session has already started.", options.sessionId);
-    }
-    if (!startComplete && request.action !== "start") {
-      return failureResult(request.action, "session_starting", "The browser session is not ready yet.", options.sessionId);
+      return { ...await handleRequest({ ...request, action: "inspect" }), action: "start" };
     }
     if (request.action === "stop") {
+      await withDeadline(checkpoint(), Math.min(500, Math.max(1, remainingMs(deadlineAt)))).catch(() => void 0);
       closing = true;
       abortOnShutdown = true;
       try {
@@ -2227,6 +2426,7 @@ async function runSessionOwner(options) {
           sessionId: options.sessionId,
           action: "stop",
           outcome: "success",
+          authentication: { status: "unknown" },
           url: null,
           visibleState: null,
           device: null,
@@ -2236,7 +2436,12 @@ async function runSessionOwner(options) {
         return failureResult("stop", failureCode(error2), messageFor(error2), options.sessionId);
       }
     }
+    if (!startComplete && request.action !== "start") {
+      return failureResult(request.action, "session_starting", "The browser session is not ready yet.", options.sessionId);
+    }
+    if (checkpointError) throw checkpointError;
     if (!startComplete) {
+      clearTimeout(startupLease);
       initializationPromise ??= initialize(deadlineAt);
       try {
         await withDeadline(initializationPromise, remainingMs(deadlineAt), expireSession);
@@ -2265,6 +2470,7 @@ async function runSessionOwner(options) {
         sessionId: options.sessionId,
         action: "start",
         outcome: actionError2 ? "failure" : "success",
+        authentication: inspected2?.authentication ?? { status: "unknown" },
         url: inspected2?.url ?? (startupError ? safeUrl(options.origin) : page ? safeUrl(crawler?.controls().redact(page.url()) ?? page.url()) : null),
         visibleState: inspected2?.visibleState ?? null,
         device: inspected2?.device ?? null,
@@ -2291,12 +2497,14 @@ async function runSessionOwner(options) {
     }
     let guidedError;
     let submitted = false;
-    const actionDeadlineAt = deadlineAt - Math.min(1500, Math.floor(remainingMs(deadlineAt) / 4));
-    let actionTimedOut = false;
-    const actionTimeout = () => Math.max(1, remainingMs(actionDeadlineAt));
-    const actionExpired = () => {
-      actionTimedOut = true;
+    const actionDeadlineAt = deadlineAt - Math.min(1500, Math.floor(remainingMs(deadlineAt) / 2));
+    const pendingActions = /* @__PURE__ */ new Set();
+    const runAction = (operation, timeoutMs) => {
+      pendingActions.add(operation);
+      operation.then(() => pendingActions.delete(operation), () => pendingActions.delete(operation));
+      return withDeadline(operation, timeoutMs);
     };
+    const actionTimeout = () => Math.max(1, remainingMs(actionDeadlineAt));
     page.setDefaultTimeout?.(actionTimeout());
     page.setDefaultNavigationTimeout?.(actionTimeout());
     let loginAttempt;
@@ -2305,16 +2513,16 @@ async function runSessionOwner(options) {
     };
     const zerodha = new PlaywrightZerodhaLoginPage(page, actionTimeout());
     try {
-      if (request.action === "operator-login") await withDeadline(operatorLogin({ page, environment: options.environment ?? "local", origin: options.origin, timeoutMs: actionTimeout(), onSubmit, registerSecrets: (...values) => crawler.controls().registerSecrets(...values) }), actionTimeout(), actionExpired);
-      if (request.action === "operator-logout") await withDeadline(operatorLogout(page, actionTimeout(), onSubmit), actionTimeout(), actionExpired);
-      if (request.action === "zerodha-login") loginAttempt = await withDeadline(zerodha.startLoginAttempt(onSubmit), actionTimeout(), actionExpired);
+      if (request.action === "operator-login") await runAction(operatorLogin({ page, environment: options.environment ?? "local", origin: options.origin, timeoutMs: actionTimeout(), onSubmit, registerSecrets: (...values) => crawler.controls().registerSecrets(...values) }), actionTimeout());
+      if (request.action === "operator-logout") await runAction(operatorLogout(page, actionTimeout(), onSubmit), actionTimeout());
+      if (request.action === "zerodha-login") loginAttempt = await runAction(zerodha.startLoginAttempt(onSubmit), actionTimeout());
       if (request.action === "zerodha-otp") {
         if (!request.attemptId || !request.otp || !/^\d{6}$/.test(request.otp)) throw new OperatorActionError("invalid_otp", "Supply a six-digit OTP and the attempt ID returned by zerodha-login.");
         crawler.controls().registerSecrets(request.otp);
-        const result = await withDeadline(zerodha.submitActiveOtp(request.attemptId, request.otp, onSubmit), actionTimeout(), actionExpired);
+        const result = await runAction(zerodha.submitActiveOtp(request.attemptId, request.otp, onSubmit), actionTimeout());
         if (result.status !== "SUCCESS") throw new OperatorActionError("otp_rejected", result.message);
       }
-      if (request.action === "zerodha-logout") await withDeadline(new PlaywrightOperatorPage(page, actionTimeout()).clickLogoutZerodha(onSubmit), actionTimeout(), actionExpired);
+      if (request.action === "zerodha-logout") await runAction(new PlaywrightOperatorPage(page, actionTimeout()).clickLogoutZerodha(onSubmit), actionTimeout());
     } catch (error2) {
       guidedError = error2;
     }
@@ -2324,9 +2532,9 @@ async function runSessionOwner(options) {
     try {
       if (isControlAction(request)) {
         const budget = Math.max(1, remainingMs(deadlineAt) - Math.min(2e3, request.timeoutMs / 4));
-        controlResult = await withDeadline(crawler.controls().act(request, budget, () => {
+        controlResult = await runAction(crawler.controls().act(request, budget, () => {
           submitted = true;
-        }), budget, () => void 0);
+        }), budget);
       }
     } catch (error2) {
       actionError = request.action === "click" && submitted && failureCode(error2) === "deadline_exceeded" ? new ControlError("action_uncertain", "The click may have been submitted but its completion was not confirmed. Inspect before deciding whether to retry.") : error2;
@@ -2334,6 +2542,25 @@ async function runSessionOwner(options) {
         await withDeadline(crawler.controls().stopLoading(), Math.min(500, remainingMs(deadlineAt))).catch(() => void 0);
       }
     }
+    if (pendingActions.size || failureCode(actionError ?? guidedError) === "deadline_exceeded") {
+      try {
+        await withDeadline((async () => {
+          await crawler.controls().stopLoading();
+          await Promise.allSettled([...pendingActions]);
+          await page.evaluate?.(() => document.readyState);
+        })(), Math.min(500, Math.max(1, remainingMs(deadlineAt))), expireSession);
+      } catch {
+        expireSession();
+        return { ...failureResult(request.action, submitted ? "action_uncertain" : "deadline_exceeded", "The browser could not safely recover from the action deadline. Start to restore the saved session; do not replay an uncertain action.", options.sessionId), outcome: submitted ? "uncertain" : "failure" };
+      }
+    }
+    if (saved) {
+      try {
+        await withDeadline(checkpoint(), Math.max(1, remainingMs(deadlineAt)), expireSession);
+      } catch (error2) {
+        actionError ??= error2;
+      }
+    }
     try {
       inspected = await withDeadline(inspectPage(page, options.mode, crawler), remainingMs(deadlineAt), expireSession);
     } catch (error2) {
@@ -2359,13 +2586,13 @@ async function runSessionOwner(options) {
         }
       }
     }
-    if (actionTimedOut) closing = true;
     const error = guidedError ?? actionError ?? closeError;
     return {
       version: RESULT_VERSION,
       sessionId: options.sessionId,
       action: request.action,
       outcome: error instanceof ControlError && error.code === "action_uncertain" ? "uncertain" : error ? submitted && !(error instanceof OperatorActionError) && !(error instanceof LoginAttemptError) ? "uncertain" : "failure" : "success",
+      authentication: inspected?.authentication ?? { status: "unknown" },
       ...!actionError ? controlResult : {},
       ...loginAttempt ? { loginAttempt: { attemptId: loginAttempt.attemptId, status: loginAttempt.status } } : {},
       url: inspected?.url ?? (page ? safeUrl(crawler?.controls().redact(page.url()) ?? page.url()) : null),
@@ -2378,6 +2605,7 @@ async function runSessionOwner(options) {
   function shutdown() {
     if (!closing) return Promise.resolve();
     if (shutdownPromise) return shutdownPromise;
+    clearTimeout(startupLease);
     shutdownPromise = (async () => {
       for (const socket of sockets) socket.destroy();
       await unlink2(socketPath).catch(() => void 0);
@@ -2404,6 +2632,7 @@ async function runSessionOwner(options) {
       }
       if (crawler) {
         try {
+          await withDeadline(checkpoint(), OWNER_CLEANUP_GRACE_MS);
           await closeCrawler();
         } catch {
           await crawler.forceClose?.().catch(() => void 0);
@@ -2411,6 +2640,8 @@ async function runSessionOwner(options) {
       } else if (forceClosePendingBrowser) {
         await forceCloseBrowser().catch(() => void 0);
       }
+      await withDeadline(checkpointQueue, OWNER_CLEANUP_GRACE_MS).catch(() => void 0);
+      saved?.close();
       process.removeListener("SIGTERM", onSignal);
       process.removeListener("SIGINT", onSignal);
     })();
@@ -2423,6 +2654,11 @@ async function runSessionOwner(options) {
       void chmod2(socketPath, 384).then(resolve, reject);
     });
   });
+  startupLease = setTimeout(() => {
+    if (initializationPromise) return;
+    expireSession();
+    void shutdown();
+  }, options.timeoutMs);
   const onSignal = () => {
     closing = true;
     void shutdown();
@@ -2434,7 +2670,7 @@ async function wait(milliseconds) {
   return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 function assertOwnedSocket(socketPath) {
-  return lstat2(socketPath).then((entry) => {
+  return lstat3(socketPath).then((entry) => {
     const uid = process.getuid?.();
     if (!entry.isSocket() || uid !== void 0 && entry.uid !== uid) {
       throw new Error("The lmt-web session socket is not owned by the invoking user.");
@@ -2515,7 +2751,7 @@ var HELP = `lmt-web \u2014 browser interaction with Live Market Terminal Web
 
 Usage:
   lmt-web install-browser [--with-deps] [--dry-run]
-  lmt-web start --env local|dev [--device mobile|desktop] [--headed] [--timeout 30s]
+  lmt-web start --env local|dev [--device mobile|desktop] [--headed] [--fresh] [--timeout 30s]
   lmt-web inspect --session ID [--full-page] [--timeout 30s]
   lmt-web click --session ID --ref REF
   lmt-web fill --session ID --ref REF --value TEXT [--secret]
@@ -2535,7 +2771,8 @@ Usage:
   lmt-web close --session ID [--full-page] [--timeout 30s]
   lmt-web stop --session ID [--timeout 30s]
 
-Start opens the configured Home Page in a fresh browser session. Mobile emulation
+Start restores the saved session or reuses its live browser. --fresh is temporary.
+Mobile emulation
 and headless mode are the defaults. Inspect and close require the returned session ID.
 Stop terminates the session's browser and owner without capturing a final screenshot.
 Each command writes one versioned JSON result to stdout; diagnostics go to stderr.
@@ -2601,6 +2838,7 @@ async function parseCommand(argv) {
       environment: values.get("--env") ?? "",
       mode,
       headless: !flags.has("--headed"),
+      fresh: flags.has("--fresh"),
       timeoutMs
     };
   }
@@ -2664,47 +2902,69 @@ async function startSession(command) {
     throw new InvocationError(error instanceof Error ? error.message : "The selected target is invalid.", "invalid_target");
   }
   await ensureSessionDirectory();
-  const sessionId = createSessionId();
-  const scriptPath = path5.resolve(process.argv[1] || fileURLToPath3(import.meta.url));
-  const child = spawn2(
-    process.execPath,
-    [
-      scriptPath,
-      "__owner",
-      sessionId,
-      target.origin,
-      command.mode,
-      command.headless ? "headless" : "headed",
-      String(command.timeoutMs),
-      target.environment
-    ],
-    {
-      detached: true,
-      stdio: "ignore"
+  const deadlineAt = Date.now() + command.timeoutMs;
+  const store = command.fresh ? void 0 : await SavedSession.open({ ...target, mode: command.mode });
+  let spawned;
+  try {
+    store?.load();
+    const selectOwner = () => {
+      const existing = store?.owner();
+      if (existing) {
+        if (existing.headless !== command.headless) throw new InvocationError("The saved session is already live with different visibility. Close it before changing --headed, or use --fresh.");
+        return existing;
+      }
+      const sessionId = createSessionId();
+      const scriptPath = path6.resolve(process.argv[1] || fileURLToPath3(import.meta.url));
+      const child = spawn2(process.execPath, [
+        scriptPath,
+        "__owner",
+        sessionId,
+        target.origin,
+        command.mode,
+        command.headless ? "headless" : "headed",
+        String(command.timeoutMs),
+        target.environment,
+        command.fresh ? "fresh" : "saved"
+      ], { detached: true, stdio: "ignore" });
+      spawned = child;
+      child.on("error", () => void 0);
+      child.unref();
+      if (!child.pid) throw new Error("Could not start the browser owner.");
+      const owner = { sessionId, pid: child.pid, headless: command.headless };
+      store?.setOwner(owner);
+      return owner;
+    };
+    while (Date.now() < deadlineAt) {
+      const owner = store ? await store.reserve(deadlineAt, selectOwner) : selectOwner();
+      const result = await requestSession({ sessionId: owner.sessionId, action: "start", timeoutMs: Math.max(1, deadlineAt - Date.now()) }, {
+        waitForSocket: true,
+        ownerAlive: () => {
+          try {
+            process.kill(owner.pid, 0);
+            return true;
+          } catch {
+            return false;
+          }
+        }
+      });
+      if (!store || !["session_not_found", "session_unavailable", "browser_start_failed"].includes(result.error?.code ?? "")) return result;
+      await new Promise((resolve) => setTimeout(resolve, 40));
     }
-  );
-  let ownerAlive = true;
-  child.once("error", () => {
-    ownerAlive = false;
-  });
-  child.once("exit", () => {
-    ownerAlive = false;
-  });
-  child.unref();
-  const result = await requestSession({ sessionId, action: "start", timeoutMs: command.timeoutMs }, {
-    waitForSocket: true,
-    ownerAlive: () => ownerAlive
-  });
-  if (result.outcome === "failure" && result.error?.code === "deadline_exceeded") {
-    try {
-      process.kill(child.pid, "SIGTERM");
-    } catch {
+    return failureResult("start", "deadline_exceeded", "The saved browser owner did not become available before the deadline.");
+  } catch (error) {
+    if (spawned?.pid) {
+      try {
+        process.kill(spawned.pid, "SIGTERM");
+      } catch {
+      }
     }
+    throw error;
+  } finally {
+    store?.close();
   }
-  return result;
 }
 async function runOwner(argv) {
-  const [sessionId, origin, modeValue, headlessValue, timeoutValue, environment] = argv;
+  const [sessionId, origin, modeValue, headlessValue, timeoutValue, environment, persistence] = argv;
   if (!isSessionId(sessionId) || !origin || modeValue !== "mobile" && modeValue !== "desktop" || headlessValue !== "headless" && headlessValue !== "headed" || !timeoutValue || !/^\d+$/.test(timeoutValue)) {
     process.exitCode = 2;
     return;
@@ -2715,7 +2975,8 @@ async function runOwner(argv) {
     environment: environment === "dev" ? "dev" : "local",
     mode: modeValue,
     headless: headlessValue === "headless",
-    timeoutMs: Math.min(Number(timeoutValue), MAX_TIMEOUT_MS)
+    timeoutMs: Math.min(Number(timeoutValue), MAX_TIMEOUT_MS),
+    persist: persistence === "saved"
   });
 }
 async function installBrowser(options) {
@@ -2728,7 +2989,7 @@ async function installBrowser(options) {
   }
   try {
     const require2 = createRequire(import.meta.url);
-    const browserCli = path5.join(path5.dirname(require2.resolve("playwright/package.json")), "cli.js");
+    const browserCli = path6.join(path6.dirname(require2.resolve("playwright/package.json")), "cli.js");
     const code = await new Promise((resolve, reject) => {
       const child = spawn2(process.execPath, [browserCli, "install", ...options, "chromium"], {
         stdio: ["ignore", "pipe", "pipe"]
@@ -2824,7 +3085,7 @@ async function runCli(argv) {
     }
   } catch (error) {
     const action = command?.action ?? (error instanceof InvocationError ? error.action : void 0) ?? (argv[0] === "inspect" || argv[0] === "close" ? argv[0] : "start");
-    const code = error instanceof InvocationError ? error.code : "action_failed";
+    const code = error instanceof SavedSessionError ? "saved_session_unavailable" : error instanceof InvocationError ? error.code : "action_failed";
     const message = error instanceof Error ? error.message : "The lmt-web command failed.";
     const result = failureResult(action, code, message);
     emit(result, `${code}: ${message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-digital-factory/lmt-web-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "bin": {
     "lmt-web": "dist/index.js"
@@ -10,7 +10,7 @@
   },
   "description": "Standalone browser session CLI for Live Market Terminal Web.",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13"
   },
   "files": [
     "dist",