タイムスタンプ表示・命名に使うタイムゾーンを設定できるようにする

[nrslib]

背景

TAKT では run directory、branch/worktree 名、debug log、session log、task list 表示、trace/report、analytics など複数箇所で timestamp を扱っている。

現状は new Date().toISOString() ベースの UTC 表現や、実行環境の local time に依存する表現が混在している。ユーザーが見る一覧や生成ディレクトリ名では、普段使っているタイムゾーンで時刻を読める方が運用しやすい。

一方で、保存データ・比較・ソート・ログ解析に使う timestamp までローカル時刻へ置き換えると、互換性や機械処理が壊れやすい。

目的

ユーザーが timestamp の表示・命名に使うタイムゾーンを選べるようにする。

内部保存・機械処理用の timestamp は原則として UTC ISO 8601 を維持し、ユーザー向け表示や人間が読むファイル/ディレクトリ名に使う timestamp だけを設定可能にする。

提案仕様

設定キー案:

timezone: Asia/Tokyo

または将来の拡張を見越して以下でもよい。

timestamps:
  timezone: Asia/Tokyo

受け付ける値:

• IANA time zone ID: Asia/Tokyo, UTC, America/Los_Angeles など
• local: 実行環境のローカルタイムゾーン
• 未設定時: 現状互換のため既存挙動を維持する。判断が難しい箇所は UTC をデフォルトとする。

対象範囲

まずは以下のような「ユーザーが見る / 人間が識別する」timestamp を対象にする。

• takt list / interactive list / retry / resume などの表示時刻
• .takt/runs/{timestamp}-{slug} の run directory 名
• worktree / branch 名に含まれる timestamp
• debug directory 名: .takt/runs/debug-{timestamp}
• report history suffix: {filename}.{timestamp}
• trace/report markdown 内の表示時刻
• session log summary / run meta の人間向け表示

対象外

以下は原則 UTC ISO 8601 のまま維持する。

• tasks.yaml / task list serializer の created_at, started_at, completed_at
• .jsonl の event timestamp
• analytics event timestamp
• run meta の startTime, endTime, updatedAt
• ソート・比較・TTL・purge など機械処理に使う timestamp

必要であれば、保存値とは別に表示用 formatter を通す。

実装方針案

• timestamp 生成・表示用の共通 helper を追加する。
  • 例: formatTimestampForDisplay(date, config)
  • 例: formatTimestampForFilename(date, config)
• IANA timezone の妥当性は Intl.DateTimeFormat で検証する。
• 保存用 helper は明示的に UTC ISO のままにする。
  • 例: toStorageTimestamp(date): date.toISOString()
• 既存の new Date().toISOString().replace(...) や toLocaleString() の直接使用を、対象範囲から段階的に置き換える。
• ファイル名用 timestamp は、タイムゾーンを反映してもファイルシステム安全な形式にする。
  • 例: 20260529-153012 または 20260529T153012+0900
  • : や / は使わない。

検討事項

• timezone をグローバル設定だけにするか、プロジェクト設定で override 可能にするか。
• run directory / branch 名は再現性と人間の読みやすさのどちらを優先するか。
• 未設定時の default を完全な現状互換にするか、明示的に UTC とするか。
• タイムゾーン変更後も既存 run / task のソート順が壊れないこと。

受け入れ条件

• 設定で IANA timezone または local を指定できる。
• 指定した timezone が、対象範囲のユーザー向け timestamp 表示に反映される。
• 内部保存・JSONL・analytics・run meta などの機械処理用 timestamp は UTC ISO 8601 のまま維持される。
• 無効な timezone を指定した場合は、明確な設定エラーになる。
• takt list など少なくとも1つ以上の表示系と、run directory または branch/worktree 名の timestamp で回帰テストを追加する。
• タイムゾーン変更によって既存 task / run のソート順が変わらないことを確認する。