@ai-digital-factory/lmt-cli 0.1.4 → 0.1.6

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.
@@ -51,7 +93,7 @@ Omitting `--date` asks Broker for the exchange's latest completed trading sessio
 
 Press Enter to submit each prompt. At the Operator password prompt, Escape returns to the username; Ctrl+U clears either field. Passwords remain masked. Press Ctrl+C to exit the terminal; use the logout command or menu action when you want to revoke the Operator Session.
 
-Interactive mode defaults to `--env local --profile default` when these options are omitted. Keep the same environment and profile across commands to reuse a session:
+Interactive mode defaults to `--env dev --profile default` when these options are omitted. A bare `live-market-terminal` invocation (no subcommand) also starts interactive mode with those defaults. Keep the same environment and profile across commands to reuse a session:
 
 ```sh
 lmt status --env dev --profile my-dev-session
@@ -242,8 +284,9 @@ 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 accessToken, expected (the metadata returned by token read),
-and optionally continueReplacement: true after reviewing an active-trading confirmation.
-A same-token submission verifies the submitter without reinstalling the token. Ordinary
+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,6 +14,30 @@ 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
 function isOperatorMarketProtection(value) {
   return typeof value === "number" && Number.isInteger(value) && value >= 2 && value <= 90;
@@ -28,6 +52,9 @@ var OPERATOR_SESSION_EXPIRY_TRACE_GRACE_SECONDS, OPERATOR_SESSION_EXPIRY_WARNING
 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;
@@ -82,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"
     };
   }
 });
@@ -248,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",
@@ -272,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",
@@ -291,13 +324,13 @@ function createGateApi(origin, fetchImpl = fetch, options = {}) {
       [...sessionSecrets(), ...otpValues]
     );
     rememberCookies(response);
-    await rejectAbsentSession(response, path4);
+    await rejectAbsentSession(response, path5);
     return response;
   }
-  async function settingsWrite(path4, body) {
+  async function settingsWrite(path5, body) {
     let response;
     try {
-      response = await fetchImpl(origin + path4, {
+      response = await fetchImpl(origin + path5, {
         method: "PUT",
         headers: headers({ "content-type": "application/json", accept: "application/json" }),
         body: JSON.stringify(body),
@@ -307,7 +340,7 @@ function createGateApi(origin, fetchImpl = fetch, options = {}) {
       throw new SettingsActionError("submission_uncertain", true);
     }
     rememberCookies(response);
-    await rejectAbsentSession(response, path4);
+    await rejectAbsentSession(response, path5);
     if (!response.ok) {
       const result = await readJson(response).catch(() => void 0);
       const codes = [
@@ -336,10 +369,46 @@ function createGateApi(origin, fetchImpl = fetch, options = {}) {
         "settings_recovery_required"
       ];
       const code = typeof result?.error === "string" && codes.includes(result.error) ? result.error : "operation_rejected";
-      throw new SettingsActionError(code, code === "settings_save_failed" || response.status >= 500);
+      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");
@@ -387,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();
@@ -611,21 +702,34 @@ function createGateApi(origin, fetchImpl = fetch, options = {}) {
   };
   return api;
 }
-var SettingsActionError, 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) {
-        super(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.");
+      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.");
@@ -1370,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";
 
@@ -2302,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
@@ -2604,6 +2817,7 @@ function splitHeadlessArgv(argv) {
   return { positional, options, credentialStdin, otpStdin };
 }
 function parseArguments(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") {
@@ -2739,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) {
@@ -2956,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);
@@ -3019,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 = error instanceof SettingsActionError ? { code: error.code, message: error.message, exitCode: 1 } : 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" || command?.kind === "settings" || command?.kind === "token" ? `${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.uncertain ? "uncertain" : 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),
@@ -3066,11 +3297,16 @@ function formatCliHelp() {
   return `Live Market Terminal CLI
 
 Usage (lmt is an alias of live-market-terminal):
+  live-market-terminal [--env local|dev] [--profile NAME]
   live-market-terminal interactive [--env local|dev] [--profile NAME]
   live-market-terminal interactive credential provision [--env local|dev] [--profile NAME]
   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
@@ -3087,16 +3323,26 @@ Usage (lmt is an alias of live-market-terminal):
 Headless options (--env, --profile, --timeout, --attempt, --otp-stdin, --credential-stdin) may appear before or after the command.
 
 From the monorepo root:
-  pnpm cli [--profile NAME]                       # interactive; --env defaults to local
+  pnpm cli [--profile NAME]                       # interactive; --env defaults to dev
   pnpm cli --env dev --profile my-dev-session
   pnpm -s cli:headless status --env local --profile default   # build step runs quietly (-s)
 
 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?} from protected stdin.
+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.
@@ -3120,9 +3366,14 @@ Exit codes (headless):
   4 validation blocked or Zerodha awaiting OTP
 
 Options:
-  --env local|dev       Target environment (interactive default: local; headless: required)
+  --env local|dev       Target environment (interactive default: dev; 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)
@@ -3139,6 +3390,11 @@ var CliInvocationError = class extends Error {
 function normalizeArgv(argv) {
   return argv[0] === "--" ? argv.slice(1) : argv;
 }
+function resolveCliInvocation(argv) {
+  if (argv.length === 0) return { kind: "interactive", argv: ["interactive"] };
+  if (argv[0] === "interactive") return { kind: "interactive", argv };
+  return { kind: "headless", argv };
+}
 async function bootstrapCli(dependencies = {}) {
   if (dependencies.runApplication) {
     await dependencies.runApplication();
@@ -3153,14 +3409,15 @@ async function bootstrapCli(dependencies = {}) {
     process.stdout.write(formatCliHelp());
     return;
   }
-  if (argv[0] !== "interactive") {
-    process.exitCode = await runHeadlessCli(argv);
+  const invocation = resolveCliInvocation(argv);
+  if (invocation.kind === "headless") {
+    process.exitCode = await runHeadlessCli(invocation.argv);
     return;
   }
   let parsed;
   let target;
   try {
-    parsed = parseInteractiveArguments(argv);
+    parsed = parseInteractiveArguments(invocation.argv);
     target = resolveCliTarget({ LMT_ENV: parsed.environment });
   } catch (error) {
     throw new CliInvocationError(error instanceof Error ? error.message : "Invalid interactive CLI configuration.");
@@ -3254,7 +3511,7 @@ function parseInteractiveArguments(argv) {
       if (flag === "--profile") profile2 = value;
     }
     assertClientProfileName(profile2);
-    return { environment: values2.has("--env") ? environment2 : "local", profile: profile2, credentialProvision: true };
+    return { environment: values2.has("--env") ? environment2 : "dev", profile: profile2, credentialProvision: true };
   }
   let environment = "";
   let profile = "default";
@@ -3271,10 +3528,10 @@ function parseInteractiveArguments(argv) {
     if (flag === "--profile") profile = value;
   }
   assertClientProfileName(profile);
-  return { environment: values.has("--env") ? environment : "local", profile, credentialProvision: false };
+  return { environment: values.has("--env") ? environment : "dev", 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.";
@@ -3286,5 +3543,6 @@ if (invokedFile && path3.resolve(fileURLToPath2(import.meta.url)) === realpathSy
 export {
   bootstrapCli,
   normalizeArgv,
-  parseInteractiveArguments
+  parseInteractiveArguments,
+  resolveCliInvocation
 };

package/package.json

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