@ai-digital-factory/lmt-cli 0.1.3 → 0.1.5

package/README.md

@@ -30,6 +30,48 @@ lmt candle-export NSE:IDEA --date 2026-10-23 --env dev --profile runner --timeou
 
 Omitting `--date` asks Broker for the exchange's latest completed trading session, accounting for holidays and Finalization Grace. The stdout JSON `candleExport` contains the immutable Hosted URL, filename, resolved identity/date, source availability, reference-fetch metadata, and comparison counts. Missing data or Zerodha authentication is explained in the workbook. Export does not start Zerodha login or token recovery. Local/dev only; see `lmt --help` for exit conventions.
 
+## Price Cross pairs for Runner
+
+Price Cross runs in Paper mode only. These commands reach the owning Broker through Gate with the saved Operator Session. They never save Settings, so the Settings Version does not change. They never place Orders, and the CLI has no strategy store or Kite client of its own.
+
+```sh
+lmt pair list --env dev --profile runner
+lmt pair assign --ce 1 --pe 3 --lots 2 --env dev --profile runner
+lmt pair report PAIR_ID --output ./pair.xlsx --env dev --profile runner
+lmt pair report PAIR_ID --publish --env dev --profile runner
+lmt pair unpair PAIR_ID --confirm --env dev --profile runner
+```
+
+| Command | Success JSON (one line on stdout) |
+|---|---|
+| `pair list` | `pairs.active` and `pairs.past`. Each pair has its globally unique `pairId`, `ceRow`/`peRow`, frozen `ceInstrument`/`peInstrument`, `pairLots`, `frozenLotSize`, `quantity`, `assignedAt`, `unpairedAt` (past pairs only) and `pnl` (exact per-leg, pair and daily Decision P&L). Ended pairs stay listed after their rows are reused. |
+| `pair assign` | `reason: "pair_assigned"` and `pair`, the Broker's summary with its identity, roles, frozen lot size and quantity. |
+| `pair unpair --confirm` | `reason: "unpaired"` with `unpair.requestedAt`. When a paper position was closed, `unpair.exit` holds the exit decision, including `requestedAt` and `fills[].priceMinute`. When the pair was flat there is no `exit`. A repeat gives `reason: "already_unpaired"`. |
+| `pair report` | Downloads the lifetime workbook unchanged. `report.path`, `report.bytes`, `report.sha256` and `report.decisionCount` describe it. Without `--output`, the file is saved under the server filename in the current directory and an existing file is never overwritten. |
+| `pair report --publish` | `report.url` is a new immutable Hosted URL. It matches the `exportUrl` field on the Broker's `price_cross_report_snapshot_published` log. Publishing again gives a new URL and leaves the old one unchanged. |
+
+Exit codes: 0 success; 1 refusal or uncertain; 2 invalid invocation (including `--env prod`); 3 Operator Login required.
+
+**Refusals.** A refusal is `outcome: "fail"` with exit 1, and `reason` and `error.code` both hold the Broker's code, unchanged. The codes are `invalid_lots` (Pair Lots outside 1 through the configured maximum, default 10), `same_type`, `already_paired`, `order_in_flight`, `real_position_open`, `row_unavailable`, `row_empty`, the `*_mismatch` codes, `flag_disabled`, `store_unavailable` and, for reports, `pair_not_found`. Each assign refusal matches the `fields_reason` on its `pair_refused` log. `pair unpair` without `--confirm` is refused locally with exit 2 and sends nothing.
+
+**Uncertain outcome.** If `pair assign`, `pair unpair` or `pair report --publish` is submitted but no answer arrives before `--timeout` (or Gate or Broker fails with a 5xx other than `store_unavailable`), the result is `outcome: "uncertain"`, `reason: "submission_uncertain"`, exit 1. The `recovery` field says to read `pair list`. The CLI never repeats the submission. Run `lmt pair list` to see whether the change happened before submitting again.
+
+### Dev-safe QA sequence
+
+Run this outside 09:15–15:30 IST, using a same-expiry CE row and PE row already applied on dev (rows 1 and 3 here).
+
+1. `lmt settings read …` and note `settingsVersion`.
+2. `lmt pair assign --ce 1 --pe 3 --lots 2 …`: exit 0. Record `pair.pairId`, `frozenLotSize` and `quantity`.
+3. Check the refusals: `--lots 0` and `--lots 11` give `invalid_lots`, re-running step 2 gives `already_paired`, and `--ce 1 --pe 1` gives `same_type`. Each exits 1.
+4. `lmt pair list …`: the pair is in `pairs.active`.
+5. `lmt pair report PAIR_ID --output ./pair.xlsx …`, then `lmt pair report PAIR_ID --publish …` twice. The two URLs differ, and each matches a `price_cross_report_snapshot_published` row.
+6. `lmt pair unpair PAIR_ID …` without `--confirm`: exit 2, and no `pair_unpaired` row is logged.
+7. `lmt pair unpair PAIR_ID --confirm …`: `unpaired`, with exit details or a flat removal. Repeat it: `already_unpaired`, and there is still only one `pair_unpaired` row.
+8. Uncertain: `lmt pair unpair PAIR_ID --confirm --timeout 1ms …` on a fresh pair either fails before submission or gives `uncertain` with exit 1. In both cases run `lmt pair list` to reconcile. The CI test `a submitted assign or unpair that outlives the timeout is uncertain, nonzero and never repeated` proves that exactly one submission is made.
+9. `lmt pair list …`: the pair is in `pairs.past`. `lmt settings read …` shows the same `settingsVersion` as step 1.
+
+Automated coverage: `pnpm --filter @ai-digital-factory/lmt-cli test` runs `src/pair-commands.test.ts` (stubbed Gate) and `integration/price-cross-pairs.test.ts`. The integration test uses real Gate and Broker, a temporary Price Cross Store and a recording order client that must see zero calls. It also covers flag-off: existing pairs are listed and can be Unpaired, and a new assign is refused with `flag_disabled`.
+
 ## Quick start: interactive dev login
 
 1. Obtain your Operator Login username and password. For headless login and Operator Session validation, also obtain an SMS read credential authorized to read `live-market-terminal-operator-directory` in the selected Gate scope from your administrator.
@@ -205,3 +247,46 @@ node .github/scripts/test-lmt-cli-package.mjs "$tarball"
 `lmt validate zerodha-session --env local --profile NAME` starts a new Broker-owned attempt and returns an attributed blocked report when a human OTP is needed. Resume with the same profile and explicit `--attempt ID`; add `--otp-stdin` to submit the protected human code. Without that flag, the supplied attempt is only observed. A pass requires authoritative attempt state followed by a hard session check; status alone does not pass the scenario. The resulting session stays available on the caller profile.
 
 Interactive **Validate Zerodha Session** runs the same scenario with masked OTP input and a visible report. **Resume Zerodha Validation** asks for an explicit attempt ID. Fresh validation can replace the Operator's active Broker attempt and successful login can refresh its shared token. CLI profile isolation does not isolate that shared state. See [local/dev validation smoke steps and recorded prerequisites](ZERODHA-SMOKE.md).
+
+## Settings and token commands for Runner
+
+Read ordinary Settings and their durable Settings Version with:
+
+```sh
+lmt settings read --env dev --profile runner
+```
+
+Save one intent by piping a single JSON object to protected stdin. Supply the version
+you reviewed and only the settings you intend to change. For example:
+
+```sh
+printf '%s\n' '{"expectedSettingsVersion":7,"entryCategories":[]}' |
+  lmt settings save --stdin --env dev --profile runner
+```
+
+An empty list disables all Entry Categories; omitted fields keep their saved values.
+Replacing credentials requires all four fields (userId, password, apiKey, apiSecret)
+inside a credentials object supplied through protected stdin. Keep secrets in an
+owner-readable input file or a protected pipe, never in command arguments or shell history.
+One changed save advances one Settings Version; a current unchanged save returns
+unchanged without a write. Every ordinary API write, including standalone credential
+saves, requires expectedSettingsVersion. Stale saves return settings_conflict; read
+Settings again and review the intended changes before submitting. A transport timeout
+after submission or an unconfirmed Broker save returns uncertain with exit code 1.
+Commands never retry a save. An ambiguous SMS write blocks authoritative Settings
+reads and further Operator-record writes until Broker restarts and reloads its durable
+record. The existing Market Watch resize recovery limitation still applies across stores.
+
+Access-token operations use a separate version and endpoint:
+
+```sh
+lmt token read --env dev --profile runner
+lmt token replace --stdin --env dev --profile runner < /path/to/protected-token-request.json
+```
+
+The token request contains expected (the metadata returned by token read), optionally
+accessToken for a new value, verifyCurrent: true to validate the saved token without
+reading its value, and continueReplacement: true after reviewing an active-trading
+confirmation. A same-token submission verifies the submitter without reinstalling the token. Ordinary
+Settings Save never replaces access tokens. Token values and saved credentials do not
+appear in command results.

package/dist/index.js

@@ -14,16 +14,62 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// ../../packages/contracts/src/price-cross.ts
+var init_price_cross = __esm({
+  "../../packages/contracts/src/price-cross.ts"() {
+    "use strict";
+  }
+});
+
+// ../../packages/contracts/src/price-cross-time.ts
+var IST_OFFSET_MS;
+var init_price_cross_time = __esm({
+  "../../packages/contracts/src/price-cross-time.ts"() {
+    "use strict";
+    IST_OFFSET_MS = 330 * 6e4;
+  }
+});
+
+// ../../packages/contracts/src/price-cross-live.ts
+var init_price_cross_live = __esm({
+  "../../packages/contracts/src/price-cross-live.ts"() {
+    "use strict";
+    init_price_cross_time();
+  }
+});
+
 // ../../packages/contracts/src/index.ts
-var OPERATOR_SESSION_EXPIRY_TRACE_GRACE_SECONDS, OPERATOR_SESSION_EXPIRY_WARNING_MS, DEFAULT_OPERATOR_SESSION_IDLE_HINT_SECONDS, ZERODHA_SESSION_ADMISSION_HEADER, ZERODHA_SESSION_ADMISSION_VERIFY, API_PATHS;
+function isOperatorMarketProtection(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 2 && value <= 90;
+}
+function validateEntryCategories(value) {
+  if (!Array.isArray(value) || value.some((category) => typeof category !== "string" || !ENTRY_CATEGORIES.includes(category)) || new Set(value).size !== value.length) {
+    throw new Error("entryCategories must be a list of supported Entry Categories with no duplicates.");
+  }
+  return [...value];
+}
+var OPERATOR_SESSION_EXPIRY_TRACE_GRACE_SECONDS, OPERATOR_SESSION_EXPIRY_WARNING_MS, DEFAULT_OPERATOR_SESSION_IDLE_HINT_SECONDS, ZERODHA_SESSION_ADMISSION_HEADER, ZERODHA_SESSION_ADMISSION_VERIFY, ENTRY_CATEGORIES, API_PATHS;
 var init_src = __esm({
   "../../packages/contracts/src/index.ts"() {
     "use strict";
+    init_price_cross();
+    init_price_cross_live();
+    init_price_cross_time();
     OPERATOR_SESSION_EXPIRY_TRACE_GRACE_SECONDS = 24 * 60 * 60;
     OPERATOR_SESSION_EXPIRY_WARNING_MS = 24 * 60 * 60 * 1e3;
     DEFAULT_OPERATOR_SESSION_IDLE_HINT_SECONDS = 7 * 24 * 60 * 60;
     ZERODHA_SESSION_ADMISSION_HEADER = "x-lmt-session-admission";
     ZERODHA_SESSION_ADMISSION_VERIFY = "verify";
+    ENTRY_CATEGORIES = [
+      "NSE EQ",
+      "BSE EQ",
+      "NFO FUT",
+      "NFO CE",
+      "NFO PE",
+      "BFO FUT",
+      "BFO CE",
+      "BFO PE"
+    ];
     API_PATHS = {
       health: "/api/health",
       unlockOperatorSession: "/api/operator-session/unlock",
@@ -37,6 +83,9 @@ var init_src = __esm({
       operatorLoginEvents: "/api/operators/login/events",
       operatorLoginOtp: "/api/operators/login/otp",
       cancelOperatorLogin: "/api/operators/login/cancel",
+      zerodhaAccessToken: "/api/zerodha/access-token",
+      zerodhaAccessTokenRecovery: "/api/zerodha/access-token/recovery",
+      zerodhaAccessTokenPublication: "/api/zerodha/access-token/publication",
       zerodhaCredentials: "/api/zerodha/credentials",
       entryCategorySettings: "/api/settings/entry-categories",
       operatorSettings: "/api/settings",
@@ -60,7 +109,13 @@ var init_src = __esm({
       placeMarketWatchOrder: "/api/market-watch/orders/place",
       retryMarketWatchPlace: "/api/market-watch/orders/place-retry",
       exitMarketWatchOrder: "/api/market-watch/orders/exit",
-      cancelMarketWatchOrder: "/api/market-watch/orders/cancel"
+      cancelMarketWatchOrder: "/api/market-watch/orders/cancel",
+      assignPriceCrossPair: "/api/price-cross/pairs/assign",
+      unpairPriceCrossPair: "/api/price-cross/pairs/unpair",
+      priceCrossReport: "/api/price-cross/report",
+      priceCrossReportShare: "/api/price-cross/report/share",
+      priceCrossPairs: "/api/price-cross/pairs",
+      priceCrossHistory: "/api/price-cross/history"
     };
   }
 });
@@ -226,17 +281,17 @@ function createGateApi(origin, fetchImpl = fetch, options = {}) {
     const timeout = options.timeoutMs && options.timeoutMs > 0 ? AbortSignal.timeout(options.timeoutMs) : void 0;
     return combineSignals2(options.signal, actionDeadlineSignal, explicitSignal, timeout);
   }
-  async function rejectAbsentSession(response, path4) {
-    if (response.status !== 401 || path4 === API_PATHS.unlockOperatorSession || path4 === API_PATHS.logoutUnauthenticatedOperator) return;
+  async function rejectAbsentSession(response, path5) {
+    if (response.status !== 401 || path5 === API_PATHS.unlockOperatorSession || path5 === API_PATHS.logoutUnauthenticatedOperator) return;
     const body = await readJson(response.clone());
     if (body && typeof body === "object" && "error" in body && body.error === "operator_session_absent") {
       delete cookies.operatorSessionCookie;
       throw new OperatorSessionRejectedError(rejectionReason(body));
     }
   }
-  async function postJson(path4, body, explicitSignal, secrets = []) {
+  async function postJson(path5, body, explicitSignal, secrets = []) {
     const signal = actionSignal(explicitSignal);
-    const url = `${origin}${path4}`;
+    const url = `${origin}${path5}`;
     const response = await requestOrThrow(
       () => fetchImpl(url, {
         method: "POST",
@@ -250,12 +305,12 @@ function createGateApi(origin, fetchImpl = fetch, options = {}) {
       [...sessionSecrets(), ...otpValues, ...secrets]
     );
     rememberCookies(response);
-    await rejectAbsentSession(response, path4);
+    await rejectAbsentSession(response, path5);
     return response;
   }
-  async function getJson(path4, explicitSignal, extraHeaders) {
+  async function getJson(path5, explicitSignal, extraHeaders) {
     const signal = actionSignal(explicitSignal);
-    const url = `${origin}${path4}`;
+    const url = `${origin}${path5}`;
     const response = await requestOrThrow(
       () => fetchImpl(url, {
         method: "GET",
@@ -269,10 +324,130 @@ function createGateApi(origin, fetchImpl = fetch, options = {}) {
       [...sessionSecrets(), ...otpValues]
     );
     rememberCookies(response);
-    await rejectAbsentSession(response, path4);
+    await rejectAbsentSession(response, path5);
+    return response;
+  }
+  async function settingsWrite(path5, body) {
+    let response;
+    try {
+      response = await fetchImpl(origin + path5, {
+        method: "PUT",
+        headers: headers({ "content-type": "application/json", accept: "application/json" }),
+        body: JSON.stringify(body),
+        signal: actionSignal()
+      });
+    } catch {
+      throw new SettingsActionError("submission_uncertain", true);
+    }
+    rememberCookies(response);
+    await rejectAbsentSession(response, path5);
+    if (!response.ok) {
+      const result = await readJson(response).catch(() => void 0);
+      const codes = [
+        "settings_conflict",
+        "settings_version_required",
+        "invalid_settings",
+        "trade_cycle_active",
+        "settings_save_failed",
+        "token_conflict",
+        "token_rejected",
+        "replacement_confirmation_required",
+        "token_write_pending",
+        "invalid_request",
+        "zerodha_session_absent",
+        "validation_failed",
+        "credentials_changed",
+        "replacement_blocked",
+        "token_changed",
+        "invalid_token_request",
+        "token_write_unresolved",
+        "active_trading_confirmation",
+        "validation_unavailable",
+        "unresolved_order",
+        "sharing_token_unavailable",
+        "token_recovery_unavailable",
+        "settings_recovery_required"
+      ];
+      const code = typeof result?.error === "string" && codes.includes(result.error) ? result.error : "operation_rejected";
+      const serverMessage = typeof result?.message === "string" && result.message.trim() ? result.message.trim() : void 0;
+      const relayMessage = serverMessage && (code === "token_rejected" || code === "validation_unavailable" || code === "invalid_token_request") ? serverMessage : void 0;
+      throw new SettingsActionError(code, code === "settings_save_failed" || response.status >= 500, relayMessage);
+    }
+    return response;
+  }
+  async function priceCrossMutation(path5, body, accept) {
+    let response;
+    try {
+      response = await fetchImpl(origin + path5, {
+        method: "POST",
+        headers: headers({ "content-type": "application/json", accept: "application/json" }),
+        body: JSON.stringify(body),
+        signal: actionSignal()
+      });
+    } catch {
+      throw new PriceCrossActionError("submission_uncertain", true);
+    }
+    rememberCookies(response);
+    await rejectAbsentSession(response, path5);
+    const parsed = await readJson(response);
+    if (response.ok) {
+      if (accept(parsed)) return parsed;
+      throw new PriceCrossActionError("submission_uncertain", true);
+    }
+    const refusal = priceCrossRefusal(parsed, response.status);
+    if (response.status >= 500 && refusal.code !== "store_unavailable") throw new PriceCrossActionError("submission_uncertain", true);
+    throw refusal;
+  }
+  function priceCrossRefusal(body, status) {
+    const result = body;
+    const code = typeof result?.error === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(result.error) ? result.error : `http_${status}`;
+    const message = typeof result?.message === "string" && result.message.trim() ? redactSecrets(result.message.trim(), sessionSecrets()) : void 0;
+    return new PriceCrossActionError(code, false, message);
+  }
+  async function priceCrossRead(path5, body) {
+    const response = body === void 0 ? await getJson(path5) : await postJson(path5, body);
+    if (!response.ok) throw priceCrossRefusal(await readJson(response), response.status);
     return response;
   }
+  function ordinarySettings(body) {
+    if (!body || !Number.isSafeInteger(body.settingsVersion) || !Number.isInteger(body.rowCount) || body.rowCount < 1 || body.rowCount > 20 || !isOperatorMarketProtection(body.marketProtection) || !Array.isArray(body.entryCategories)) {
+      throw new SettingsActionError("invalid_response");
+    }
+    return { settingsVersion: body.settingsVersion, rowCount: body.rowCount, marketProtection: body.marketProtection, entryCategories: validateEntryCategories(body.entryCategories) };
+  }
   const api = {
+    async getTokenMetadata() {
+      const response = await getJson(API_PATHS.zerodhaCredentials);
+      const body = await readJson(response);
+      if (!response.ok || !body?.accessTokenMetadata) throw new SettingsActionError("token_metadata_unavailable");
+      const { fingerprint, version, updatedAt, writePending } = body.accessTokenMetadata;
+      return { fingerprint, version, updatedAt, ...writePending === void 0 ? {} : { writePending } };
+    },
+    async getSettings() {
+      const response = await getJson(API_PATHS.operatorSettings);
+      if (!response.ok) throw new SettingsActionError("settings_read_failed");
+      return ordinarySettings(await readJson(response));
+    },
+    async saveSettings(request) {
+      const response = await settingsWrite(API_PATHS.operatorSettings, request);
+      try {
+        const body = await readJson(response);
+        if (body.outcome !== "saved" && body.outcome !== "unchanged") throw new Error("Invalid outcome");
+        return { outcome: body.outcome, settings: ordinarySettings(body.settings) };
+      } catch {
+        throw new SettingsActionError("submission_uncertain", true);
+      }
+    },
+    async replaceToken(request) {
+      const response = await settingsWrite(API_PATHS.zerodhaAccessToken, request);
+      try {
+        const body = await readJson(response);
+        if (body.outcome !== "verified" && body.outcome !== "replaced") throw new Error("Invalid outcome");
+        return { outcome: body.outcome, sharing: body.sharing, metadata: body.metadata, message: "Token operation completed." };
+      } catch {
+        throw new SettingsActionError("submission_uncertain", true);
+      }
+    },
     async exportCandles(request) {
       const response = await postJson(API_PATHS.candleExportOnDemand, request);
       const body = await readJson(response);
@@ -281,6 +456,28 @@ function createGateApi(origin, fetchImpl = fetch, options = {}) {
       }
       return body;
     },
+    async listPriceCrossPairs() {
+      const body = await readJson(await priceCrossRead(API_PATHS.priceCrossPairs));
+      if (!body || !Array.isArray(body.active) || !Array.isArray(body.past)) throw new PriceCrossActionError("invalid_response");
+      return { active: body.active, past: body.past };
+    },
+    assignPriceCrossPair(request) {
+      return priceCrossMutation(API_PATHS.assignPriceCrossPair, request, (body) => !!body && typeof body === "object" && "pair" in body && !!body.pair && typeof body.pair.pairId === "string");
+    },
+    unpairPriceCrossPair(request) {
+      return priceCrossMutation(API_PATHS.unpairPriceCrossPair, request, (body) => !!body && typeof body === "object" && "outcome" in body && (body.outcome === "unpaired" || body.outcome === "already_unpaired"));
+    },
+    async downloadPriceCrossReport(pairId) {
+      const response = await priceCrossRead(API_PATHS.priceCrossReport, { pairId });
+      const filename = /filename="([^"]+)"/.exec(response.headers.get("content-disposition") ?? "")?.[1];
+      const count = Number(response.headers.get("x-price-cross-decision-count"));
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      if (!filename || bytes.length === 0) throw new PriceCrossActionError("invalid_response");
+      return { bytes, filename, decisionCount: response.headers.has("x-price-cross-decision-count") && Number.isSafeInteger(count) ? count : null };
+    },
+    publishPriceCrossReport(pairId) {
+      return priceCrossMutation(API_PATHS.priceCrossReportShare, { pairId }, (body) => !!body && typeof body === "object" && "url" in body && typeof body.url === "string" && "filename" in body && typeof body.filename === "string");
+    },
     setActionSignal(signal) {
       actionDeadlineSignal = signal;
       if (!signal) otpValues.clear();
@@ -505,12 +702,34 @@ function createGateApi(origin, fetchImpl = fetch, options = {}) {
   };
   return api;
 }
-var OperatorSessionRejectedError, ZerodhaLoginFailedError, ZerodhaLoginAttemptUnavailableError, OperatorCredentialsRejectedError;
+var SettingsActionError, PRICE_CROSS_UNCERTAIN_MESSAGE, PriceCrossActionError, OperatorSessionRejectedError, ZerodhaLoginFailedError, ZerodhaLoginAttemptUnavailableError, OperatorCredentialsRejectedError;
 var init_gate_api_client = __esm({
   "src/gate-api-client.ts"() {
     "use strict";
     init_src();
     init_profile_name();
+    SettingsActionError = class extends Error {
+      constructor(code, uncertain = false, messageOverride) {
+        super(messageOverride ?? (uncertain ? "Submission could not be confirmed. Read current Settings or token metadata before another submission." : code === "settings_conflict" ? "Settings changed elsewhere. Read saved Settings and submit again with its version." : code === "active_trading_confirmation" ? "Another device has active trading. Review it, then explicitly submit continueReplacement: true to continue." : code === "token_changed" ? "The token changed. Read token metadata and review a fresh submission." : code === "token_write_unresolved" ? "A token write is unresolved. Resolve interrupted save in Web before replacing." : code === "unresolved_order" ? "An Order remains unresolved. Reconcile it before replacing the token." : "The Settings or token operation was rejected."));
+        this.code = code;
+        this.uncertain = uncertain;
+      }
+      code;
+      uncertain;
+    };
+    PRICE_CROSS_UNCERTAIN_MESSAGE = "Submission could not be confirmed and was not retried. Run pair list before another submission.";
+    PriceCrossActionError = class extends Error {
+      constructor(code, uncertain = false, message) {
+        super(message ?? (uncertain ? PRICE_CROSS_UNCERTAIN_MESSAGE : "The Price Cross request was rejected."));
+        this.code = code;
+        this.uncertain = uncertain;
+        this.name = "PriceCrossActionError";
+        if (uncertain) this.recovery = "Read current and past pairs with pair list; the CLI never repeats a submission.";
+      }
+      code;
+      uncertain;
+      recovery;
+    };
     OperatorSessionRejectedError = class extends Error {
       constructor(reason) {
         super("The saved Operator Session was rejected by Gate.");
@@ -1255,7 +1474,7 @@ var init_app = __esm({
 });
 
 // src/index.ts
-import path3 from "node:path";
+import path4 from "node:path";
 import { realpathSync } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
@@ -2187,6 +2406,115 @@ async function runZerodhaValidation(options) {
 
 // src/commands.ts
 init_zerodha_actions();
+
+// src/pair-commands.ts
+import { createHash } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import path3 from "node:path";
+var PairInvocationError = class extends Error {
+  code = "invalid_invocation";
+};
+var PAIR_USAGE = "Use pair list, pair assign --ce ROW --pe ROW --lots N, pair unpair PAIR_ID --confirm, or pair report PAIR_ID [--publish | --output PATH].";
+var VALUE_OPTIONS = /* @__PURE__ */ new Set(["--env", "--profile", "--timeout", "--ce", "--pe", "--lots", "--output"]);
+var FLAG_OPTIONS = /* @__PURE__ */ new Set(["--confirm", "--publish"]);
+var PAIR_ID = /^[A-Za-z0-9_-]{1,200}$/;
+function isPairInvocation(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--env" || token === "--profile" || token === "--timeout") {
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--")) continue;
+    return token === "pair";
+  }
+  return false;
+}
+function parsePairArguments(argv, parseTimeout2, validateProfile) {
+  const options = /* @__PURE__ */ new Map();
+  const flags = /* @__PURE__ */ new Set();
+  const positional = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (VALUE_OPTIONS.has(token)) {
+      const value = argv[index + 1];
+      if (value === void 0 || value.startsWith("--")) throw new PairInvocationError(`Invalid or incomplete command argument: ${token}`);
+      if (options.has(token)) throw new PairInvocationError(`Argument ${token} may be specified only once.`);
+      options.set(token, value);
+      index += 1;
+    } else if (FLAG_OPTIONS.has(token)) {
+      if (flags.has(token)) throw new PairInvocationError(`Argument ${token} may be specified only once.`);
+      flags.add(token);
+    } else if (token.startsWith("--")) {
+      throw new PairInvocationError(`Unsupported command option: ${token.split("=")[0]}`);
+    } else positional.push(token);
+  }
+  const [, action, pairId, ...extra] = positional;
+  const allowed = {
+    list: [],
+    assign: ["--ce", "--pe", "--lots"],
+    unpair: ["--confirm"],
+    report: ["--publish", "--output"]
+  };
+  if (!action || !(action in allowed) || extra.length > 0 || [...options.keys(), ...flags].some((key) => !["--env", "--profile", "--timeout", ...allowed[action]].includes(key))) {
+    throw new PairInvocationError(PAIR_USAGE);
+  }
+  const environment = options.get("--env"), profile = options.get("--profile");
+  if (!environment || !profile) throw new PairInvocationError("Headless commands require both --env local|dev and --profile NAME.");
+  validateProfile(profile);
+  const target = { environment, profile, ...options.has("--timeout") ? { timeoutMs: parseTimeout2(options.get("--timeout")) } : {} };
+  if (action === "list") {
+    if (pairId !== void 0) throw new PairInvocationError(PAIR_USAGE);
+    return { kind: "pair", action, ...target };
+  }
+  if (action === "assign") {
+    if (pairId !== void 0) throw new PairInvocationError(PAIR_USAGE);
+    const ce = options.get("--ce"), pe = options.get("--pe"), lots = options.get("--lots");
+    if (!ce || !pe || !lots || !/^\d{1,3}$/.test(ce) || !/^\d{1,3}$/.test(pe) || !/^-?\d{1,6}$/.test(lots)) {
+      throw new PairInvocationError("pair assign requires --ce ROW --pe ROW --lots N as whole numbers.");
+    }
+    return { kind: "pair", action, ceRow: Number(ce), peRow: Number(pe), pairLots: Number(lots), ...target };
+  }
+  if (!pairId || !PAIR_ID.test(pairId)) throw new PairInvocationError(`pair ${action} requires a Price Cross pair ID from pair list.`);
+  if (action === "unpair") {
+    if (!flags.has("--confirm")) {
+      throw new PairInvocationError("pair unpair requires --confirm. Unpair closes any paper position at its latest complete close.");
+    }
+    return { kind: "pair", action, pairId, ...target };
+  }
+  const publish = flags.has("--publish");
+  if (publish && options.has("--output")) throw new PairInvocationError("--output downloads the workbook; --publish returns a URL. Choose one.");
+  return { kind: "pair", action: "report", pairId, publish, ...options.has("--output") ? { output: options.get("--output") } : {}, ...target };
+}
+async function runPairCommand(command, api) {
+  if (command.action === "list") return { pairs: await api.listPriceCrossPairs() };
+  if (command.action === "assign") {
+    const { pair } = await api.assignPriceCrossPair({ ceRow: command.ceRow, peRow: command.peRow, pairLots: command.pairLots });
+    return { reason: "pair_assigned", pair };
+  }
+  if (command.action === "unpair") {
+    const { pairs: _pairs, ...unpair } = await api.unpairPriceCrossPair({ pairId: command.pairId, confirmExit: true });
+    return { reason: unpair.outcome, unpair: { pairId: command.pairId, ...unpair } };
+  }
+  if (command.publish) {
+    const published = await api.publishPriceCrossReport(command.pairId);
+    return { reason: "report_published", report: { pairId: command.pairId, published: true, url: published.url, filename: published.filename } };
+  }
+  const download = await api.downloadPriceCrossReport(command.pairId);
+  const output = path3.resolve(command.output ?? path3.basename(download.filename));
+  await writeFile(output, download.bytes, { flag: command.output ? "w" : "wx" });
+  return { reason: "report_downloaded", report: {
+    pairId: command.pairId,
+    published: false,
+    filename: download.filename,
+    path: output,
+    bytes: download.bytes.length,
+    sha256: createHash("sha256").update(download.bytes).digest("hex"),
+    decisionCount: download.decisionCount
+  } };
+}
+
+// src/commands.ts
 init_gate_api();
 
 // src/validation-scenario.ts
@@ -2489,7 +2817,24 @@ function splitHeadlessArgv(argv) {
   return { positional, options, credentialStdin, otpStdin };
 }
 function parseArguments(argv) {
-  const { positional, options, credentialStdin, otpStdin } = splitHeadlessArgv(argv);
+  if (!hasArgumentOtp(argv) && isPairInvocation(argv)) return parsePairArguments(argv, parseTimeout, validateCommandProfile);
+  const parsedInput = splitHeadlessArgv(argv.filter((value) => value !== "--stdin"));
+  const commandVerb = parsedInput.positional[0];
+  if (commandVerb === "settings" || commandVerb === "token") {
+    const stdin = argv.includes("--stdin");
+    if (argv.filter((value) => value === "--stdin").length > 1) throw new InvocationError("--stdin may be supplied only once.");
+    const parsed = parsedInput;
+    const [kind2, action] = parsed.positional;
+    if (parsed.positional.length !== 2 || parsed.credentialStdin || parsed.otpStdin || [...parsed.options.keys()].some((key) => !["--env", "--profile", "--timeout"].includes(key)) || !(kind2 === "settings" && (action === "read" && !stdin || action === "save" && stdin) || kind2 === "token" && (action === "replace" && stdin || action === "read" && !stdin))) {
+      throw new InvocationError("Use settings read, settings save --stdin, or token replace --stdin.");
+    }
+    const environment2 = parsed.options.get("--env"), profile2 = parsed.options.get("--profile");
+    if (!environment2 || !profile2) throw new InvocationError("Headless commands require --env local|dev and --profile NAME.");
+    validateCommandProfile(profile2);
+    return { kind: kind2, action, environment: environment2, profile: profile2, ...parsed.options.has("--timeout") ? { timeoutMs: parseTimeout(parsed.options.get("--timeout")) } : {} };
+  }
+  if (argv.includes("--stdin")) throw new InvocationError("--stdin is only supported for Settings save and token replacement.");
+  const { positional, options, credentialStdin, otpStdin } = parsedInput;
   if (positional[0] === "candle-export") {
     const instrument = positional[1]?.match(/^([A-Za-z][A-Za-z0-9]{0,31}):([^:\s]{1,100})$/);
     const date = options.get("--date");
@@ -2608,7 +2953,7 @@ function durationFor(command) {
 }
 function errorDetails(error, signal) {
   if (signal?.aborted) return { code: "deadline_exceeded", message: "The action exceeded its deadline.", exitCode: 1 };
-  if (error instanceof InvocationError || error instanceof ProtectedInputError) {
+  if (error instanceof InvocationError || error instanceof ProtectedInputError || error instanceof PairInvocationError) {
     return { code: error.code, message: error.message, exitCode: 2 };
   }
   if (error instanceof OperatorSessionRejectedError) {
@@ -2668,8 +3013,11 @@ async function readProtectedInput(stdin, signal, label = "SMS credential") {
 }
 async function runHeadlessCli(argv, dependencies = {}) {
   let otp;
+  let securePayload;
   const protect = (stream) => ({ write(chunk) {
-    return stream.write(otp ? chunk.replaceAll(otp, "[redacted]") : chunk);
+    let output = otp ? chunk.replaceAll(otp, "[redacted]") : chunk;
+    if (securePayload) output = output.replaceAll(securePayload, "[redacted]");
+    return stream.write(output);
   } });
   const streams = { stdout: protect(dependencies.stdout ?? defaultOut), stderr: protect(dependencies.stderr ?? defaultErr) };
   const started = performance.now();
@@ -2772,6 +3120,36 @@ async function runHeadlessCli(argv, dependencies = {}) {
       ...dependencies.readLoginCredentials ? { readLoginCredentials: dependencies.readLoginCredentials } : {}
     });
     actionApi = await actions.getApi();
+    if (command.kind === "settings" || command.kind === "token") {
+      await actions.status();
+      let payload;
+      if (command.action !== "read") {
+        securePayload = await readProtectedInput(dependencies.stdin ?? process.stdin, signal, "Settings JSON");
+        try {
+          payload = JSON.parse(securePayload);
+        } catch {
+          throw new InvocationError("Protected stdin must contain one JSON object.");
+        }
+        if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new InvocationError("Protected stdin must contain one JSON object.");
+      }
+      const settings = command.kind === "settings" ? command.action === "read" ? { outcome: "read", settings: await actionApi.getSettings() } : await actionApi.saveSettings(payload) : void 0;
+      const tokenMetadata = command.kind === "token" && command.action === "read" ? await actionApi.getTokenMetadata() : void 0;
+      const token = command.kind === "token" && command.action === "replace" ? await actionApi.replaceToken(payload) : void 0;
+      emit({
+        version: 1,
+        command: command.kind + " " + command.action,
+        outcome: "success",
+        reason: settings?.outcome ?? token?.outcome,
+        ...settings ? { settings: settings.settings } : {},
+        ...token ? { token } : {},
+        ...tokenMetadata ? { tokenMetadata } : {},
+        target: { environment: target.environment, origin: target.origin },
+        profile,
+        elapsedMs: Math.round(performance.now() - started),
+        metadata: { requestId: actionApi.responseMetadata().requestId ?? null, buildId: actionApi.responseMetadata().buildId ?? null }
+      }, streams);
+      return 0;
+    }
     if (command.kind === "candle-export") {
       await actions.status();
       const candleExport = await actionApi.exportCandles({
@@ -2792,6 +3170,22 @@ async function runHeadlessCli(argv, dependencies = {}) {
       }, streams);
       return 0;
     }
+    if (command.kind === "pair") {
+      await actions.status();
+      const result2 = await runPairCommand(command, actionApi);
+      emit({
+        version: 1,
+        command: `pair ${command.action}`,
+        outcome: "success",
+        ...result2,
+        target: { environment: target.environment, origin: target.origin },
+        profile,
+        observedOperator: target.operatorId,
+        elapsedMs: Math.round(performance.now() - started),
+        metadata: { requestId: actionApi.responseMetadata().requestId ?? null, buildId: actionApi.responseMetadata().buildId ?? null }
+      }, streams);
+      return 0;
+    }
     if (command.kind === "zerodha") {
       await actions.status();
       if (command.otpStdin) otp = await readProtectedOtp(dependencies.stdin ?? process.stdin, signal);
@@ -2855,17 +3249,18 @@ async function runHeadlessCli(argv, dependencies = {}) {
     if (error instanceof OperatorSessionRejectedError && store && actionApi && target && profile && !signal?.aborted) {
       await store.saveSession(profile, target, actionApi.getCookies()).catch(() => void 0);
     }
-    const details = errorDetails(error, signal);
+    const details = error instanceof SettingsActionError || error instanceof PriceCrossActionError ? { code: error.code, message: error.message, exitCode: 1 } : errorDetails(error, signal);
     const recovery = error instanceof Error ? error : void 0;
     const attemptId = recovery?.attemptId ?? (command?.kind === "zerodha" ? command.attemptId : void 0);
     emit({
       version: 1,
-      command: command?.kind === "zerodha" ? `zerodha ${command.action}` : command?.kind === "credential-provision" ? "credential provision" : command?.kind === "validate-zerodha" ? "validate zerodha-session" : command?.kind === "validate" ? "validate operator-session" : command?.kind ?? "",
-      outcome: details.exitCode === 4 ? "blocked" : "fail",
+      command: command?.kind === "zerodha" || command?.kind === "settings" || command?.kind === "token" || command?.kind === "pair" ? `${command.kind} ${command.action}` : command?.kind === "credential-provision" ? "credential provision" : command?.kind === "validate-zerodha" ? "validate zerodha-session" : command?.kind === "validate" ? "validate operator-session" : command?.kind ?? "",
+      outcome: (error instanceof SettingsActionError || error instanceof PriceCrossActionError) && error.uncertain ? "uncertain" : details.exitCode === 4 ? "blocked" : "fail",
       reason: details.code,
       ...target ? { target: { environment: target.environment, origin: target.origin } } : command ? { target: { environment: command.environment } } : {},
       ...profile ? { profile } : {},
       ...attemptId ? { attemptId, recovery: recovery?.recovery ?? "Observe this exact attempt with the same target and profile; start explicitly only if Gate reports it inactive." } : {},
+      ...!attemptId && error instanceof PriceCrossActionError && error.recovery ? { recovery: error.recovery } : {},
       ...recovery?.observedState ? { observedState: recovery.observedState } : {},
       ...recovery?.observedOperator ? { observedOperator: recovery.observedOperator } : {},
       elapsedMs: Math.round(performance.now() - started),
@@ -2878,6 +3273,7 @@ async function runHeadlessCli(argv, dependencies = {}) {
     return details.exitCode;
   } finally {
     otp = void 0;
+    securePayload = void 0;
     if (deadlineTimer) clearTimeout(deadlineTimer);
   }
 }
@@ -2906,6 +3302,14 @@ Usage (lmt is an alias of live-market-terminal):
   live-market-terminal login --env local|dev --profile NAME [--timeout DURATION]
   live-market-terminal logout --env local|dev --profile NAME [--timeout DURATION]
   live-market-terminal candle-export EXCHANGE:SYMBOL [--date YYYY-MM-DD] --env local|dev --profile NAME [--timeout DURATION]
+  live-market-terminal pair list --env local|dev --profile NAME [--timeout DURATION]
+  live-market-terminal pair assign --ce ROW --pe ROW --lots N --env local|dev --profile NAME [--timeout DURATION]
+  live-market-terminal pair unpair PAIR_ID --confirm --env local|dev --profile NAME [--timeout DURATION]
+  live-market-terminal pair report PAIR_ID [--publish | --output PATH] --env local|dev --profile NAME [--timeout DURATION]
+  live-market-terminal settings read --env local|dev --profile NAME
+  live-market-terminal settings save --stdin --env local|dev --profile NAME
+  live-market-terminal token read --env local|dev --profile NAME
+  live-market-terminal token replace --stdin --env local|dev --profile NAME
   live-market-terminal status --env local|dev --profile NAME [--timeout DURATION]
   live-market-terminal zerodha login --env local|dev --profile NAME [--timeout DURATION]
   live-market-terminal zerodha observe --attempt ID --env local|dev --profile NAME [--timeout DURATION]
@@ -2925,6 +3329,21 @@ From the monorepo root:
 Candle Export publishes a new immutable workbook link and returns its context in candleExport JSON.
 Empty or unavailable sources are explained in the workbook. Export never starts Zerodha login or token recovery.
 
+Price Cross pair commands operate Paper pairs on the owning Broker through Gate; they never save Settings or place Orders.
+pair list returns current and past pairs (JSON pairs.active / pairs.past). Broker refusals keep their reason codes
+(invalid_lots, same_type, already_paired, order_in_flight, flag_disabled, ...) with exit 1.
+pair unpair requires --confirm and returns exit details (unpair.exit) when a paper position closed; a repeat reports already_unpaired.
+pair report downloads the lifetime workbook (default: server filename in the current directory, never overwritten);
+--publish returns a new immutable Hosted URL instead.
+A pair assign, unpair or publish timeout after submission is uncertain (exit 1); read pair list before resubmitting.
+The CLI never repeats a submission.
+
+Settings save reads one JSON object from stdin: expectedSettingsVersion plus selected rowCount,
+marketProtection, entryCategories, or complete credentials. Omitted fields are preserved.
+Token replace reads {accessToken?, expected, continueReplacement?, verifyCurrent?} from protected stdin.
+Use verifyCurrent: true with expected from token read to validate the saved token without supplying accessToken.
+Read token metadata through token read. A timeout after submission is uncertain; never retry blindly.
+
 Targets: local and dev only. Production is not permitted.
 
 Zerodha login is two steps: zerodha login, then zerodha otp --attempt ID --otp-stdin.
@@ -2949,6 +3368,11 @@ Options:
   --env local|dev       Target environment (interactive default: local; headless: required)
   --profile NAME        Client profile (default: default for interactive)
   --timeout DURATION    Action deadline, e.g. 45s, 2m, 30000ms (headless)
+  --ce ROW / --pe ROW   Market Watch rows for pair assign (CE leg, PE leg)
+  --lots N              Pair Lots for pair assign; the Broker enforces 1 through its configured maximum
+  --confirm             Required by pair unpair
+  --publish             pair report: publish an immutable snapshot and return its URL
+  --output PATH         pair report: write the downloaded workbook to PATH (overwrites)
   --date YYYY-MM-DD     Single IST date for candle-export; omitted: latest completed exchange session
   --attempt ID          Attempt ID returned by zerodha login (required for observe and otp)
   --otp-stdin           Read one six-digit OTP line from piped protected stdin (maximum 8 bytes)
@@ -3100,7 +3524,7 @@ function parseInteractiveArguments(argv) {
   return { environment: values.has("--env") ? environment : "local", profile, credentialProvision: false };
 }
 var invokedFile = process.argv[1];
-if (invokedFile && path3.resolve(fileURLToPath2(import.meta.url)) === realpathSync(invokedFile)) {
+if (invokedFile && path4.resolve(fileURLToPath2(import.meta.url)) === realpathSync(invokedFile)) {
   ensureFetchIgnoresEnvProxy();
   bootstrapCli().catch((error) => {
     const message = error instanceof Error ? error.message : "CLI failed to start.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-digital-factory/lmt-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "bin": {
     "live-market-terminal": "dist/index.js",