bitbank-lab-mcp 0.1.3 → 0.2.1

package/README.md

@@ -420,6 +420,8 @@ npx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp
 ```
 ソースコードから動かす場合は `npx @modelcontextprotocol/inspector -- tsx src/server.ts`（[開発者向け](#開発者向けソースから起動) を参照）。
 
+**Q. 当日の約定（フロー）データが少ない・古い時間帯が取れない** bitbank 側の仕様です。約定履歴の日付アーカイブ（`/transactions/{YYYYMMDD}`）は **UTC 暦日単位**で、当該 UTC 日の完了後（日本時間 9:00 以降、さらに公開遅延あり）にのみ公開されます。進行中の UTC 日の約定は直近約 60 件（latest）しか取得できないため、`get_flow_metrics` 等では当日区間のカバレッジが限定的になります（結果に warning として明示されます）。ローソク足（`get_candles`）は進行中の UTC 日でもリアルタイムで取得できます。
+
 ## トラブルシューティング
 
 | 症状 | 原因・対処 |

package/lib/candle-fetch.ts

@@ -160,6 +160,29 @@ export async function mergeChunks(
 	return { rows, results, lastRateLimit, failedKeys };
 }
 
+/**
+ * 失敗した chunk を「key(エラー内容)」形式で列挙する（診断用メッセージ向け）。
+ * 例: "20260708(HTTP 404 Not Found), 20260707(bitbank API error (code: 10000))"
+ *
+ * 「N日中M日失敗」だけではどの日付が何の理由で落ちたか判別できず調査不能になるため、
+ * 過半数失敗 fail / 部分失敗 warning のメッセージには必ずこれを含めること。
+ */
+export function describeFailedChunks(
+	keys: string[],
+	results: FetchChunkResult[],
+	onlyKeys?: ReadonlySet<string>,
+): string {
+	const parts: string[] = [];
+	for (let i = 0; i < keys.length; i++) {
+		const err = results[i]?.error;
+		if (err == null) continue;
+		if (onlyKeys && !onlyKeys.has(keys[i])) continue;
+		const msg = err instanceof Error ? err.message : String(err);
+		parts.push(`${keys[i]}(${msg})`);
+	}
+	return parts.join(', ');
+}
+
 function isOhlcAllZero(row: OhlcvRow): boolean {
 	return Number(row[0]) === 0 && Number(row[1]) === 0 && Number(row[2]) === 0 && Number(row[3]) === 0;
 }

package/lib/tx-archive.ts

@@ -0,0 +1,58 @@
+/**
+ * /transactions/{YYYYMMDD} 日付アーカイブの日付キーユーティリティ。
+ *
+ * bitbank Public API の日付アーカイブは **UTC 暦日** でグルーピングされ、
+ * 当該 UTC 日が完了するまで 404 を返す（進行中の UTC 日のデータは
+ * /transactions (latest, 直近約60件) でのみ取得可能）。
+ * 実測ログ: docs/internal/bitbank-tx-archive-tz.md
+ *
+ * JST 基準で「今日 / 昨日」を組むと、JST 早朝（00:00〜09:00 = UTC 日付更新前）には
+ * 進行中の UTC 日を要求してしまい必ず 404 になる。日付キーは必ず本モジュールの
+ * 「完了済み UTC 暦日」ベースで導出すること。
+ */
+
+import { dayjs } from './datetime.js';
+
+/** nowMs が属する UTC 暦日キー (YYYYMMDD)。この日のアーカイブは未公開（404）。 */
+export function currentUtcDayKey(nowMs: number = Date.now()): string {
+	return dayjs.utc(nowMs).format('YYYYMMDD');
+}
+
+/**
+ * dateKey のアーカイブが公開済みと期待できるか（= その UTC 暦日が完了しているか）。
+ * 進行中・未来の UTC 日は false。形式不正（YYYYMMDD 以外）も false。
+ */
+export function isArchiveExpectedPublished(dateKey: string, nowMs: number = Date.now()): boolean {
+	return /^\d{8}$/.test(dateKey) && dateKey < currentUtcDayKey(nowMs);
+}
+
+/**
+ * 直近 count 個の完了済み UTC 暦日キーを新しい順で返す。
+ * 進行中の UTC 日（= currentUtcDayKey）は含めない。
+ */
+export function recentCompletedUtcDayKeys(count: number, nowMs: number = Date.now()): string[] {
+	const utcNow = dayjs.utc(nowMs);
+	return Array.from({ length: Math.max(0, Math.floor(count)) }, (_, i) =>
+		utcNow.subtract(i + 1, 'day').format('YYYYMMDD'),
+	);
+}
+
+/**
+ * [sinceMs, nowMs] と交差する完了済み UTC 暦日キーを昇順で返す。
+ * 進行中の UTC 日は除外する（アーカイブ未公開のため要求しても 404）。
+ * その区間のデータが必要な場合は /transactions (latest) で補完し、
+ * カバレッジ不足を warning で明示すること。
+ */
+export function completedUtcDayKeysInRange(sinceMs: number, nowMs: number = Date.now()): string[] {
+	if (!Number.isFinite(sinceMs) || !Number.isFinite(nowMs) || sinceMs > nowMs) return [];
+	const current = currentUtcDayKey(nowMs);
+	const keys: string[] = [];
+	let d = dayjs.utc(sinceMs).startOf('day');
+	const end = dayjs.utc(nowMs).startOf('day');
+	while (d.valueOf() <= end.valueOf()) {
+		const key = d.format('YYYYMMDD');
+		if (key < current) keys.push(key);
+		d = d.add(1, 'day');
+	}
+	return keys;
+}

package/lib/validate.ts

@@ -1,3 +1,5 @@
+import { realpathSync } from 'node:fs';
+import { basename, delimiter, dirname, join, resolve, sep } from 'node:path';
 import type { Pair } from '../src/schemas.js';
 import { nowIso } from './datetime.js';
 
@@ -148,6 +150,74 @@ export function validateDate(
 	return { ok: true, value: date };
 }
 
+/** チャートファイルの既定出力ディレクトリ（Claude.ai 環境の出力先） */
+export const DEFAULT_CHART_OUTPUT_DIR = '/mnt/user-data/outputs';
+
+/** チャート出力の許可 root を運用側が追加する環境変数（path.delimiter 区切り） */
+export const OUTPUT_DIR_ALLOWLIST_ENV = 'BACKTEST_OUTPUT_DIR_ALLOWLIST';
+
+/**
+ * チャート出力先として許可される root ディレクトリ一覧。
+ * 既定: DEFAULT_CHART_OUTPUT_DIR とサーバー作業ディレクトリ配下
+ * （相対パス指定・Cursor 等でワークスペース直下に書き出すユースケース用）。
+ * それ以外は運用側が環境変数で明示的に許可する（LLM 入力からは追加できない）。
+ */
+export function allowedOutputRoots(): string[] {
+	const extra = (process.env[OUTPUT_DIR_ALLOWLIST_ENV] ?? '')
+		.split(delimiter)
+		.map((p) => p.trim())
+		.filter((p) => p.length > 0)
+		.map((p) => resolve(p));
+	return [resolve(DEFAULT_CHART_OUTPUT_DIR), process.cwd(), ...extra];
+}
+
+/**
+ * パスを実パスに正規化する。実在する最深の祖先を realpathSync で解決し、
+ * 未作成の末尾セグメントは字句のまま結合する（mkdir 前の検証で使うため）。
+ * 許可 root 配下に置かれた symlink を経由した外部への書き込みを防ぐ。
+ */
+function canonicalizePath(p: string): string {
+	let current = resolve(p);
+	const pending: string[] = [];
+	for (;;) {
+		try {
+			return join(realpathSync(current), ...pending);
+		} catch {
+			const parent = dirname(current);
+			if (parent === current) return join(current, ...pending);
+			pending.unshift(basename(current));
+			current = parent;
+		}
+	}
+}
+
+/**
+ * outputDir が許可 root 配下かを検証する。
+ * LLM 入力（プロンプトインジェクション含む）経由でプロセス権限内の任意パスへ
+ * ディレクトリ作成・ファイル書き込みされるのを防ぐ。`..` を含むパスも
+ * symlink も実パスに解決してから判定するため、トラバーサル・symlink では
+ * 迂回できない（検証と書き込みの間に symlink を差し替える TOCTOU は、
+ * それができる時点でローカルアクセスを持つため脅威モデル外）。
+ */
+export function ensureAllowedOutputDir(
+	dir: string,
+): { ok: true; dir: string } | { ok: false; error: { type: 'user' | 'internal'; message: string } } {
+	const canonical = canonicalizePath(dir);
+	const roots = allowedOutputRoots();
+	const canonicalRoots = roots.map(canonicalizePath);
+	const allowed = canonicalRoots.some((root) => canonical === root || canonical.startsWith(root + sep));
+	if (!allowed) {
+		return {
+			ok: false,
+			error: {
+				type: 'user',
+				message: `outputDir '${dir}' は許可されていません。許可 root: ${roots.join(', ')} 配下のみ（追加は環境変数 ${OUTPUT_DIR_ALLOWLIST_ENV} で指定）`,
+			},
+		};
+	}
+	return { ok: true, dir: canonical };
+}
+
 export function createMeta(
 	pair: Pair,
 	additional: Record<string, unknown> = {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitbank-lab-mcp",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Experimental MCP server for bitbank — botters lab community edition. Market data, technical analysis, charting, and Private API trading tools.",
   "type": "module",
   "bin": {
@@ -9,11 +9,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tjackiet/bitbank-lab-mcp.git"
+    "url": "https://github.com/bitbankinc/bitbank-lab-mcp.git"
   },
-  "homepage": "https://github.com/tjackiet/bitbank-lab-mcp",
+  "homepage": "https://github.com/bitbankinc/bitbank-lab-mcp",
   "bugs": {
-    "url": "https://github.com/tjackiet/bitbank-lab-mcp/issues"
+    "url": "https://github.com/bitbankinc/bitbank-lab-mcp/issues"
   },
   "files": [
     "bin/",

package/src/schema/backtest.ts

@@ -60,7 +60,15 @@ export const RunBacktestInputSchema = z
 				'One-way fee in basis points. When omitted, resolved dynamically from the current /spot/pairs taker rate (falls back to nominal 12 bp if unavailable). Explicit values are always respected.',
 			),
 		execution: z.literal('t+1_open').optional().default('t+1_open').describe('Execution timing (fixed: t+1_open)'),
-		outputDir: z.string().optional().default('/mnt/user-data/outputs').describe('Output directory for chart files'),
+		outputDir: z
+			.string()
+			.optional()
+			.default('/mnt/user-data/outputs')
+			.describe(
+				'Output directory for chart files. Must be under an allowed root: ' +
+					'/mnt/user-data/outputs, the server working directory, or a directory listed in ' +
+					'the BACKTEST_OUTPUT_DIR_ALLOWLIST environment variable.',
+			),
 		savePng: z
 			.boolean()
 			.optional()

package/tools/analyze_volume_profile.ts

@@ -10,9 +10,10 @@
  */
 
 import type { z } from 'zod';
-import { dayjs, toDisplayTime, toIsoWithTz } from '../lib/datetime.js';
+import { toDisplayTime, toIsoWithTz } from '../lib/datetime.js';
 import { formatPair, formatPercent, formatPrice } from '../lib/formatter.js';
 import { fail, failFromError, failFromValidation, ok } from '../lib/result.js';
+import { completedUtcDayKeysInRange, recentCompletedUtcDayKeys } from '../lib/tx-archive.js';
 import { createMeta, ensurePair } from '../lib/validate.js';
 import {
 	type AnalyzeVolumeProfileDataSchemaOut,
@@ -27,12 +28,22 @@ type Tx = { price: number; amount: number; side: 'buy' | 'sell'; timestampMs: nu
 
 // ── Transaction fetch helpers (shared pattern with get_flow_metrics) ──
 
-function mergeTxResults(results: unknown[]): { txs: Tx[]; totalCount: number; failedCount: number } {
+type TxFetchFailure = { label: string; errorType: string; message: string };
+
+function mergeTxResults(
+	results: unknown[],
+	labels?: string[],
+): { txs: Tx[]; totalCount: number; failedCount: number; failures: TxFetchFailure[] } {
 	const seen = new Set<string>();
 	const merged: Tx[] = [];
-	let failedCount = 0;
-	for (const res of results) {
-		const r = res as { ok?: boolean; data?: { normalized?: Tx[] } } | null;
+	const failures: TxFetchFailure[] = [];
+	for (let i = 0; i < results.length; i++) {
+		const r = results[i] as {
+			ok?: boolean;
+			data?: { normalized?: Tx[] };
+			summary?: string;
+			meta?: { errorType?: string };
+		} | null;
 		if (r?.ok && Array.isArray(r.data?.normalized)) {
 			for (const tx of r.data.normalized as Tx[]) {
 				const key = `${tx.timestampMs}:${tx.price}:${tx.amount}:${tx.side}`;
@@ -42,10 +53,19 @@ function mergeTxResults(results: unknown[]): { txs: Tx[]; totalCount: number; fa
 				}
 			}
 		} else {
-			failedCount++;
+			failures.push({
+				label: labels?.[i] ?? `#${i}`,
+				errorType: r?.meta?.errorType ?? 'unknown',
+				message: r?.summary ?? 'unknown error',
+			});
 		}
 	}
-	return { txs: merged, totalCount: results.length, failedCount };
+	return { txs: merged, totalCount: results.length, failedCount: failures.length, failures };
+}
+
+/** 失敗詳細を "label(errorType: message)" 形式で列挙する（get_flow_metrics と同形式）。 */
+function formatFailures(failures: TxFetchFailure[]): string {
+	return failures.map((f) => `${f.label}(${f.errorType}: ${f.message})`).join(', ');
 }
 
 type FetchResult = { ok: true; txs: Tx[]; fetchWarning?: string } | { ok: false; errorType: string; summary: string };
@@ -60,29 +80,28 @@ function extractUpstreamError(results: unknown[]): { errorType: string; summary:
 	return null;
 }
 
-function partialFailureWarning(totalCount: number, failedCount: number): string | undefined {
-	if (failedCount === 0) return undefined;
-	return `⚠️ ${totalCount}件中${failedCount}件のAPI取得に失敗しました。データが不完全な可能性があります。`;
+function partialFailureWarning(totalCount: number, failures: TxFetchFailure[]): string | undefined {
+	if (failures.length === 0) return undefined;
+	// どの日付/エンドポイントが何の理由で失敗したかを必ず含める（件数だけでは診断不能）。
+	return `⚠️ ${totalCount}件中${failures.length}件のAPI取得に失敗しました（${formatFailures(failures)}）。データが不完全な可能性があります。`;
 }
 
 async function fetchTransactions(pair: string, hours?: number, limit?: number): Promise<FetchResult> {
 	if (hours != null && hours > 0) {
 		const nowMs = Date.now();
 		const sinceMs = nowMs - hours * 3600_000;
-		const sinceDayjs = dayjs(sinceMs).tz('Asia/Tokyo');
-		const nowDayjs = dayjs(nowMs).tz('Asia/Tokyo');
-
-		const dates: string[] = [];
-		let d = sinceDayjs.startOf('day');
-		while (d.isBefore(nowDayjs) || d.isSame(nowDayjs, 'day')) {
-			dates.push(d.format('YYYYMMDD'));
-			d = d.add(1, 'day');
-		}
+
+		// /transactions/{YYYYMMDD} は UTC 暦日アーカイブで、当該 UTC 日が完了するまで 404
+		// （実測: docs/internal/bitbank-tx-archive-tz.md）。進行中の UTC 日は列挙から除外し、
+		// その区間は /transactions (latest) で補完する。JST 暦日で列挙すると JST 早朝に
+		// 進行中の UTC 日を要求して必ず失敗する。
+		const dates = completedUtcDayKeysInRange(sinceMs, nowMs);
 
 		const fetches: Promise<unknown>[] = dates.map((ds) => getTransactions(pair, 1000, ds));
 		fetches.push(getTransactions(pair, 1000));
 		const results = await Promise.all(fetches);
-		const { txs: mergedTxs, totalCount, failedCount } = mergeTxResults(results);
+		const labels = [...dates, 'latest'];
+		const { txs: mergedTxs, totalCount, failedCount, failures } = mergeTxResults(results, labels);
 		if (mergedTxs.length === 0) {
 			const upstreamErr = extractUpstreamError(results);
 			if (upstreamErr) return { ok: false, ...upstreamErr };
@@ -91,7 +110,7 @@ async function fetchTransactions(pair: string, hours?: number, limit?: number):
 			return {
 				ok: false,
 				errorType: 'upstream',
-				summary: `API取得の過半数が失敗しました（${totalCount}件中${failedCount}件失敗）`,
+				summary: `API取得の過半数が失敗しました（${totalCount}件中${failedCount}件失敗: ${formatFailures(failures)}）`,
 			};
 		}
 		return {
@@ -99,7 +118,7 @@ async function fetchTransactions(pair: string, hours?: number, limit?: number):
 			txs: mergedTxs
 				.filter((t) => t.timestampMs >= sinceMs && t.timestampMs <= nowMs)
 				.sort((a, b) => a.timestampMs - b.timestampMs),
-			fetchWarning: partialFailureWarning(totalCount, failedCount),
+			fetchWarning: partialFailureWarning(totalCount, failures),
 		};
 	}
 
@@ -115,31 +134,24 @@ async function fetchTransactions(pair: string, hours?: number, limit?: number):
 	if (latestTxs.length >= lim) return { ok: true, txs: latestTxs.slice(-lim) };
 
 	// Supplement with previous days
-	const todayJst = dayjs().tz('Asia/Tokyo');
-	const supplementFetches: Promise<unknown>[] = [
-		getTransactions(pair, 1000, todayJst.subtract(1, 'day').format('YYYYMMDD')),
-	];
-	if (lim > 500) {
-		supplementFetches.push(getTransactions(pair, 1000, todayJst.subtract(2, 'day').format('YYYYMMDD')));
-	}
-	const supplementResults = await Promise.all(supplementFetches);
+	// /transactions/{YYYYMMDD} は UTC 暦日アーカイブ・当該 UTC 日完了後に公開のため、
+	// 完了済み UTC 日から補完する（JST 基準で組むと JST 早朝に進行中の UTC 日を要求して 404）。
+	const supplementDates = recentCompletedUtcDayKeys(lim > 500 ? 2 : 1);
+	const supplementResults = await Promise.all(supplementDates.map((ds) => getTransactions(pair, 1000, ds)));
 	const allResults = [latestRes, ...supplementResults];
-	const { txs: mergedTxs, totalCount, failedCount } = mergeTxResults(allResults);
+	const labels = ['latest', ...supplementDates];
+	const { txs: mergedTxs, totalCount, failures } = mergeTxResults(allResults, labels);
 	if (mergedTxs.length === 0) {
 		const upstreamErr = extractUpstreamError(allResults);
 		if (upstreamErr) return { ok: false, ...upstreamErr };
 	}
-	if (failedCount > 0 && failedCount >= totalCount / 2) {
-		return {
-			ok: false,
-			errorType: 'upstream',
-			summary: `API取得の過半数が失敗しました（${totalCount}件中${failedCount}件失敗）`,
-		};
-	}
+	// 補完は best-effort: 何かしら取得できていれば fail せず、部分失敗は警告で明示する
+	// （latest 成功 + 補完失敗を「過半数失敗」として全体 fail すると、正当に取得できた
+	// 直近データまで捨ててしまう。補完アーカイブは公開遅延等で 404 になり得る）。
 	return {
 		ok: true,
 		txs: mergedTxs.sort((a, b) => a.timestampMs - b.timestampMs).slice(-lim),
-		fetchWarning: partialFailureWarning(totalCount, failedCount),
+		fetchWarning: partialFailureWarning(totalCount, failures),
 	};
 }
 

package/tools/get_candles.ts

@@ -1,12 +1,13 @@
 import {
 	dedupeByTimestamp,
+	describeFailedChunks,
 	type FetchChunkResult,
 	fetchCandleChunk,
 	mergeChunks,
 	type OhlcvRow,
 	UpstreamApiError,
 } from '../lib/candle-fetch.js';
-import { dayjs, formatDateInTz, today, toIsoTime, toIsoWithTz } from '../lib/datetime.js';
+import { dayjs, formatDateInTz, toIsoTime, toIsoWithTz } from '../lib/datetime.js';
 import { getErrorMessage } from '../lib/error.js';
 import { formatSummary } from '../lib/formatter.js';
 import { BITBANK_API_BASE, DEFAULT_RETRIES, fetchJsonWithRateLimit, type RateLimitInfo } from '../lib/http.js';
@@ -99,10 +100,6 @@ const CANDLE_LIMIT = {
 	multiDay: 10_000,
 } as const;
 
-function todayYyyymmdd(): string {
-	return today('YYYYMMDD');
-}
-
 /**
  * tz 引数を正規化する。空文字・undefined・不正値は Asia/Tokyo にフォールバック。
  *
@@ -149,6 +146,33 @@ function computeAnchorEndMs(rawDate: string, type: string, tz: string = 'Asia/To
 	return null;
 }
 
+/**
+ * date 指定時の対象期間の「開始」timestamp (ms since epoch) を返す（未来日の早期判定用）。
+ *
+ * computeAnchorEndMs と対になる関数で、tz 暦日/暦年の先頭 00:00:00.000 (in tz) を返す:
+ * - YYYYMMDD: その日の先頭
+ * - YYYY: その年の 1/1 先頭（YEARLY_TYPES でのみ用いる）
+ *
+ * 未来日判定は「終端 > now」ではなく「開始 > now」で行う。終端で判定すると
+ * 当日（進行中の tz 暦日）が『未来』扱いになり、当日途中の部分データ取得という
+ * 正当なユースケースを拒否してしまう。
+ */
+function computeAnchorStartMs(rawDate: string, type: string, tz: string = 'Asia/Tokyo'): number | null {
+	const safeTz = normalizeAnchorTz(tz);
+	if (/^\d{8}$/.test(rawDate)) {
+		const year = rawDate.slice(0, 4);
+		const month = rawDate.slice(4, 6);
+		const day = rawDate.slice(6, 8);
+		const d = dayjs.tz(`${year}-${month}-${day}`, safeTz);
+		return d.isValid() ? d.startOf('day').valueOf() : null;
+	}
+	if (YEARLY_TYPES.has(type) && /^\d{4}$/.test(rawDate)) {
+		const d = dayjs.tz(`${rawDate}-01-01`, safeTz);
+		return d.isValid() ? d.startOf('year').valueOf() : null;
+	}
+	return null;
+}
+
 /**
  * [windowStartMs, windowEndMs] と交差する UTC 暦年 (YYYY) を昇順で返す。
  * YEARLY_TYPES の fetch key 導出に使う（bitbank API は UTC 年 chunk）。
@@ -213,6 +237,43 @@ function classifyAllChunksFailure(results: FetchChunkResult[]): FailResult | nul
 	return null;
 }
 
+/**
+ * 上流の「データ未生成（まだ無い）」応答か。
+ * bitbank /candlestick は未来・未開始の期間に HTTP 404 または success:0 (code: 10000) を返す
+ * （docs/internal/bitbank-candle-tz.md 実測）。5xx・ネットワークエラーは含めない。
+ */
+function isNotYetAvailableError(err: unknown): boolean {
+	if (err instanceof UpstreamApiError) return true;
+	const msg = err instanceof Error ? err.message : String(err ?? '');
+	return /\b404\b/.test(msg);
+}
+
+/**
+ * 失敗 chunk を「実失敗 (hard)」と「進行中 UTC 期間のデータ未生成 (expectedGap)」に分ける。
+ *
+ * expectedGap = key が進行中の UTC 期間以降（辞書順比較。YYYYMMDD 日 key / YYYY 年 key 両対応）
+ * かつエラーが 404 / success:0 のもの。UTC 期間の開始直後はその期間の chunk がまだ生成されて
+ * いないことがあり、これは上流の正常応答（データが無いだけ）なので、過半数失敗の分母分子から
+ * 除外して ℹ️ 注記に落とす。過去期間の失敗やネットワーク/5xx は実失敗として扱う。
+ */
+function partitionFailedChunks(
+	keys: string[],
+	results: FetchChunkResult[],
+	nowUtcDayKey: string,
+): { hardFailedKeys: string[]; expectedGapKeys: string[] } {
+	const hardFailedKeys: string[] = [];
+	const expectedGapKeys: string[] = [];
+	for (let i = 0; i < keys.length; i++) {
+		const err = results[i]?.error;
+		if (err == null) continue;
+		const key = keys[i];
+		const isCurrentOrFuturePeriod = key >= nowUtcDayKey.slice(0, key.length);
+		if (isCurrentOrFuturePeriod && isNotYetAvailableError(err)) expectedGapKeys.push(key);
+		else hardFailedKeys.push(key);
+	}
+	return { hardFailedKeys, expectedGapKeys };
+}
+
 export default async function getCandles(
 	pair: string,
 	type: CandleType | string = '1day',
@@ -227,8 +288,14 @@ export default async function getCandles(
 		return fail(`type は ${[...TYPES].join(', ')} から選択してください（指定値: ${String(type)}）`, 'user');
 	}
 
+	// anchor / fetch 範囲計算で参照する tz。空文字・不正値は Asia/Tokyo にフォールバックする
+	// （PR-2 の displayTz と同じフォールバック規則）。
+	const anchorTz = normalizeAnchorTz(tz);
+
 	const dateProvided = date != null;
-	const effectiveDate = date ?? todayYyyymmdd();
+	// date 省略時の基準日は anchorTz の暦日で解釈する。サーバーのローカル tz で組むと、
+	// tz とローカルの暦日がずれる時間帯（JST 早朝の UTC サーバー等）に基準日が 1 日ずれる。
+	const effectiveDate = date ?? dayjs().tz(anchorTz).format('YYYYMMDD');
 	const dateCheck = validateDate(effectiveDate, String(type));
 	if (!dateCheck.ok) return failFromValidation(dateCheck);
 
@@ -238,10 +305,6 @@ export default async function getCandles(
 	const barsPerYear = BARS_PER_YEAR[type] || 365;
 	const barsPerDay = BARS_PER_DAY[type] || 24;
 
-	// anchor / fetch 範囲計算で参照する tz。空文字・不正値は Asia/Tokyo にフォールバックする
-	// （PR-2 の displayTz と同じフォールバック規則）。
-	const anchorTz = normalizeAnchorTz(tz);
-
 	// date 指定時に「これ以下の足だけ返す」アンカー timestamp を計算する。
 	// 単一 fetch（YEARLY_TYPES）では API が年単位で返すため slice(-limit) のみだと
 	// 「指定日以前 limit 件」ではなく「年末側 limit 件」を返してしまう問題への対処。
@@ -250,14 +313,17 @@ export default async function getCandles(
 	const anchorActive = anchorEndMs != null;
 
 	// anchor 計算後の早期 fail（fetch 前に明らかに無効な範囲を弾く）:
-	// - 未来日: anchor が現在時刻より先 → データはまだ存在しない
+	// - 未来日: 期間の「開始」が現在時刻より先 → データはまだ存在しない。
+	//   当日（進行中の tz 暦日）は終端が未来でも部分データ取得が正当なユースケースなので、
+	//   終端ではなく開始で判定する（終端判定だと当日を『未来』として誤拒否する）。
 	// - サービス開始前: anchor が BITBANK_SERVICE_START_MS より前 → ヒューリスティックに無効と推定
 	// 上流 404 / 空配列として返すより user 向け原因を明示する方が調査が早い。
 	if (anchorEndMs != null) {
-		if (anchorEndMs > Date.now()) {
-			const isoLocal = toIsoWithTz(anchorEndMs, anchorTz) ?? String(anchorEndMs);
+		const anchorStartMs = computeAnchorStartMs(effectiveDate, String(type), anchorTz);
+		if (anchorStartMs != null && anchorStartMs > Date.now()) {
+			const isoLocal = toIsoWithTz(anchorStartMs, anchorTz) ?? String(anchorStartMs);
 			return fail(
-				`No candle data available for date=${effectiveDate} (date is in the future, anchor=${isoLocal})`,
+				`No candle data available for date=${effectiveDate} (date is in the future, starts at ${isoLocal} ${anchorTz})`,
 				'user',
 			);
 		}
@@ -268,9 +334,11 @@ export default async function getCandles(
 
 	// 起点年（multi-year のみ参照）:
 	//   - date 指定時 → その年（過去年は丸ごと利用可能）
-	//   - date 未指定 → 現在年（部分年であり経過日数を考慮）
+	//   - date 未指定 → 現在の UTC 年（部分年であり経過日数を考慮）
 	// 公式 API は YYYY 指定で 1 年分の candlestick を返す（4hour 以上の YEARLY_TYPES のみ）。
-	const currentYear = dayjs().year();
+	// 年は UTC で数える（fetch key は UTC 年 chunk。ローカル/anchorTz 年で数えると、
+	// JST 元日早朝など UTC ではまだ前年の時間帯に存在しない未来年 chunk を要求して 404 になる）。
+	const currentYear = dayjs.utc().year();
 	const anchorYear = dateProvided && isYearlyType ? Number(dateCheck.value) : currentYear;
 	const isCurrentYearAnchor = anchorYear === currentYear;
 
@@ -278,7 +346,7 @@ export default async function getCandles(
 	// floor(elapsedMs / intervalMs) + 1 は「確定済み本数 + 現在形成中の足」。
 	// 日数ベース（floor(dayOfYear * barsPerYear/365)）だと 4hour/8hour/12hour で
 	// 今日 1 日分の足がすべて確定済と過大評価され、年初の小 limit で前年取得が漏れる。
-	const now = dayjs();
+	const now = dayjs.utc();
 	const startOfYear = now.startOf('year');
 	const intervalMs = INTERVAL_MS[String(type)] ?? 86_400_000;
 	const elapsedThisYearMs = Math.max(0, now.valueOf() - startOfYear.valueOf());
@@ -332,8 +400,20 @@ export default async function getCandles(
 		const localDayEndMs = dayjs.tz(`${y}-${m}-${d}`, anchorTz).endOf('day').valueOf();
 		const intervalMsForDaily = INTERVAL_MS[String(type)] ?? 3_600_000;
 		const lookbackStartMs = localDayEndMs - (limit - 1) * intervalMsForDaily;
-		const windowStartMs = Math.min(localDayStartMs, lookbackStartMs);
-		const windowEndMs = localDayEndMs;
+		// date 省略（realtime）は「現在時刻から遡って limit 本」も window に含める。
+		// tz 暦日終端起点の lookback だけだと、tz 暦日 = UTC 暦日となる tz（UTC 等）で window が
+		// 当日 1 chunk に潰れ、UTC 日開始直後はデータ未生成（success:0）で 0 本、日中も当日分
+		// しか返せず limit 本を満たせない。realtime の意味論は「最新 limit 本」なので now 起点が正。
+		const realtimeLookbackStartMs = !dateProvided
+			? Date.now() - (limit - 1) * intervalMsForDaily
+			: Number.POSITIVE_INFINITY;
+		const windowStartMs = Math.min(localDayStartMs, lookbackStartMs, realtimeLookbackStartMs);
+		// fetch key の列挙は現在時刻でクランプする。date 省略・当日指定では window 終端が
+		// tz 暦日の終端（未来）まで伸びるが、未来の UTC 日 chunk は上流に存在せず 404 が確定
+		// している（docs/internal/bitbank-candle-tz.md）。クランプしないと JST 早朝
+		// （UTC 日付更新前）に「まだ始まっていない UTC 日」を要求し、その 404 が
+		// 過半数失敗と誤判定されて取得済みデータごと捨てられる。
+		const windowEndMs = Math.min(localDayEndMs, Date.now());
 
 		let cursor = dayjs.utc(windowStartMs).startOf('day');
 		const endCursor = dayjs.utc(windowEndMs).startOf('day');
@@ -364,7 +444,8 @@ export default async function getCandles(
 		}
 		const lookbackStartMs = (anchorEndMs as number) - (limit - 1) * intervalMsYearly;
 		const windowStartMs = Math.min(periodStartMs, lookbackStartMs);
-		const windowEndMs = anchorEndMs as number;
+		// 未来の UTC 年 chunk は存在しない（404 確定）ため現在時刻でクランプ（multi-day と同旨）。
+		const windowEndMs = Math.min(anchorEndMs as number, Date.now());
 		multiYearUtcKeys.push(...enumerateUtcYearsIntersectingWindow(windowStartMs, windowEndMs));
 	}
 	// date 未指定時は従来どおり anchorYear から過去方向に yearsNeeded 分だけ fetch。
@@ -405,15 +486,29 @@ export default async function getCandles(
 				if (classified) return classified;
 			}
 
-			// 過半数失敗なら信頼性が低いため fail
-			const totalChunks = merged.results.length;
-			const failedCount = merged.failedKeys.length;
-			if (failedCount > 0 && failedCount >= totalChunks / 2) {
-				return fail(`ローソク足取得の過半数が失敗しました（${totalChunks}年中${failedCount}年失敗）`, 'upstream');
+			// 失敗を「実失敗」と「進行中 UTC 年のデータ未生成（許容）」に分け、実失敗のみで過半数判定する。
+			// 失敗メッセージには key と原因を必ず含める（「N年中M年失敗」だけでは診断不能）。
+			const nowUtcDayKey = dayjs.utc().format('YYYYMMDD');
+			const { hardFailedKeys, expectedGapKeys } = partitionFailedChunks(yearKeys, merged.results, nowUtcDayKey);
+			const totalChunks = merged.results.length - expectedGapKeys.length;
+			if (hardFailedKeys.length > 0 && hardFailedKeys.length >= totalChunks / 2) {
+				const detail = describeFailedChunks(yearKeys, merged.results, new Set(hardFailedKeys));
+				return fail(
+					`ローソク足取得の過半数が失敗しました（${chk.pair}/${type}, ${totalChunks}年中${hardFailedKeys.length}年失敗: ${detail}）`,
+					'upstream',
+				);
 			}
-			if (failedCount > 0) {
-				fetchWarning = `⚠️ ${totalChunks}年中${failedCount}年の取得に失敗しました（${merged.failedKeys.join(', ')}年）。データが不完全な可能性があります。`;
+			const warnLines: string[] = [];
+			if (hardFailedKeys.length > 0) {
+				const detail = describeFailedChunks(yearKeys, merged.results, new Set(hardFailedKeys));
+				warnLines.push(
+					`⚠️ ${totalChunks}年中${hardFailedKeys.length}年の取得に失敗しました（${detail}）。データが不完全な可能性があります。`,
+				);
 			}
+			if (expectedGapKeys.length > 0) {
+				warnLines.push(`ℹ️ UTC 暦年 ${expectedGapKeys.join(', ')} は開始直後でデータ未生成のためスキップしました。`);
+			}
+			if (warnLines.length > 0) fetchWarning = warnLines.join('\n');
 
 			ohlcvs = merged.rows;
 			const years = yearKeys.map(Number);
@@ -443,15 +538,34 @@ export default async function getCandles(
 				if (classified) return classified;
 			}
 
-			// 過半数失敗なら信頼性が低いため fail
-			const totalDays = merged.results.length;
-			const failedCount = merged.failedKeys.length;
-			if (failedCount > 0 && failedCount >= totalDays / 2) {
-				return fail(`ローソク足取得の過半数が失敗しました（${totalDays}日中${failedCount}日失敗）`, 'upstream');
+			// 失敗を「実失敗」と「進行中 UTC 日のデータ未生成（許容）」に分け、実失敗のみで過半数判定する。
+			// 進行中の UTC 日は通常 200 + 部分データを返すが、UTC 日開始直後は chunk 未生成で
+			// 404 になることがある。これを過半数失敗に数えると、取得済みの正当なデータごと捨てて
+			// しまう（JST 早朝の当日取得が全滅する障害の原因）。
+			// 失敗メッセージには key と原因を必ず含める（「N日中M日失敗」だけでは診断不能）。
+			const nowUtcDayKey = dayjs.utc().format('YYYYMMDD');
+			const { hardFailedKeys, expectedGapKeys } = partitionFailedChunks(multiDayUtcKeys, merged.results, nowUtcDayKey);
+			const totalDays = merged.results.length - expectedGapKeys.length;
+			if (hardFailedKeys.length > 0 && hardFailedKeys.length >= totalDays / 2) {
+				const detail = describeFailedChunks(multiDayUtcKeys, merged.results, new Set(hardFailedKeys));
+				return fail(
+					`ローソク足取得の過半数が失敗しました（${chk.pair}/${type}, ${totalDays}日中${hardFailedKeys.length}日失敗: ${detail}）`,
+					'upstream',
+				);
 			}
-			if (failedCount > 0) {
-				fetchWarning = `⚠️ ${totalDays}日中${failedCount}日の取得に失敗しました。データが不完全な可能性があります。`;
+			const warnLines: string[] = [];
+			if (hardFailedKeys.length > 0) {
+				const detail = describeFailedChunks(multiDayUtcKeys, merged.results, new Set(hardFailedKeys));
+				warnLines.push(
+					`⚠️ ${totalDays}日中${hardFailedKeys.length}日の取得に失敗しました（${detail}）。データが不完全な可能性があります。`,
+				);
+			}
+			if (expectedGapKeys.length > 0) {
+				warnLines.push(
+					`ℹ️ UTC 暦日 ${expectedGapKeys.join(', ')} は開始直後でデータ未生成のためスキップしました（当日分は形成され次第、以降の取得で揃います）。`,
+				);
 			}
+			if (warnLines.length > 0) fetchWarning = warnLines.join('\n');
 
 			ohlcvs = merged.rows;
 			json = {
@@ -459,10 +573,18 @@ export default async function getCandles(
 				_multiDay: { daysRequested: multiDayUtcKeys.length, totalFetched: ohlcvs.length },
 			};
 		} else {
-			// 単一リクエスト（YEARLY tz window で 1 UTC 年のみ交差する場合はその年 key）
-			const singleYearKey =
-				yearlyTzWindowActive && multiYearUtcKeys.length === 1 ? multiYearUtcKeys[0] : dateCheck.value;
-			const url = `${BITBANK_API_BASE}/${chk.pair}/candlestick/${type}/${singleYearKey}`;
+			// 単一リクエスト。fetch key は UTC 基準で導出済みの key set を優先する:
+			// - YEARLY tz window で 1 UTC 年のみ交差 → その年 key
+			// - DAILY で UTC 暦日 key が 1 日のみ（クランプ後の当日取得など） → その日 key。
+			//   dateCheck.value（tz 暦日）をそのまま使うと、JST 早朝の当日取得で
+			//   「UTC ではまだ始まっていない日」を要求して 404 になる。
+			const singleKey =
+				yearlyTzWindowActive && multiYearUtcKeys.length === 1
+					? multiYearUtcKeys[0]
+					: isDailyType && multiDayUtcKeys.length >= 1
+						? multiDayUtcKeys[multiDayUtcKeys.length - 1]
+						: dateCheck.value;
+			const url = `${BITBANK_API_BASE}/${chk.pair}/candlestick/${type}/${singleKey}`;
 			const fetchResult = await fetchJsonWithRateLimit(url, {
 				timeoutMs: CANDLE_FETCH.singleTimeoutMs,
 				retries: DEFAULT_RETRIES,
@@ -477,6 +599,18 @@ export default async function getCandles(
 			// 公式 API は { success: 0|1, data: ... } 形式で、エラー時は success:0 を返す。
 			// optional chaining のフォールバックに任せると空配列として握りつぶされ「データなし」(user) として返してしまう。
 			if (jsonObj?.success !== 1) {
+				// 進行中の UTC 期間の success:0 は「データ未生成（UTC 期間の開始直後）」で上流障害ではない。
+				// multi-fetch 経路の expected-gap（partitionFailedChunks）と同じ扱いで user 向けに明示する
+				// （例: tz=UTC × 当日指定が UTC 日開始直後に単一 key へ潰れるケース）。
+				if (isDailyType && String(singleKey) >= dayjs.utc().format('YYYYMMDD')) {
+					return parseAsResult<GetCandlesData, GetCandlesMeta>(
+						GetCandlesOutputSchema,
+						fail(
+							`No candle data available yet for ${chk.pair} / ${type} / ${singleKey} (UTC 暦日の開始直後でデータ未生成です。しばらく待って再試行するか、前日以前の date を指定してください)`,
+							'user',
+						),
+					);
+				}
 				const code = jsonObj?.data?.code;
 				const codeStr = code != null ? `（code: ${code}）` : '';
 				return parseAsResult<GetCandlesData, GetCandlesMeta>(
@@ -697,10 +831,11 @@ export default async function getCandles(
 			priceRange,
 		});
 
-		// 最新足が形成中（未確定）か。realtime 取得（date 未指定）でのみ判定する。
-		// 過去日 anchor は確定足なので注記を付けない（false）。1month の暦依存も含め、
-		// 厳密判定は lib の isLatestBarProvisional に委ねる（自前実装しない）。
-		const provisional = !dateProvided && isLatestBarProvisional(normalized.at(-1)?.timestamp, String(type));
+		// 最新足が形成中（未確定）か。realtime 取得（date 未指定）と、anchor 期間が現在を含む
+		// 当日/当年指定で判定する。過去 anchor は確定足なので注記を付けない（false）。
+		// 1month の暦依存も含め、厳密判定は lib の isLatestBarProvisional に委ねる（自前実装しない）。
+		const anchorIncludesNow = anchorEndMs == null || anchorEndMs > Date.now();
+		const provisional = anchorIncludesNow && isLatestBarProvisional(normalized.at(-1)?.timestamp, String(type));
 
 		// テキスト summary に全ローソク足データを含める
 		// （MCP クライアントが structuredContent.data を読めない場合に対応）

package/tools/get_flow_metrics.ts

@@ -1,6 +1,12 @@
 import { dayjs, toDisplayTime, toIsoTime, toIsoWithTz } from '../lib/datetime.js';
 import { formatSummary } from '../lib/formatter.js';
 import { fail, failFromError, failFromValidation, ok } from '../lib/result.js';
+import {
+	completedUtcDayKeysInRange,
+	currentUtcDayKey,
+	isArchiveExpectedPublished,
+	recentCompletedUtcDayKeys,
+} from '../lib/tx-archive.js';
 import { createMeta, ensurePair, validateLimit } from '../lib/validate.js';
 import { GetFlowMetricsInputSchema, GetFlowMetricsOutputSchema } from '../src/schemas.js';
 import type { ToolDefinition } from '../src/tool-definition.js';
@@ -151,20 +157,13 @@ export default async function getFlowMetrics(
 			const nowMs = Date.now();
 			const sinceMs = nowMs - hours * 3600_000;
 
-			// bitbank の /transactions/{YYYYMMDD} は JST 基準の日付アーカイブ。
-			// 当日分はアーカイブが未生成で 404 を返すことがあるため、当日 URL の失敗は
-			// fatal 扱いせず /transactions (latest) からの補完にフォールバックする。
-			const sinceDayjs = dayjs(sinceMs).tz('Asia/Tokyo');
-			const nowDayjs = dayjs(nowMs).tz('Asia/Tokyo');
-			const todayStr = nowDayjs.format('YYYYMMDD');
-
-			// 必要な日付を YYYYMMDD (JST) 形式で列挙（古い順）
-			const dates: string[] = [];
-			let d = sinceDayjs.startOf('day');
-			while (d.isBefore(nowDayjs) || d.isSame(nowDayjs, 'day')) {
-				dates.push(d.format('YYYYMMDD'));
-				d = d.add(1, 'day');
-			}
+			// bitbank の /transactions/{YYYYMMDD} は UTC 暦日アーカイブで、当該 UTC 日が完了する
+			// まで 404 を返す（実測: docs/internal/bitbank-tx-archive-tz.md）。進行中の UTC 日は
+			// 要求しても必ず 404 なので列挙から除外し、その区間は /transactions (latest) で補完する。
+			// （旧実装は JST 暦日で列挙しており、JST 早朝＝UTC 日付更新前に進行中の UTC 日を
+			// 要求して 404 → 全滅していた。）
+			const currentUtcKey = currentUtcDayKey(nowMs);
+			const dates = completedUtcDayKeysInRange(sinceMs, nowMs);
 
 			// 日付ベース取得（authoritative: 時間範囲をカバー）と latest（supplement: 直近数分の補完）を区別。
 			// 当日分は日付指定だと直近数分が欠ける場合があるため latest も併用する。
@@ -189,12 +188,11 @@ export default async function getFlowMetrics(
 			const dateMerge = mergeTxResults(dateResults, dates);
 			const latestMerge = mergeTxResults([latestResult], ['latest']);
 
-			// 当日 (JST) のアーカイブ欠如は許容: その分は latest から補う。
-			// fatal 扱いするのは「過去日が要求されたのに全て失敗」または「当日のみ要求で latest も失敗」
-			const nonTodayFailures = dateMerge.failures.filter((f) => f.label !== todayStr);
-			const todayFailed = dateMerge.failures.some((f) => f.label === todayStr);
-			const historicalRequested = dates.some((ds) => ds !== todayStr);
-			const historicalAllFailed = historicalRequested && dateMerge.txs.length === 0 && nonTodayFailures.length > 0;
+			// 完了済み UTC 日アーカイブ（authoritative）が全滅した場合は fail。
+			// 進行中の UTC 日は fetch 対象外（アーカイブ未公開）なので、この失敗は実失敗のみ。
+			// 「全滅」は失敗件数 == 要求件数で厳密に判定する（txs.length===0 をプロキシにすると、
+			// 約定 0 件の日 + 一部失敗の組合せを全滅と誤分類する）。
+			const historicalAllFailed = dates.length > 0 && dateMerge.failures.length === dates.length;
 
 			if (historicalAllFailed) {
 				return GetFlowMetricsOutputSchema.parse(
@@ -205,29 +203,28 @@ export default async function getFlowMetrics(
 				);
 			}
 
-			// 過去日が無く (today のみ) かつ today + latest 両方失敗 → 取得手段なし
-			if (!historicalRequested && todayFailed && latestMerge.txs.length === 0) {
-				const allFailures = [...dateMerge.failures, ...latestMerge.failures];
+			// 時間窓が進行中の UTC 日内に収まる（アーカイブ要求なし）場合、latest が唯一のソース。
+			// その latest も失敗したら取得手段なし。
+			if (dates.length === 0 && latestMerge.txs.length === 0 && latestMerge.failures.length > 0) {
 				return GetFlowMetricsOutputSchema.parse(
 					fail(
-						`日付ベース取得（当日 ${todayStr}）と latest の両方が失敗しました（${allFailures.length}件: ${formatFailures(allFailures)}）`,
+						`取得手段がありません: 時間窓が進行中の UTC 日 (${currentUtcKey}) 内のためアーカイブは未公開で、latest 取得も失敗しました（${formatFailures(latestMerge.failures)}）`,
 						'upstream',
 					),
 				);
 			}
 
-			// 部分失敗は警告のみ（latest 失敗は直近数分の欠落、一部 date 失敗は該当日のカバレッジ不足）
+			// 部分失敗・カバレッジ制約は警告で明示（latest 失敗は直近数分の欠落、一部 date 失敗は該当日のカバレッジ不足）
 			const warnMsgs: string[] = [];
-			if (nonTodayFailures.length > 0) {
-				warnMsgs.push(
-					`⚠️ 日付ベース取得で ${dateMerge.totalCount}件中 ${nonTodayFailures.length}件失敗: ${formatFailures(nonTodayFailures)}`,
-				);
-			}
-			if (todayFailed) {
+			if (dateMerge.failures.length > 0) {
 				warnMsgs.push(
-					`⚠️ 当日 (${todayStr}) アーカイブが未公開または取得失敗のため /transactions (latest) から補完しました`,
+					`⚠️ 日付ベース取得で ${dateMerge.totalCount}件中 ${dateMerge.failures.length}件失敗: ${formatFailures(dateMerge.failures)}`,
 				);
 			}
+			// 進行中の UTC 日の区間はアーカイブが存在しないため、常に latest（直近約60件）のみでの補完になる
+			warnMsgs.push(
+				`ℹ️ 進行中の UTC 日 (${currentUtcKey}) のアーカイブは未公開のため、この区間は /transactions (latest, 直近約60件) で補完しています`,
+			);
 			if (latestMerge.failures.length > 0) {
 				warnMsgs.push(
 					`⚠️ 最新約定の補完取得に失敗 (${formatFailures(latestMerge.failures)}) — 直近数分のデータが欠落している可能性があります`,
@@ -256,21 +253,23 @@ export default async function getFlowMetrics(
 
 			if (date) {
 				// 明示的な日付指定がある場合はそのまま取得。
-				// 当日 (JST) はアーカイブ未生成で 404 の可能性があるため latest にフォールバック。
+				// /transactions/{YYYYMMDD} は UTC 暦日アーカイブで、当該 UTC 日が完了するまで未公開
+				// （404）。進行中・未来の UTC 日（JST の「今日」に加え、JST 早朝は「昨日」も該当）を
+				// 指定された場合は latest にフォールバックする。
 				const txRes = await getTransactions(chk.pair, Math.min(lim.value, 1000), date);
-				const isTodayJst = date === dayjs().tz('Asia/Tokyo').format('YYYYMMDD');
+				const archivePublished = isArchiveExpectedPublished(date);
 				if (!txRes?.ok) {
-					if (isTodayJst) {
+					if (!archivePublished) {
 						const latestRes = await getTransactions(chk.pair, Math.min(lim.value, 1000));
 						if (!latestRes?.ok) {
 							return GetFlowMetricsOutputSchema.parse(
 								fail(
-									`date=${date} (today JST) アーカイブ未公開かつ latest 取得も失敗: ${txRes?.summary || 'unknown'} / ${latestRes?.summary || 'unknown'}`,
+									`date=${date} のアーカイブは未公開（UTC 暦日完了後に公開）で、latest 取得も失敗: ${txRes?.summary || 'unknown'} / ${latestRes?.summary || 'unknown'}`,
 									latestRes?.meta?.errorType || 'upstream',
 								),
 							);
 						}
-						fetchWarning = `⚠️ 当日 (${date}) のアーカイブは未公開のため /transactions (latest) から取得しました`;
+						fetchWarning = `⚠️ date=${date} のアーカイブは未公開（/transactions/{YYYYMMDD} は UTC 暦日の完了後に公開）のため /transactions (latest) から取得しました`;
 						// 加工契約: 全ての取得パスで昇順 sort を保証する。
 						// 上流 getTransactions も内部 sort 済みだが、契約の単一ソースをこちらに置く。
 						txs = (latestRes.data.normalized as Tx[]).slice().sort((a, b) => a.timestampMs - b.timestampMs);
@@ -294,18 +293,15 @@ export default async function getFlowMetrics(
 					// 加工契約: 全ての取得パスで昇順 sort を保証する。
 					txs = latestTxs.slice().sort((a, b) => a.timestampMs - b.timestampMs);
 				} else {
-					// latest の返却数が不足 → 前日・前々日の日付ベース取得で補完
-					// bitbank の latest エンドポイントは約60件のみ返却するため
-					const todayJst = dayjs().tz('Asia/Tokyo');
-					const supplementFetches: Promise<unknown>[] = [
-						getTransactions(chk.pair, 1000, todayJst.subtract(1, 'day').format('YYYYMMDD')),
-					];
-					if (lim.value > 500) {
-						supplementFetches.push(getTransactions(chk.pair, 1000, todayJst.subtract(2, 'day').format('YYYYMMDD')));
-					}
-					const supplementResults = await Promise.all(supplementFetches);
+					// latest の返却数が不足（bitbank の latest エンドポイントは約60件のみ返却）
+					// → 完了済み UTC 日アーカイブで補完する。
+					// /transactions/{YYYYMMDD} は UTC 暦日アーカイブ・当該 UTC 日完了後に公開のため、
+					// JST 基準の「昨日」で組むと JST 早朝（UTC 日付更新前）は進行中の UTC 日を
+					// 要求して必ず 404 になる（当該障害の原因）。
+					const supplementDates = recentCompletedUtcDayKeys(lim.value > 500 ? 2 : 1);
+					const supplementResults = await Promise.all(supplementDates.map((ds) => getTransactions(chk.pair, 1000, ds)));
 					const allResults = [latestRes, ...supplementResults];
-					const labels = ['latest', ...supplementFetches.map((_, i) => `supplement-${i + 1}`)];
+					const labels = ['latest', ...supplementDates];
 					const { txs: merged, totalCount, failures } = mergeTxResults(allResults, labels);
 					// 全て失敗した場合は network エラーとして返す
 					if (merged.length === 0 && failures.length > 0) {
@@ -313,19 +309,22 @@ export default async function getFlowMetrics(
 							fail(`upstream fetch all failed (${formatFailures(failures)})`, 'network'),
 						);
 					}
-					// 過半数失敗なら fail
-					if (failures.length > 0 && failures.length >= totalCount / 2) {
-						return GetFlowMetricsOutputSchema.parse(
-							fail(
-								`API取得の過半数が失敗しました（${totalCount}件中${failures.length}件失敗: ${formatFailures(failures)}）`,
-								'upstream',
-							),
-						);
-					}
+					// 補完は best-effort: 何かしら取得できていれば fail せず、失敗と件数不足を警告で明示する。
+					// （latest 成功 + 補完失敗を「過半数失敗」として全体 fail すると、正当に取得できた
+					// 直近データまで捨ててしまう。補完アーカイブは公開遅延等で 404 になり得る。）
+					const warnMsgs: string[] = [];
 					if (failures.length > 0) {
-						fetchWarning = `⚠️ ${totalCount}件中 ${failures.length}件のAPI取得に失敗しました: ${formatFailures(failures)}`;
+						warnMsgs.push(
+							`⚠️ ${totalCount}件中 ${failures.length}件のAPI取得に失敗しました: ${formatFailures(failures)}`,
+						);
 					}
 					txs = merged.sort((a, b) => a.timestampMs - b.timestampMs).slice(-lim.value);
+					if (txs.length < lim.value) {
+						warnMsgs.push(
+							`ℹ️ 要求 ${lim.value}件に対し取得できたのは ${txs.length}件です（進行中の UTC 日のアーカイブは未公開のため取得不可）`,
+						);
+					}
+					if (warnMsgs.length > 0) fetchWarning = warnMsgs.join('\n');
 				}
 			}
 		}
@@ -546,6 +545,7 @@ export const toolDef: ToolDefinition = {
 	name: 'get_flow_metrics',
 	description:
 		`[Flow / CVD / Buy-Sell Pressure] 資金フロー分析（flow / CVD / aggressor ratio / buy-sell pressure）。約定データからCVD・アグレッサー比・スパイクを検出。hours（推奨）で時間範囲指定、または limit で件数指定。` +
+		`\n\nデータソース制約（bitbank 側仕様）: 約定アーカイブ /transactions/{YYYYMMDD} は UTC 暦日単位で、当該 UTC 日の完了後にのみ公開される。進行中の UTC 日（JST 09:00 で切り替わる）の約定は /transactions (latest, 直近約60件) でしか取得できないため、当日区間のカバレッジは限定的（warning で明示される）。` +
 		`\n\n加工契約:` +
 		`\n- 内部で使用する約定列は、取得パスに関わらず timestampMs 昇順にソート済み。` +
 		`\n- latest と date ベースをマージする場合、重複除去キーは \`timestampMs:price:amount:side\`（transaction_id は使用しない: 同一約定でも上流エンドポイント間で ID が一致しないケースがあるため）。`,

package/tools/get_transactions.ts

@@ -4,6 +4,7 @@ import { dayjs, toIsoMs } from '../lib/datetime.js';
 import { formatPair, formatPrice } from '../lib/formatter.js';
 import { BITBANK_API_BASE, DEFAULT_RETRIES, fetchJsonWithRateLimit } from '../lib/http.js';
 import { fail, failFromError, failFromValidation, ok } from '../lib/result.js';
+import { isArchiveExpectedPublished } from '../lib/tx-archive.js';
 import { createMeta, ensurePair, validateLimit } from '../lib/validate.js';
 import {
 	type GetTransactionsDataSchemaOut,
@@ -193,7 +194,16 @@ export default async function getTransactions(pair: string = 'btc_jpy', limit: n
 			});
 		}
 		const baseMsg = e instanceof Error && e.message ? e.message : typeof e === 'string' ? e : 'ネットワークエラー';
-		const wrapped = new Error(`${baseMsg} [url: ${url}]`);
+		// 進行中・未来の UTC 日のアーカイブ 404 は bitbank 側の仕様（UTC 暦日完了後に公開）。
+		// 「なぜ 404 か」を呼び出し側で診断できるようヒントを付与する。
+		// URL 生成（上記）と同じ形式判定に揃える: YYYYMMDD 形式でない date は latest エンドポイントに
+		// フォールバックしており、その 404 にアーカイブ未公開ヒントを付けると誤誘導になる。
+		const isDateArchiveRequest = date != null && /^\d{8}$/.test(String(date));
+		const archiveHint =
+			isDateArchiveRequest && /404/.test(baseMsg) && !isArchiveExpectedPublished(String(date))
+				? `（/transactions/{YYYYMMDD} は UTC 暦日アーカイブで、date=${date} は UTC ではまだ完了していないため未公開です。直近の約定は date 省略の latest を使用してください）`
+				: '';
+		const wrapped = new Error(`${baseMsg} [url: ${url}]${archiveHint}`);
 		return failFromError(wrapped, {
 			schema: GetTransactionsOutputSchema,
 			timeoutMs: 4000,
@@ -207,7 +217,8 @@ export default async function getTransactions(pair: string = 'btc_jpy', limit: n
 export const toolDef: ToolDefinition = {
 	name: 'get_transactions',
 	description:
-		'[Transactions / Trades] 市場の約定履歴（transactions / recent trades）を取得。直近60件 or 日付指定。金額・価格でフィルタ可能。',
+		'[Transactions / Trades] 市場の約定履歴（transactions / recent trades）を取得。直近60件 or 日付指定。金額・価格でフィルタ可能。' +
+		'\n\n制約（bitbank 側仕様）: date 指定（YYYYMMDD）は UTC 暦日アーカイブで、当該 UTC 日の完了後（JST 09:00 以降）にのみ公開される。進行中の UTC 日を指定すると 404。当日分の約定は date 省略（latest, 直近約60件）でのみ取得可能。',
 	inputSchema: GetTransactionsInputSchema,
 	handler: async ({
 		pair,

package/tools/trading_process/lib/svg_to_png.ts

@@ -49,6 +49,15 @@ export async function svgToPng(
 	return outputPath;
 }
 
+/**
+ * ファイル名に埋め込む値からパス区切り・ドット等を除去する。
+ * pair は上流（ensurePair）で検証済みだが、ファイル名の安全性を
+ * 上流バリデーションに依存させないための防御的サニタイズ。
+ */
+function sanitizeFilenamePart(part: string): string {
+	return part.replace(/[^a-zA-Z0-9_-]/g, '');
+}
+
 /**
  * Generate a unique filename for backtest chart
  */
@@ -59,6 +68,6 @@ export function generateBacktestChartFilename(
 	format: 'png' | 'svg' = 'png',
 ): string {
 	const timestamp = dayjs().format('YYYY-MM-DDTHH-mm-ss');
-	const safePair = pair.replace('_', '');
-	return `backtest_${safePair}_${timeframe}_${strategy}_${timestamp}.${format}`;
+	const safePair = sanitizeFilenamePart(pair.replace('_', ''));
+	return `backtest_${safePair}_${sanitizeFilenamePart(timeframe)}_${sanitizeFilenamePart(strategy)}_${timestamp}.${format}`;
 }

package/tools/trading_process/run_backtest.ts

@@ -7,6 +7,7 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { dayjs, formatDateInTz } from '../../lib/datetime.js';
+import { DEFAULT_CHART_OUTPUT_DIR, ensureAllowedOutputDir } from '../../lib/validate.js';
 import { prependWarnings } from '../../lib/warning-propagation.js';
 import { type BacktestEngineInput, type BacktestEngineResult, runBacktestEngine } from './lib/backtest_engine.js';
 import { fetchCandlesForBacktest } from './lib/fetch_candles.js';
@@ -21,7 +22,7 @@ import {
 import type { BacktestRange, Period, Timeframe } from './types.js';
 
 // Claude.ai のデフォルト出力ディレクトリ
-const DEFAULT_OUTPUT_DIR = '/mnt/user-data/outputs';
+const DEFAULT_OUTPUT_DIR = DEFAULT_CHART_OUTPUT_DIR;
 
 /**
  * 書き込み可能なディレクトリを確保
@@ -48,7 +49,7 @@ export interface RunBacktestInput {
 	strategy: StrategyConfig;
 	fee_bp?: number;
 	execution?: 't+1_open';
-	/** 出力ディレクトリ（デフォルト: /mnt/user-data/outputs/） */
+	/** 出力ディレクトリ（デフォルト: /mnt/user-data/outputs/）。許可 root 配下のみ（lib/validate.ts の ensureAllowedOutputDir） */
 	outputDir?: string;
 	/** PNG ファイルを生成する（デフォルト: false、ファイルシステム非共有のため） */
 	savePng?: boolean;
@@ -118,6 +119,17 @@ export default async function runBacktest(input: RunBacktestInput): Promise<RunB
 		}
 		const params = validation.normalizedParams;
 
+		// 出力ディレクトリをバリデーション（savePng 時のみ・fetch 前に弾く）。
+		// LLM 指定の任意パスへの書き込みを許可 root 配下に制限する。
+		let resolvedOutputDir: string | undefined;
+		if (savePng) {
+			const dirCheck = ensureAllowedOutputDir(outputDir);
+			if (!dirCheck.ok) {
+				return { ok: false, error: dirCheck.error.message };
+			}
+			resolvedOutputDir = dirCheck.dir;
+		}
+
 		// 必要なバー数を params から動的に計算（ユーザーが long / slow / signal 等を
 		// デフォルトより大きく指定した場合でもウォームアップを十分確保するため）
 		const requiredBars = strategy.computeRequiredBars(params);
@@ -214,11 +226,11 @@ export default async function runBacktest(input: RunBacktestInput): Promise<RunB
 		};
 
 		// PNG ファイル保存（savePng: true の場合のみ）
-		if (savePng && svg) {
+		if (savePng && svg && resolvedOutputDir) {
 			try {
-				ensureOutputDir(outputDir);
+				ensureOutputDir(resolvedOutputDir);
 				const filename = generateBacktestChartFilename(pair, timeframe, strategyConfig.type, 'png');
-				const pngPath = join(outputDir, filename);
+				const pngPath = join(resolvedOutputDir, filename);
 				await svgToPng(svg, pngPath, { density: 150 });
 				output.chartPath = pngPath;
 			} catch (pngError) {