gangtise-openapi-cli 0.26.0 → 0.27.0

package/README.md

@@ -4,6 +4,33 @@
 
 ## Changelog
 
+### v0.27.0 — 2026-07-11
+
+**EDE 指标（体验修复）**
+- `indicator` 三端点对 `999999` 不再自动重试——实测服务端用 `999999` + HTTP 500 表示「查询无数据」（节假日 / 未来日期 / 未覆盖标的），此前每次空查询白烧 3 个请求 + ~4 秒；错误提示改为指向检查查询条件而非「稍后重试」
+
+**资金与下载加固（承接 v0.26.0）**
+- 下载路径同样接入重试策略：50/篇 的 `summary` / `foreign-report` / `my-conference` download 改为 no-replay（与 AI Agent 同价档；下载中断重试可能重复计费），10-30/篇 的下载维持默认重试
+- 签名 URL 下载增加整体硬截止（10× 单请求超时）——headers/body 超时是空闲型，慢滴速传输可无限续命；最终 rename 失败时清理 `.part`
+- `GANGTISE_PAGE_CONCURRENCY` 防御性解析：非法/非正数回退默认 5、上限 32——负值此前被底层钳制成**单 worker 串行**（静默变慢），过大值可能造成过度并发触发限流
+- `--version` 更新提示改为数值分段版本比较（不处理预发布号；本项目只发 x.y.z）——刚发版的 registry 滞后窗口不再把旧版本提示成"可更新"
+
+**体验与正确性小修**
+- `--wait` 异步轮询容忍瞬态错误：5xx/网络抖动只消耗一次尝试并继续等待，不再作废整段等待（积分不足等终态错误仍立即中止）
+- table 输出单元格显示宽度上限 120（超长截断加 `…`）——一个超长字段不再把整列所有行 pad 成同宽（行数 × 宽度的空格放大）
+- markdown 输出先转义反斜杠再转义竖线，字面 `\|` 单元格不再错位列；table/markdown 过滤 C1 控制符（U+009B 单字节 CSI 注入面）
+- 自动文件名按码点截断，emoji 不再被截成 `�`；EDE 矩阵中与 `date`/`security`/`name` 同名的指标列自动加后缀，不再覆盖元数据列
+- 全市场分片截断时输出 `truncatedShards`（具体日期区间，与 `failedShards` 对称），脚本/AI 消费者可定向缩窗补拉
+- 分页端点首页形状漂移（如 `total` 变字符串）时 `--verbose` 下告警，不再完全静默退化单页
+
+**Skill 分发**
+- `gangtise-openapi/` 目录纳入 npm 包；README 安装命令改为从 `$(npm root -g)` 复制——此前的相对路径命令对 npm 用户不可执行
+
+**防漂移门禁（工程，不影响 CLI 行为）**
+- 新增 README↔ENDPOINTS 一致性测试：「自动翻页」清单与注册表 pagination 标记双向比对（此类手抄清单漂移已发生两次）；insight/reference 子命令的 `--help` 覆盖改为从端点注册表派生，新命令漏接线直接测试失败
+- `npm run prepare` 前置断言 README/CHANGELOG 含当前版本条目（写盘前检查，失败零残留）；`npm run typecheck` 纳入 tests/（tsconfig.test.json）
+- CI：`npm pack` 装包冒烟（`--help` + skill 文件存在校验）、测试矩阵 Node 下限改精确 20.18.1、CI typecheck；publish 的 `workflow_dispatch` 必须指向 `v*` tag（关闭无护栏发布通道）
+
 ### v0.26.0 — 2026-07-11
 
 **资金安全（重要）**
@@ -68,14 +95,6 @@
 - `reference institution-search` — 机构 ID 搜索，输入机构名/简称返回 `institutionId` 及适用接口参数（`usageScopes`）；`--keyword`（必填）、`--category`（`domesticBroker`/`foreignInstitution`/`leadInstitution`/`opinionInstitution`/`foreignOpinionInstitution`，可重复）、`--top`（默认 10，上限 10）；免费。覆盖既有 `--broker`/`--institution` 全部机构类（research/foreign-report/opinion/foreign-opinion/summary/roadshow/site-visit/strategy/my-conference）
 - `vault my-conference-list` 新增 `--source` — 按录制来源筛选（`1`=企微会议助理 `2`=会议服务微信群，可重复；不传返回全部）
 
-### v0.22.1 — 2026-07-03
-
-**修复**
-- 错误码 `410004` 提示改为中性措辞「数据未找到或无指标权限，请检查查询条件与指标权限」——此前只说"数据未找到"，与 `indicator` 内层信封的"无权限"消息拼接后自相矛盾
-
-**文档 / Skill**（随 `/sync-skill` 分发，不影响 CLI 行为）
-- gangtise-openapi Agent Skill 经 fable5 审计 + 多轮 review 优化：官方积分计费速查表 + 高积分 pre-flight 闸门、AI 同步生成命令 `GANGTISE_TIMEOUT_MS=120000` 超时前置、大结果集 `--output` 落盘、异步 `--wait` 主路径、行业码口径收敛到单一权威、市值量纲实测（`qte_mkt_cptl` 仅 A 股 / 默认原始「元」/ `scale`+`currency`）等文档补全与消歧
-
 > 更早版本及完整更新历史见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 首次安装
@@ -96,6 +115,8 @@ gangtise --help
 npm update -g gangtise-openapi-cli
 ```
 
+> 更新后若使用 Agent Skill：包内 skill 已随包更新，但复制到 `~/.claude/skills/` 等目录的副本是快照，**需重新执行下方「安装」段的复制命令**才能让 AI 助手拿到新版 skill。
+
 本地开发：
 
 ```bash
@@ -116,7 +137,7 @@ export GANGTISE_BASE_URL="https://openapi.gangtise.com"
 export GANGTISE_TOKEN="Bearer xxx"
 
 # 性能/调试可选项
-export GANGTISE_PAGE_CONCURRENCY=5     # 翻页并发数（默认 5）
+export GANGTISE_PAGE_CONCURRENCY=5     # 翻页/分片并发数（默认 5，上限 32；非法值回退默认）
 export GANGTISE_VERBOSE=1              # 打印每个请求的耗时与字节数
 export GANGTISE_TIMEOUT_MS=30000       # 请求超时（默认 30s）
 export GANGTISE_TOKEN_CACHE_PATH=...   # 覆盖 token 缓存路径（默认 ~/.config/gangtise/token.json）
@@ -155,22 +176,26 @@ gangtise-openapi/
     └── response-schema.md            # 各接口响应字段说明
 ```
 
-安装：
+安装（skill 目录随 npm 包分发，`npm install -g` 之后即可从全局安装位置复制）：
 
 ```bash
+SKILL_SRC="$(npm root -g)/gangtise-openapi-cli/gangtise-openapi"
+
 # Claude Code
-cp -r gangtise-openapi ~/.claude/skills/gangtise-openapi
+cp -r "$SKILL_SRC" ~/.claude/skills/gangtise-openapi
 
 # Codex
-cp -r gangtise-openapi ~/.codex/skills/gangtise-openapi
+cp -r "$SKILL_SRC" ~/.codex/skills/gangtise-openapi
 
 # OpenClaw
-cp -r gangtise-openapi ~/.openclaw/skills/gangtise-openapi
+cp -r "$SKILL_SRC" ~/.openclaw/skills/gangtise-openapi
 
 # Hermes
-cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
+cp -r "$SKILL_SRC" ~/.hermes/skills/gangtise-openapi
 ```
 
+> 从仓库 clone 开发时，把 `$SKILL_SRC` 换成仓库内的 `gangtise-openapi` 目录即可。
+
 > **版本更新**：每次 CLI 发版时，`gangtise-openapi/SKILL.md` 的 `version` 字段会自动同步。更新 CLI 后，请将项目中的 `gangtise-openapi/` 目录重新复制到对应的 skills 目录覆盖更新：
 >
 > ```bash
@@ -302,7 +327,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - **HTTP keep-alive**：所有请求复用同一个 `undici.Agent`（连接池 16），避免重复 TLS 握手。
 - **流式下载**：指定 `--output` 时，二进制响应（PDF 等）直接 `pipeline` 到磁盘，不经过内存缓冲；50MB PDF 内存占用近乎为零。
 - **流式输出**：`jsonl`/`csv` 格式且 `--output` 指定时，超过 1000 行自动切换为逐行写盘，避免一次性构建百 MB 字符串。
-- **自动重试**：5xx / 429 / `ECONNREFUSED` / `ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` / `EAI_AGAIN` / `UND_ERR_*`（undici 连接/超时类）/ `999999` 系统错误自动指数退避重试 2 次。**贵档生成类端点例外**（one-pager 等 13 个）：5xx/超时不重放——按次计费不幂等，重放即重复扣分；仅连接失败、429 与 token 自愈重试。
+- **自动重试**：5xx / 429 / `ECONNREFUSED` / `ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` / `EAI_AGAIN` / `UND_ERR_*`（undici 连接/超时类）/ `999999` 系统错误自动指数退避重试 2 次。**贵档端点例外**（one-pager 等 13 个生成/提交类 + 50/篇 的 summary/foreign-report/my-conference 下载，共 16 个）：5xx/超时不重放——按次计费不幂等，重放即重复扣分；仅连接失败、429 与 token 自愈重试。**`indicator`（EDE）端点对 `999999` 不重试**——该码实为「查询无数据」（实测），重试纯浪费。
 - **Token 自愈**：调用返回 8000014/8000015 时自动强制刷新 Token 并重试一次。
 - **K线/资金流向自动分片**：`quote day-kline --security all`、`quote fund-flow --security aShares` 等全市场查询自动按日期切分（A股 K线/资金流向 1 天/片、美股 1 天/片、HK 2 天/片、指数 30 天/片），并发执行后合并结果；按日分片自动跳过周六日。分片时如果用户未传 `--limit`，自动注入 `limit: 10000`（API 上限）避免默认 6000 截断。
 - **Token 内存缓存**：Token 在进程内存中缓存，避免每次请求读盘。

package/dist/src/cli.js

@@ -2,7 +2,7 @@
 import { Command, Option } from "commander";
 import { checkAsyncContent, pollAsyncContent, POLL_MAX_ATTEMPTS } from "./core/asyncContent.js";
 import { readTokenCache, redactTokenCache } from "./core/auth.js";
-import { collectKeyValue, collectList, collectNumberList, localDateString, maybeArray, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize, parseTimestamp13 } from "./core/args.js";
+import { collectKeyValue, collectList, collectNumberList, isVersionNewer, localDateString, maybeArray, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize, parseTimestamp13 } from "./core/args.js";
 import { buildIndicatorCrossSectionBody, buildIndicatorTimeSeriesBody, buildQuoteKlineBody, buildStockPoolStocksBody, buildWechatChatroomListBody, buildWechatMessageListBody } from "./core/commandBodies.js";
 import { flattenCrossSection, flattenTimeSeries, unwrapIndicatorData } from "./core/indicatorMatrix.js";
 import { callKlineWithSharding, isAllMarket, isFullMarket } from "./core/quoteSharding.js";
@@ -681,7 +681,9 @@ async function checkForUpdate(timeoutMs = 2000) {
     try {
         const response = await fetch("https://registry.npmjs.org/gangtise-openapi-cli/latest", { signal: AbortSignal.timeout(timeoutMs) });
         const latest = (await response.json()).version;
-        if (latest && latest !== CLI_VERSION) {
+        // Ordered compare, not inequality: during the just-published window the
+        // registry still serves the PREVIOUS version — don't suggest a "downgrade".
+        if (latest && isVersionNewer(latest, CLI_VERSION)) {
             process.stderr.write(`Update available: ${CLI_VERSION} → ${latest}\nRun: npm update -g gangtise-openapi-cli\n`);
         }
     }

package/dist/src/core/args.js

@@ -62,6 +62,23 @@ export function collectKeyValue(value, previous = {}) {
 export function maybeArray(value) {
     return value.length > 0 ? value : undefined;
 }
+/** True when `latest` is strictly newer than `current` (numeric per-segment
+ * compare). Plain inequality would nag "update available" during the
+ * just-published window while the registry still serves the previous version. */
+export function isVersionNewer(latest, current) {
+    const parse = (v) => v.split(".").map(Number);
+    const a = parse(latest);
+    const b = parse(current);
+    if (a.some(Number.isNaN) || b.some(Number.isNaN))
+        return false;
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y)
+            return x > y;
+    }
+    return false;
+}
 // Whitelist for enum-valued repeatable options. Only used where the server was
 // probed NOT to reject bad values (it silently ignores the filter or returns
 // empty instead) — endpoints that answer 100003 keep server-side validation.

package/dist/src/core/asyncContent.js

@@ -1,5 +1,6 @@
 import { ApiError } from "./errors.js";
 import { printData } from "./printer.js";
+import { isTransientError } from "./transport.js";
 // 14 attempts with exponential backoff (5s→30s cap) ≈ 316s total wait budget.
 export const POLL_MAX_ATTEMPTS = 14;
 const POLL_INITIAL_DELAY_MS = 5_000;
@@ -26,8 +27,16 @@ export async function pollAsyncContent(client, getContentEndpoint, dataId, forma
                 process.stderr.write("Content generation failed (terminal). Do not retry.\n");
                 return "failed";
             }
-            if (!isAsyncPending(error))
-                throw error;
+            if (!isAsyncPending(error)) {
+                // AI generation windows are exactly when the server is busiest: one 5xx
+                // (after the client's own retries) must not void minutes of waiting —
+                // the dataId is still valid. Transient errors consume this attempt and
+                // polling continues; anything else (no credits, bad params) aborts.
+                if (!isTransientError(error))
+                    throw error;
+                const msg = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: transient error (${msg.slice(0, 80)}), continuing to wait...\n`);
+            }
         }
         if (attempt < POLL_MAX_ATTEMPTS) {
             const delay = nextDelayMs(attempt);

package/dist/src/core/client.js

@@ -175,8 +175,14 @@ export class GangtiseClient {
             from: startFrom,
             size: firstPageSize,
         });
-        if (!this.isPaginatedListResponse(firstPage))
+        if (!this.isPaginatedListResponse(firstPage)) {
+            // Shape drift (e.g. total arriving as a string) silently degrades fetch-all
+            // to a single page with no partial marker — make it visible on verbose.
+            if (isVerbose()) {
+                process.stderr.write(`[gangtise] warning: ${endpoint.key} is marked paginated but the first page has an unexpected shape (no numeric total + list); returning it as-is\n`);
+            }
             return firstPage;
+        }
         const total = firstPage.total;
         const collected = [...firstPage.list];
         const available = Math.max(total - startFrom, 0);
@@ -398,13 +404,21 @@ export class GangtiseClient {
                 throw error;
             }
         }, {
-            policy: endpoint.retry === "no-replay" ? "no-replay" : "default",
+            policy: endpoint.retry ?? "default",
             onRetry: (attempt, error, delay) => {
                 if (!isVerbose())
                     return;
                 const msg = error instanceof Error ? error.message : String(error);
                 process.stderr.write(`[gangtise] retry ${attempt} after ${delay.toFixed(0)}ms: ${msg.slice(0, 120)}\n`);
             },
+        }).catch((error) => {
+            // EDE uses 999999 for "no data for this query" (probed 2026-07-11) — the
+            // generic "系统错误，请稍后重试" hint would send the user retrying a query
+            // that will never have data. Swap in a context-specific hint.
+            if (endpoint.retry === 'no-999999' && error instanceof ApiError && error.code === '999999') {
+                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 的 999999 多为查询无数据（节假日 / 未来日期 / 未覆盖标的）——先检查查询条件，确认应有数据再重试。');
+            }
+            throw error;
         });
     }
     async download(endpoint, query, options) {
@@ -544,6 +558,9 @@ export class GangtiseClient {
                 filename,
             };
         }, {
+            // Download endpoints carry per-篇 billing too (summary/foreign-report/
+            // my-conference at 50/篇) — honor the endpoint's retry policy here as well.
+            policy: endpoint.retry ?? "default",
             onRetry: (attempt, error, delay) => {
                 if (!isVerbose())
                     return;

package/dist/src/core/download.js

@@ -18,10 +18,12 @@ function truncateFilename(name, maxBytes = 200) {
     if (Buffer.byteLength(name, "utf8") <= maxBytes)
         return name;
     const ext = extname(name);
-    let stem = name.slice(0, name.length - ext.length);
-    while (stem.length > 1 && Buffer.byteLength(stem + ext, "utf8") > maxBytes)
-        stem = stem.slice(0, -1);
-    return stem + ext;
+    // Trim by code point, not UTF-16 unit: a cut inside a surrogate pair would put
+    // a lone surrogate in the name, which reaches the filesystem as U+FFFD (�).
+    const stem = [...name.slice(0, name.length - ext.length)];
+    while (stem.length > 1 && Buffer.byteLength(stem.join("") + ext, "utf8") > maxBytes)
+        stem.pop();
+    return stem.join("") + ext;
 }
 /** Pick a non-existing path by suffixing -1, -2, … before the extension, so batch
  * downloads whose titles collide ("2025年第一季度报告" from several companies) don't
@@ -137,6 +139,11 @@ async function downloadUrlTo(url, outputPath) {
             method: "GET",
             headersTimeout: timeoutMs,
             bodyTimeout: timeoutMs,
+            // headers/body timeouts are IDLE timeouts — a stream trickling one byte
+            // per interval resets them forever. A generous total deadline (10× the
+            // per-request timeout) bounds the whole transfer without killing large
+            // legitimate downloads.
+            signal: AbortSignal.timeout(timeoutMs * 10),
             dispatcher: getDispatcher(),
         };
         let currentUrl = url;
@@ -171,7 +178,14 @@ async function downloadUrlTo(url, outputPath) {
         }
         logTiming(`GET ${redactUrl(currentUrl)}`, Date.now() - startedAt, String(response.statusCode));
     });
-    await fs.rename(partPath, outputPath);
+    try {
+        await fs.rename(partPath, outputPath);
+    }
+    catch (error) {
+        // e.g. outputPath turned out to be a directory — don't leave the .part behind.
+        await fs.unlink(partPath).catch(() => { });
+        throw error;
+    }
 }
 export async function saveDownloadResult(result, fallbackName, output) {
     if (!(result && typeof result === "object")) {

package/dist/src/core/endpoints.js

@@ -46,6 +46,8 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/summary/v2/download/file",
         kind: "download",
         description: "Download summary file",
+        // 50/篇 — same price tier as the AI Agent calls; billing probed non-idempotent.
+        retry: "no-replay",
     },
     "insight.roadshow.list": {
         method: "POST",
@@ -100,6 +102,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/foreign-report/download/file",
         kind: "download",
         description: "Download foreign report",
+        retry: "no-replay",
     },
     "insight.announcement.list": {
         method: "POST",
@@ -538,6 +541,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-vault/my-conference/download/file",
         kind: "download",
         description: "Download my conference resource",
+        retry: "no-replay",
     },
     "vault.wechat-message.list": {
         method: "POST",
@@ -599,18 +603,21 @@ const ENDPOINT_DEFS = {
         path: "/application/open-indicator/EDE/search",
         kind: "json",
         description: "Search data indicators by keyword (returns indicatorCode + params)",
+        retry: "no-999999",
     },
     "indicator.cross-section": {
         method: "POST",
         path: "/application/open-indicator/EDE/cross-section",
         kind: "json",
         description: "Get cross-section data (multi-indicator x multi-security, single date)",
+        retry: "no-999999",
     },
     "indicator.time-series": {
         method: "POST",
         path: "/application/open-indicator/EDE/time-series",
         kind: "json",
         description: "Get time-series data (multi-indicator x single-security OR single-indicator x multi-security)",
+        retry: "no-999999",
     },
 };
 export const ENDPOINTS = Object.fromEntries(Object.entries(ENDPOINT_DEFS).map(([key, def]) => [key, { key, ...def }]));

package/dist/src/core/errors.js

@@ -40,12 +40,15 @@ export class ApiError extends CliError {
     constructor(message, code, statusCode, details, 
     /** Server-specified Retry-After (ms), set on 429 responses so the transport
      * backoff can honor it instead of the default exponential schedule. */
-    retryAfterMs) {
+    retryAfterMs, 
+    /** Context-specific hint that beats the generic per-code table — e.g. EDE's
+     * 999999 means "no data", not the table's "系统错误，请稍后重试". */
+    hintOverride) {
         super(message);
         this.code = code;
         this.statusCode = statusCode;
         this.details = details;
         this.retryAfterMs = retryAfterMs;
-        this.hint = code ? ERROR_HINTS[code] : undefined;
+        this.hint = hintOverride ?? (code ? ERROR_HINTS[code] : undefined);
     }
 }

package/dist/src/core/indicatorMatrix.js

@@ -34,7 +34,9 @@ function rowOf(values, index) {
 // Build one column header per series. Prefer the human-readable name; on a
 // duplicate name append the code so a column is never silently overwritten.
 function buildHeaders(names, codes, count) {
-    const used = new Set();
+    // Pre-seed the metadata column names: an indicator literally named "date" /
+    // "security" / "name" must get a suffixed header, not overwrite the metadata.
+    const used = new Set(["date", "security", "name"]);
     const headers = [];
     for (let i = 0; i < count; i++) {
         const base = String(names?.[i] ?? codes?.[i] ?? `col${i}`);

package/dist/src/core/output.js

@@ -9,10 +9,11 @@ export function parseOutputFormat(value) {
     throw new ConfigError(`Unsupported format: ${format}`);
 }
 /** Cell text for terminal-facing formats (table/markdown): newlines collapsed for
- * alignment, remaining C0/DEL control chars stripped so server data can't inject
- * terminal escape sequences (ESC[31m etc.) into the user's terminal. */
+ * alignment, remaining C0/DEL/C1 control chars stripped so server data can't inject
+ * terminal escape sequences into the user's terminal (U+009B is a one-byte CSI
+ * that 8-bit-control terminals treat exactly like ESC[). */
 function sanitizeCell(value) {
-    return value.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f]/g, "");
+    return value.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f\u0080-\u009f]/g, "");
 }
 /** Terminal display width: CJK/fullwidth chars and emoji occupy 2 columns — padEnd
  * counts UTF-16 code units and misaligns every table containing Chinese text or emoji
@@ -62,6 +63,24 @@ function toRows(value) {
     }
     return [{ value }];
 }
+// One huge cell (a 50KB brief/chat message) would otherwise force every row of
+// that column to be padded to the same width — rows × width of pure spaces.
+const MAX_CELL_DISPLAY_WIDTH = 120;
+/** Truncate a cell to the display-width cap, ellipsis included in the budget. */
+function clampCell(value) {
+    if (displayWidth(value) <= MAX_CELL_DISPLAY_WIDTH)
+        return value;
+    let out = "";
+    let width = 0;
+    for (const ch of value) {
+        const w = displayWidth(ch);
+        if (width + w > MAX_CELL_DISPLAY_WIDTH - 1)
+            break;
+        out += ch;
+        width += w;
+    }
+    return out + "…";
+}
 function renderTable(rows) {
     if (rows.length === 0) {
         return "(empty)";
@@ -73,8 +92,8 @@ function renderTable(rows) {
     // spreading a per-row array overflows the call stack on large results (table is
     // the default format, e.g. `quote day-kline --security all`). Widths and padding
     // use displayWidth so CJK cells stay aligned.
-    const headerCells = columns.map(sanitizeCell);
-    const matrix = rows.map((row) => columns.map((column) => sanitizeCell(formatScalar(row[column]))));
+    const headerCells = columns.map((column) => clampCell(sanitizeCell(column)));
+    const matrix = rows.map((row) => columns.map((column) => clampCell(sanitizeCell(formatScalar(row[column])))));
     const widths = columns.map((_, c) => matrix.reduce((max, cells) => Math.max(max, displayWidth(cells[c])), displayWidth(headerCells[c])));
     const renderLine = (values) => values.map((value, index) => value + " ".repeat(Math.max(0, widths[index] - displayWidth(value)))).join("  ");
     const header = renderLine(headerCells);
@@ -89,9 +108,12 @@ function renderMarkdown(rows) {
     const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
     // Column names come from server data (e.g. EDE indicator display names) — escape
     // them like cell values or a name containing | / , breaks the whole table.
-    const header = `| ${columns.map((column) => sanitizeCell(column).replaceAll("|", "\\|")).join(" | ")} |`;
+    // Backslash must go first: escaping only "|" turns a literal `\|` into `\\|`,
+    // which GFM reads as an escaped backslash + BARE pipe → an extra column.
+    const mdEscape = (value) => value.replaceAll("\\", "\\\\").replaceAll("|", "\\|");
+    const header = `| ${columns.map((column) => mdEscape(sanitizeCell(column))).join(" | ")} |`;
     const divider = `| ${columns.map(() => "---").join(" | ")} |`;
-    const body = rows.map((row) => `| ${columns.map((column) => sanitizeCell(formatScalar(row[column])).replaceAll("|", "\\|")).join(" | ")} |`);
+    const body = rows.map((row) => `| ${columns.map((column) => mdEscape(sanitizeCell(formatScalar(row[column])))).join(" | ")} |`);
     return [header, divider, ...body].join("\n");
 }
 function renderCsv(rows) {

package/dist/src/core/quoteSharding.js

@@ -153,8 +153,11 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
     let fieldList;
     let header = null;
     const merged = [];
-    let truncatedShards = 0;
-    for (const r of results) {
+    // Record WHICH windows maxed out, not just how many: a script/agent consumer
+    // needs the concrete date ranges to re-pull narrower windows (mirrors failedShards).
+    const truncatedShards = [];
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
         if (!(r && typeof r === "object"))
             continue;
         const rec = r;
@@ -163,7 +166,7 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
         if (!fieldList && Array.isArray(rec.fieldList))
             fieldList = rec.fieldList;
         if (isTruncated(rec))
-            truncatedShards++;
+            truncatedShards.push(shards[i]);
         // Append one-by-one rather than push(...list): a future higher row cap could
         // make a single shard's list large enough to overflow the stack via spread.
         if (Array.isArray(rec.list))
@@ -187,9 +190,10 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
         out.failedShards = failedShards;
         process.stderr.write(`[gangtise] warning: ${failedShards.length}/${shards.length} shards failed; results are partial (see failedShards)\n`);
     }
-    if (truncatedShards > 0) {
+    if (truncatedShards.length > 0) {
         out.partial = true;
-        process.stderr.write(`[gangtise] warning: ${truncatedShards}/${shards.length} shard(s) hit the ${perShardLimit}-row limit and were likely truncated; results are partial — ${truncationHint}.\n`);
+        out.truncatedShards = truncatedShards;
+        process.stderr.write(`[gangtise] warning: ${truncatedShards.length}/${shards.length} shard(s) hit the ${perShardLimit}-row limit and were likely truncated; results are partial (see truncatedShards) — ${truncationHint}.\n`);
     }
     return out;
 }

package/dist/src/core/transport.js

@@ -62,8 +62,18 @@ export async function runWithConcurrency(items, concurrency, fn) {
     await Promise.all(Array.from({ length: limit }, () => worker()));
     return results;
 }
+/** Parse GANGTISE_PAGE_CONCURRENCY defensively. runWithConcurrency clamps to
+ * ≥1 worker, so a negative/zero/NaN value silently degrades to SERIAL fetching
+ * (slow, confusing); an absurd value fans out up to items.length workers at
+ * once and can 429-storm the server. Fall back to the default and cap at 32. */
+export function resolvePageConcurrency(raw, fallback = 5, max = 32) {
+    const parsed = Math.floor(Number(raw));
+    if (!Number.isFinite(parsed) || parsed < 1)
+        return fallback;
+    return Math.min(parsed, max);
+}
 /** Fan-out width for pagination and kline shards — one env knob tunes both. */
-export const PAGE_CONCURRENCY = Number(process.env.GANGTISE_PAGE_CONCURRENCY ?? 5) || 5;
+export const PAGE_CONCURRENCY = resolvePageConcurrency(process.env.GANGTISE_PAGE_CONCURRENCY);
 const RETRYABLE_HTTP_STATUS = new Set([429, 500, 502, 503, 504]);
 const RETRYABLE_NETWORK_CODES = new Set(["ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "ENOTFOUND", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_SOCKET", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT"]);
 const RETRYABLE_API_CODES = new Set(["999999"]);
@@ -79,9 +89,9 @@ function isRetryableError(error, policy) {
             return true;
         if (policy === "no-replay")
             return false;
-        if (error.statusCode != null && RETRYABLE_HTTP_STATUS.has(error.statusCode))
-            return true;
         if (error.code && RETRYABLE_API_CODES.has(error.code))
+            return policy !== "no-999999";
+        if (error.statusCode != null && RETRYABLE_HTTP_STATUS.has(error.statusCode))
             return true;
         return false;
     }
@@ -100,6 +110,12 @@ function isRetryableError(error, policy) {
 export function markRetryable(error) {
     return Object.assign(error, { __retryable: true });
 }
+/** Errors worth waiting out (anything the default policy would retry): transient
+ * 5xx / network / timeout / 429 / 999999. Used by async polling to survive a
+ * blip without abandoning a multi-minute wait. */
+export function isTransientError(error) {
+    return isRetryableError(error, "default");
+}
 export async function withRetry(fn, options = {}) {
     const retries = options.retries ?? 2;
     const baseDelay = options.baseDelayMs ?? 400;

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated — DO NOT EDIT
-export const CLI_VERSION = "0.26.0";
+export const CLI_VERSION = "0.27.0";