Telegram Secretary

---
name: telegram-secretary
description: Telegram Bot API の long-polling を cloud routine 上で常駐させ、認可済みチャットからのメッセージに秘書エージェント（SecretaryRole）が即応する対話チャネル。Webhook 不可な cloud routine 環境制約を long-polling + /goal deadline 駆動ループで回避する。
---

# TelegramSecretary — cloud routine 上の Telegram 常駐秘書スキル

## 概要

- **目的**: Gmail より低レイテンシ（数秒）で `<OWNER>` から呼べる常駐秘書。定時通知配信のような push 型に対し、pull/対話型として 24-7 到達口を提供
- **受信方式**: Telegram getUpdates の long-polling（公開 ingress 不要のため **Claude Code Routines**（Anthropic のクラウド実行＝cloud routine）と整合）
- **応答主体**: 親プロセスのエージェント本人が担う（LLM 推論をサブプロセスで多重起動しない設計原則）。本スキルは fetch / 認可 / 正規化 / 送信のみ
- **state 永続化**: `offset.json` + `lease.json` を `state_dir` に保存、heartbeat + TTL リースで並走防止と crash 自己治癒。**管理表（8表: individuals/tasks/knowledge/subjects/abilities/profile/goals/steps）は揮発 state と分離した `registry_dir` に置き、`registry_sync` 有効時は固定ブランチへ git 永続化**（イベント駆動 commit&push + 起動時 fetch、force 不使用）
- **言行一致の保証（WAL、`registry_sync` 有効時）**: registry の push は best-effort ゆえ「登録したと返信したのに未登録」の不整合が起きうる。これを **WAL（Write-Ahead Log）** で防ぐ——登録系の返信の前に intent を WAL ログ（`registry_dir/wal/WAL.jsonl`、同一固定ブランチ）へ先行 push（must-succeed＝push 不能なら送信もしない）し、起動時に未反映分を registry へ redo（key 冪等）。ログは直近 24h の会話文脈の短期記憶も兼ねる。**書き込み口（`add` / `import` / `wal-append` / `wal-redo`）は同一の検証関門を共有**し、redo で落ちた intent は正典へ書かず `dead` へ隔離される（出口は同 key の正しい `add` による自己治癒か `wal-drop`。設計根拠は DESIGN §3.7）
- **アイドル枠ゼロの心臓部**: `/goal` が deadline まで各ターンで foreground `watch --exit-on-message` を回す。メッセージ受信で即 exit→返信→再起動（即応、遅延 ≤ long-poll の timeout）、無メッセージ時は long-poll でブロック（待機トークン最小＋ foreground call でセッション warm 保持）。詳細は [`ROUTINE_PROMPT.md`](../../docs/ROUTINE_PROMPT.md)

## Daily Workflow（cloud routine 起動時）

```
1. Step 0 で `config.json` を読み `agent_name`/`private_dir` を把握 → `source bootstrap.sh` で依存導入 + validate-config（config.json の session_duration_sec 検証含む）+ `TELEGRAM_SECRETARY_SESSION_ID` を env 共有
2. egress 疎通確認（curl api.telegram.org/.../getMe を invalid token で叩いて 401/404 が返ることを確認）
3. lease acquire（他セッション保持中なら exit 4 で即終了＝自己治癒）
4. 起動時オリエンテーション = `orientation` 一撃（role 判定 + 8表の件数/射影 + handoff 最新ブロック）でコンテキストを立ち上げ、今日の役割（秘書/執事/コーチ/守護霊）を確定。**8表を並べて `list` しない**——肥大した registry では出力上限を超えてコンテキストに載らないまま exit 0 する（沈黙失敗、DESIGN §3.12）。本文が要る個票だけ `get --key` で引く。**notes から引いた値を外へ出す前に `## artifacts` に挙がった採択済み成果物を見る**（notes は撤回を書かない監査証跡）。続けて自由時間（autonomous turn）の actionability 判断（grant 下なら継続型タスクの能動 push・STEPS 期限近接の伴走ナッジ・未消化 handoff の消化〔`knowledge search` で既出照合 → knowledge へ結晶化 → `handoff-archive` で卒業〕等を1つ、値しなければ inbound 専念）。詳細は ROUTINE_PROMPT Step 5
5. `/goal` で deadline（`$TELEGRAM_SECRETARY_SESSION_DEADLINE_EPOCH`）まで監視を駆動。各ターン = foreground
   `watch --exit-on-message --max-duration <残り窓> --timeout 30`（この call のみ bash
   `timeout: $TELEGRAM_SECRETARY_POLL_BASH_TIMEOUT_MS`、他は既定 2分）
6. watch 返却後、stdout の JSON Lines を読み、エージェントが SecretaryRole で応答ドラフト → send-reply
   （メッセージ受信なら即応再起動、無ければ窓満了で再起動）
7. lease renew は watch がサイクル毎に内蔵実行（手動 renew 不要）
8. セッション終端で申し送りを `registry_dir/artifacts/handoff/<UTC日時>_<session_id>.md` へ Write → `artifacts-sync`（枠＝ブロック境界。tasks の notes に長文を追記しない。消化済みブロックは `handoff-archive` で `handoff/archive/` へ卒業＝以後 orientation に載らない）→ lease release（次 cron が拾える）
```

各 media item の処理分岐（詳細フローは [`ROUTINE_PROMPT.md`](../../docs/ROUTINE_PROMPT.md)）:

- **`rendered_text` 非 null（`render_status="ok"`）** → そのテキストを直接活用。docx/pptx/xlsx は markdown、voice/audio/video は音声の文字起こし transcript（`kind`/`mime_type` で判別）
- **`derived_image_paths` 非空（PDF）** → PDF は常に画像化される（`rendered_text=""`）。先頭最大 5 枚を Vision で大枠把握し、①全文テキスト（`render-pdf --text`）／②個別ページ精読／③十分 を判断（詳細は下記「PDF の扱い」）
- **`local_path` 非 null + `render_status="passthrough"`** → `Read` ツールで開いて Vision/text 解釈（image/text 系）
- **`render_status="failed"`** → `file_name` 込みで「読めなかった」を短く応答。※音声（PyAV）の壊れ・無音・デコード不可は failed でなく `ok`+空に落ちる → 「無音か、音声として読めないファイルの可能性」と両義応答（媒体別）
- **`render_status="skipped"` + `skip_reason="media_size_exceeded"`** → サイズ超過応答
- **`render_status="skipped"` + `skip_reason=null`** → 未対応 mime、または音声で transcriber 未注入/Medium モード。`mime_type` を見て応答
- **生成物を送り返す** → 図表/レポート等を生成したら `send-reply --file <path>`（複数可、画像→sendPhoto・他→sendDocument 自動振り分け）。`--reply-to <message_id>` で返信スレッド、送信前に typing インジケータ

## PDF の扱い（仕様 SSoT）

PDF は **常に全ページ画像化**する（テキスト層の有無を判定しない）。スタンプ・薄いテキスト層の誤判定（全ページ同一の文書番号印で text 経路に落ち中身が読めない等）を構造的に排除する。**画像化＝決定論（コード）／何を読むか＝判断（エージェント）** の分離（LLM 推論をコード外に出す設計原則）。

**受信時（自動）**: `poll`/`watch` が PDF を受けると `PdfRenderer.render()` が先頭 `pdf_image_max_pages`（既定 20）枚を画像化し、`rendered_text=""` ／ `page_count`（実総数）／ `derived_image_paths`（png パス配列）を emit する。テキスト抽出は **しない**（オンデマンドに分離）。

**エージェントの段階処理**:

1. **大枠把握** — `derived_image_paths` の **先頭最大 5 枚**を `Read` で Vision し、文書の性質と `page_count`（総量）を掴む（20 枚全ては見ない＝トークン節約）
2. **①②③ を判断**:
   - **① 全文テキストが要る** → `render-pdf --path <local_path> --text`（pdfplumber が全ページのテキスト層を `--- page N ---` マーカー付き抽出。スキャン PDF はテキスト層ゼロで空文字を正直に返す）
   - **② 個別ページの精読が要る** → そのページ画像を `Read`。**N ≤ 20 は emit 済み `derived_image_paths[N-1]` を開くだけ（追加コストゼロ）**、**N > 20（cap 超）は `render-pdf --path <local_path> --pages N-M` で初めて生成**してから Read
   - **③ 5 枚で十分** → そのまま応答
3. **多量・不明なら確認** — どこを見るべきか不明・ページ多量なら `send-reply` で「全 N ページの〇〇のようです。どこを見ますか？」と確認してから必要分のみ処理

> **retention 注意**: ② の N>20 遅延生成は元 PDF が `media_retention_hours`（既定 24h）内に残っている必要がある。同一セッション/同日なら確実。後日「あの PDF の 25 ページ」は消えている可能性があり、その場合は再送を促す。

## Subcommands

| Command | 機能 | Exit code |
|---|---|---|
| `validate-config` | env + config.json の検証（session_duration_sec の範囲含む） | 0=OK, 2=設定欠損 |
| `show-config` | 現設定を read-only 表示（秘匿はマスク） | 0（未設定でも 0） |
| `init-config [--session-duration-sec] [--agent-name] [--private-dir] [--force]` | config.json を生成（範囲検証、既存は `--force` で上書き）。対話的収集は `/telegram-secretary` 経由 | 0, 2=範囲外/既存 |
| `lease acquire\|renew\|release [--owner] [--ttl SEC]` | リースロック操作（`--ttl` 既定 300） | 0=成功, 4=conflict, 2=設定欠損 |
| `poll [--timeout SEC]` | getUpdates 1サイクル（`--timeout` long-poll 秒、既定 30）、認可・正規化済み update を JSON Lines で stdout に emit | 0=OK, 1=fetch失敗, 3=auth失敗 |
| `watch [--owner] [--timeout SEC] [--max-iterations N] [--max-duration SEC] [--exit-on-message] [--cleanup-interval N]` | 長期 long-poll ループ。実 message 1件=1行 emit。サイクル毎に lease 自動 renew。`--timeout`=getUpdates long-poll 秒（既定 30）、`--max-duration SEC`=窓満了で exit 0（0=無限）、`--exit-on-message`=メッセージ emit したサイクルで exit 0（即応再起動） | 長時間常駐 / 窓畳み |
| `send-reply --chat-id --update-id --text-file [--owner] [--file ...] [--reply-to]` | エージェント起草の返信送信 → offset advance + lease renew。CLI 層 + UseCase 層の二重 owner 検証。`--file`（複数可）で画像→sendPhoto・他→sendDocument 添付、`--reply-to` で threading | 0=OK, 1=送信失敗, 2=添付不正, 3=auth, 4=lease |
| `proactive-send --chat-id --text-file [--owner] [--file ...] [--reply-to]` | 秘書による能動送信（inbound 非依存の outbound push）→ 送信 + lease renew（**offset 非干渉**＝inbound 専用の既読台帳に触れない）。`registry_sync` 有効時は outbound WAL ライフサイクル（append→push→送信→**settle**→push）を内包し、送信成功分を done 化（happy-path settle＝次回再送しない・別途 wal-append/push 不要）。**`--update-id` 無し**が send-reply との差分。二重 owner 検証・`--file`・`--reply-to` は共通。能力境界は SecretaryRole、再送方針は DESIGN §3.9 | 0=OK, 1=送信失敗, 2=添付不正, 3=auth, 4=lease |
| `test --chat-id` | owner chat に ping 1通 | 0=OK, 1=送信失敗, 3=auth |
| `cleanup-media` | `state_dir/media/` 配下で `media_retention_hours` 超過の保存 media を削除（手動 / cron）。`watch` は `--cleanup-interval` で自動発火（既定 120 サイクル≒1h） | 0=OK, 2=設定欠損 |
| `render-pdf --path <pdf> (--text \| --pages N-M)` | 受信済み PDF のオンデマンド抽出。`--text`=全ページのテキスト層（pdfplumber、`--- page N ---` マーカー）、`--pages N-M`=指定ページ画像化（1-indexed inclusive、cap 超 21 枚目以降用）。結果は JSON 1 行で stdout。`--text`/`--pages` は排他必須 | 0=OK, 2=ファイル不在/引数不正 |
| `lint-numbers <path>` | 納品物・handoff（**原稿 md**）の裸数値スキャン。数字（半角/全角）を含む各行について、**同一行に計器トークン**（`実測` / `見込み` / `出典` / `継承` 等、出所を名指す語形）があるかを二値判定し、JSON 1 行で stdout（keys: `path` / `number_lines` / `covered` / `bare` / `bare_lines`。`bare_lines` は `[[行番号, 行], ...]` で行番号は 1-indexed）。**presence の検査であって正しさの検査ではない**（計器あり ≠ その数が正しい）——読んで分類するのはエージェント側。read-only（config / lease / レジストリに触れない）。**裸 0 件でも JSON 1 行を出す**（黙る計器は掛け忘れと全緑を区別させない）。生 HTML に掛けると属性値・px・hex 色でほぼ全行が候補化する＝仕様なので、対で作る納品物は原稿 md に掛ける（DESIGN §3.13） | 0=OK（裸の有無に依らず）, 2=パス不在/不可読 |
| `individuals\|tasks\|knowledge\|subjects\|abilities\|profile\|goals\|steps {list\|get\|add\|remove\|import}` | 管理表（8表: INDIVIDUALS/TASKS/KNOWLEDGE/SUBJECTS/ABILITIES/PROFILE/GOALS/STEPS）の CRUD。`get`/`remove` は `--key`（uuid/id）、`add` は `--json`/`--json-file`、`import --json-file` は**全件置換**（配列を丸ごと差し替え、stderr に `imported <表>: N -> M records` の差分。全件検証→置換ゆえ 1 件でも不正なら exit 2・無置換）。値オブジェクトで検証。**書き込み口（add / import）はトップレベル未知キーを exit 2 で弾く**（v1.9.0 の fail-closed。typo キーが沈黙で消えるのを止める＝後方非互換。read 経路〔list/get/orientation〕は前方互換のため警告どまりで読める）。**knowledge の `category` は許可集合 10 種のみ**（`observation` / `research` / `harness` / `domain-insight` / `analysis` / `design` / `method` / `philosophy` / `business` / `decision`）——範囲外も**欠落**も、許可集合を列挙した stderr メッセージ付きで exit 2（v1.8.0。暗黙の `"general"` 補完は廃止＝弾かれるだけで、綴りを選び直せる情報はエラー文に載る）。category は**認識の型**の軸専用で、主題（馬・建設 等）の軸は **knowledge の `subjects[]`**（v1.9.0）が持つ——値は SUBJECTS 表の **active な id** と照合し、語彙外・deprecated は候補列挙付き exit 2（空配列・省略は可）。**語彙そのものは SUBJECTS 表＝データ**なので、主題を増やすのは `subjects add`（コード変更・deploy 不要。使わなくなった語は remove せず `status=deprecated`＝過去レコードの読み出しを壊さない）。SSoT は Private JSON、操作主体は SecretaryRole、入口は `/telegram-secretary`。`registry_sync` 有効時は add/remove/import 後に commit&push（イベント駆動） | 0=OK, 2=不正入力 |
| `orientation [--notes-tail N] [--topic-width N] [--handoff-latest N] [--handoff-cap N] [--knowledge-category CAT] [--knowledge-latest N] [--knowledge-subject ID] [--profile-cap N] [--individuals-cap N] [--abilities-cap N] [--goals-cap N] [--tasks-latest N] [--steps-latest N] [--artifacts-latest N]` | **起動時オリエンテーションのダイジェスト**（8表を並べた `list` を置き換える read-only 射影）。role 判定 + 8表の件数/バイト数 + 小表全文（goals）+ **abilities / profile の一行索引**（v1.19.0。abilities は `id\|name\|trigger\|skill_path\|guidance`、profile は `id\|subject\|method\|traits\|content`。件数絞りは無く全件。`trigger` と `traits` は全量、`guidance` / `content` だけ頭を丸め、全文〔profile の `sources` を含む〕は `abilities get --key` / `profile get --key`）+ **individuals の一人一行索引**（v1.18.0。`uuid\|display_name\|role\|status\|chat\|honorific\|tone\|category\|priority_bias\|taboo_topics\|shared_with\|relationship_label\|context_notes`。件数絞りは無く全件——「誰と」の一覧ゆえ母数は減らさない。`chat` は `tg:<id>/line:<id>`、空は `-`。`context_notes` だけ頭を丸め、全文は `individuals get --key <uuid>`）+ tasks 一行要約と active の notes 末尾（既定 4000 バイト）+ **tasks.notes 直後の `## artifacts`**（v1.17.0。`artifacts/` 配下〔`handoff/` を除く〕のファイル名をパス中のタスク id トークン〔`t0007/`・`_t0013_`〕で束ね、**active タスクの群だけ**名前を並べる〔各群 basename 降順＝名前の日付が新しい順、`--artifacts-latest N` で群ごとに頭打ち・見出し `latest N of M files`〕、active 以外の群と untagged は `other: T0013 30, untagged 217` の一行。active で成果物が無い群も `0 files` で載る。**中身は開かない**＝索引はファイル名だけ。notes〔追記のみ・撤回を書かない監査証跡〕から引いた値を外へ出す前に、ここに挙がった採択済み成果物を見るための節）+ knowledge の `id\|subjects\|topic` 索引（既定幅 120 バイト、主題は `/` 連結・未設定は `-`）+ subjects の `id\|label\|aliases\|status\|note` 索引（v1.10.0。件数絞りは無く全件——主題を選ぶ一覧ゆえ母数は減らさない）+ steps の `id\|goal_id\|seq\|status\|title` 索引（v1.10.0）+ handoff 最新ブロック（既定 3 件・各 8000 バイト）を stdout に出す。**counts の直後に `## outbound`（v1.16.0）**——WAL から `last_sent: <created_at> (created_at, UTC) | <本文先頭 topic_width バイト>`（status **done**＝happy-path settle 済み＝送信成功の記録、無ければ `none`）と `pending: N`（intent を書いただけで送信未確定＝**送信済と読まない**）の 2 行。「今日の日報は出したか」の判定材料であり判定そのものではない（時刻は UTC の送信予定時刻＝`created_at` で、送信完了時刻ではない）。**done は `wal-redo` の checkpoint が retention で掃除する**ので `none` は「retention 内に送信確定なし」であって「一度も送っていない」ではない。WAL が読めない枠は `none` で続行し stderr に `outbound wal unreadable` を出す（fail-open）。**幅の単位は UTF-8 バイト**で丸めは文字境界（退避の閾値と同じ単位で数える、DESIGN §3.12）。出力サイズは notes 長に依存せず有界。`--knowledge-category` は索引を category 完全一致で絞る（見出しに `N of M` が載り、絞って落ちた分も可視。該当 0 件でも exit 0＝絞りは観測であって検証ではない）。`--knowledge-subject` は同じ規約で subjects の要素一致に絞る（category と併用可）。`--knowledge-latest` は索引を新しい順 N 件に絞る（既定は未指定＝全件、見出しは `latest N of M, newest last`。選ぶのは新しい順だが並びは id 昇順のまま＝**末尾が最新**、その読み方を見出しの `newest last` が開示する。絞りの順は category → subject → latest）。`--individuals-cap` / `--profile-cap` / `--abilities-cap` は索引行の `context_notes` / `content` / `guidance` 頭の幅（individuals は v1.18.0、profile / abilities は v1.19.0 で意味を移した。引数名は v1.9.0 から不変、未指定なら 120）。`--goals-cap` は**小表の支配的長文フィールド** `notes` をバイト上限で丸める（v1.10.0＝**未指定なら全文**。丸めても個票は `get --key` で全文が引ける。見出しに `full, notes cap N bytes` として開示）、`--tasks-latest` は tasks 一行要約の**終端（done / cancelled 等）だけ**を新しい順 N 件に絞る——**active（open / in_progress / blocked）は件数絞りの対象外で常に全件載る**（v1.15.2。依頼そのものが起動時に見えなくなる形をコードで塞ぐ、DESIGN §3.12）。見出しは `## tasks (A active + latest N of T terminal records, newest last, summary: id \| status \| priority \| due_date \| title)` で active 数 A・終端の母数 T・実際に載った N を開示する（未指定なら従来どおり全件・見出しは `N records`）。notes は載った集合の active に連動＝**active 全件の notes 末尾が載る**。`--steps-latest` は **steps 索引を新しい順 N 件に絞る（未指定なら全件、v1.10.0）**。件数絞り系はいずれも **0 が「全捨て」で未指定へ逆転しない**（`--tasks-latest 0` は「終端を全捨て」＝active だけ載る）。**digest の総バイトは実行のたび stderr に `orientation digest: N bytes` として出る**（v1.8.0。25,600 バイト超では退避の可能性と絞りオプションを添えた警告が付く。stdout・exit code は不変）。深掘りは個別 `get --key` | 0=OK, 2=設定欠損 |
| `knowledge search --query Q [--query Q2] [--any] [--category C] [--subject S] [--limit N] [--topic-width N]` | knowledge の **read-only 検索**（v1.17.0。git にも sync にも触れない）。id / subjects / topic / content に対する部分文字列一致で、両側を NFKC → casefold に正規化してから照合（「ＬＬＭ」と「llm」を別語にしない）。複数 `--query` は既定 **AND**（精査）、`--any` で **OR**（同義語を並べた既出照合）。絞りの順は category → subject → query → limit（orientation の索引と同じ合成順、母数 M は category / subject を掛けた後）。出力は索引行 `id \| subjects \| topic`（content は載せない＝本文は `get --key`）、見出し `## knowledge search (N matches of M records[, latest K …, newest last][, category=…][, subject=…], query: a AND b, index: …)` で一致数・母数・合成則を開示。**0 件でも exit 0**（検索は観測であって検証ではない）。総バイトを stderr に `knowledge search: N bytes` として申告し、25,600 超は退避の可能性と絞り方（`--limit` / 語を足す / `--category` / `--subject`）を警告。新しい知見を焼く前の既出照合の口（自前の全件走査を書かない、ROUTINE_PROMPT Step 11） | 0=OK（0 件でも）, 2=`--query` 無し／knowledge 以外の表 |
| `artifacts-sync` | 成果物層 `registry_dir/artifacts/`（申し送りの `handoff/` ブロックを含む）を固定ブランチへ commit & push。**書き込み CLI は持たない**——秘書が `Write` して、この一手で送る（スキーマレス、DESIGN §3.10/§3.12）。`registry_sync` 無効・`artifacts/` 未作成は no-op | 0=OK（push 失敗は stdout の `pushed=False`、commit はローカルに残り次回再送）, 1=同期処理の例外 |
| `handoff-archive <name>...` | 消化（knowledge への結晶化）を終えた handoff ブロックを `handoff/archive/` へ移し、`artifacts-sync` 経路で送る（卒業）。**orientation は `handoff/` 直下の `*.md` しか読まない契約ゆえ、archive/ へ移したブロックは以後載らない**（消えるのではなく読み筋から外れる）。名前は `handoff/` 直下のファイル名そのもの（複数可）。パス成分を含む名前・不在・archive/ に同名既存は**何も移動せず** exit 2（部分成功を作らない）。どれを卒業させるかは持たない＝消化判断の出力を受ける指名制（DESIGN §3.12）。**卒業後、そのブロックへの参照（notes / knowledge に書いたファイル名）の解決先は「直下 → `archive/`」の二箇所になる**——名前は不変で場所だけが動くため。**直下に無い＝失われた、ではない**ので、`archive/` を見てから判定する | 0=OK（push 失敗は stdout の `pushed=False`、commit はローカルに残り次回再送）, 1=同期処理の例外, 2=不正/不在 |
| `role-status` | PROFILE/GOALS から現在の役割（secretary/butler/coach/anego＝守護霊）を決定論導出し JSON 1行で emit（P=principal の PROFILE≥1、A=active な GOALS≥1。役割の自称をしない＝判定はコード、演技は SecretaryRole。DESIGN §3.11）。起動時は `orientation` の `## role` に同一判定が載るため、単独で叩くのは役割だけ確かめたい時 | 0=OK |
| `registry-sync` | 起動時に固定ブランチから管理表を fetch（`registry_sync` 有効時のみ、無効は no-op）。最新の管理表で起動するため ROUTINE_PROMPT が起動時に1回呼ぶ | 0=OK, 1=fetch失敗 |
| `wal-append --kind <individuals\|tasks\|knowledge\|subjects\|abilities\|profile\|goals\|steps\|outbound> (--json \| --json-file)` | WAL に intent を pending 追記（**登録系の返信の前**、言行一致保証の先行書込）。kind は registry 全8表＋outbound（choices は `REGISTRY_SPEC` 導出＝表追加に自動追従）。**registry kind は `add` と同一の検証を通り、正準化した payload を書く**——未知トップレベルキー・語彙外 subject・許可集合外 category は **exit 2**（stderr `invalid <kind> wal payload: <理由>`）で、**ログを書く前に**止まる。ゆえに **`add` へ渡すのと同一のレコード**（`created_at` / `updated_at` を含む）が要る（後方非互換、v1.11.0）。`outbound` は値オブジェクトを持たないため従来どおり素通し（通常 `proactive-send` が内包するため手動使用は非推奨）。`registry_sync` 有効時のみ・無効は no-op | 0=OK, 2=不正 |
| `wal-push [--message]` | WAL ログを commit & push（**must-succeed**＝失敗は exit 1＝**送信前ゲートで send-reply を中止**）。`registry_sync` 無効は no-op | 0=OK, 1=push失敗 |
| `wal-redo` | 起動時に WAL の pending を redo（`registry_sync` 有効時）。registry kind は upsert（key 冪等・**inbound 返信は再送しない**）、outbound kind は happy-path settle 後に残った中断分のみ1回再送→即 done。**各 intent は `add` と同一の検証を通り、落ちたものは registry へ書かず `dead`（理由付き）へ隔離**する（v1.11.0）。stdout は `wal redo: redone=N resent=N kept=N dead=N`——`dead` は**ログに残る dead の総数**であって今回隔離した分ではない。残存する dead は毎起動 stderr へ `wal redo: dead <kind> key=<key>: <理由>` を 1 行ずつ出す。**exit は 0 のまま**（起動経路を止めない）。ROUTINE_PROMPT が registry-sync 直後に1回呼ぶ | 0=OK |
| `wal-drop --kind <individuals\|tasks\|knowledge\|subjects\|abilities\|profile\|goals\|steps> --key <key>` | `dead` の intent を WAL から落とし、固定ブランチへ **must-succeed** push する（履行しないと決めた約束を明示的に畳む、v1.11.0）。`--kind` / `--key` はどちらも必須で、kind は registry 全8表のみ（`outbound` は検証対象外＝dead にならないため choices に無い）。**pending / done は落とせない**（不在も同じく exit 2）——果たしていない約束を黙って捨てる口は開けない。dead のもう一つの出口は同 key の正しい `add` で、次回 redo の `settle` が done 化する（自己治癒）。stdout `wal dropped <kind> key=<key>`。`registry_sync` 無効は no-op | 0=OK, 1=push失敗, 2=dead でない/不在 |

`--owner` は省略可（`source bootstrap.sh` で env 経由自動同期）。優先順位は `--owner > env > uuid 自動生成`。

## cloud routine ライフサイクル（schedule / unschedule）

`/telegram-secretary` を呼んだエージェントが、この常駐 routine 自体を cloud routine に登録・更新・停止する操作。**Python CLI ではなく `RemoteTrigger` ツール手順**（上記 Subcommands 表＝決定論 CLI とは別系統）。手順の SSoT は [`ROUTINE_PROMPT.md`](../../docs/ROUTINE_PROMPT.md)「cloud routine ライフサイクル管理」節、body shape の正典は内蔵 `schedule` skill。

| 操作 | 機能 | 実体 |
|---|---|---|
| `schedule` | 登録 / 有効化 / 設定上書き（upsert） | `RemoteTrigger create`（不在）or `get→modify→update`（既存）＋ `init-config`（config.json） |
| `unschedule` | 停止（`enabled:false`、二度と起動しない） | `RemoteTrigger update {enabled:false}`。物理削除（list から消す）は claude.ai UI 手動 |

> 秘匿（bot token / authorized chats）は cloud routine の Environment に注入（prompt body・commit に焼かない）。`session_duration_sec` 等の運用設定は `init-config`（決定論）。RemoteTrigger スキーマ罠（events v1 ネスト・session_context 全置換）の回避は ROUTINE_PROMPT / `schedule` skill 参照。

## Failure Modes

| Exit code | 意味 | 対応 |
|---|---|---|
| 0 | 成功 | — |
| 1 | fetch / send 失敗（5xx 再試行後 or 4xx） | 一時的、次サイクルで再試行 |
| 2 | 設定欠損 / 形式不正 / **書き込み口の fail-closed**（未知トップレベルキー・語彙外 subject・許可集合外 category。主語は `add` / `import` / **`wal-append`**） / `wal-drop` の指定違い（dead でない・不在） | env vars 確認。fail-closed は stderr が原因（キー名・候補列挙）を出すので、それを見て直してから再実行。`wal-append` の exit 2 はログを書く前に止まるので、その intent について約束をしない |
| 3 | 401 Unauthorized | bot token 確認・再生成 |
| 4 | リース conflict（他セッション保持中 or lease 不在） | 自己治癒の正常動作 |

> **`list` の 200KB 超警告**（exit code ではない）: 単表の `list` 出力が 200KB を超えると stderr に警告一行が出る（stdout と exit 0 は不変＝fail-open）。この規模はハーネスの出力上限に触れて**コンテキストに載らないまま成功したように見える**領域——警告を見たら `orientation` のダイジェストか `get --key` の個票に切り替える。警告文にレコード内容は含まない（PII 非出力）。機序は DESIGN §3.12。

> **裸検出は exit に載らない**（`lint-numbers`）: 走査が完了すれば**裸の有無に関わらず exit 0** で、二値は **JSON 内の値**（`bare` / `bare_lines`）である。exit 0-4 は外部契約ゆえ「裸あり=1」は fetch 失敗（1）と衝突する——`bare` を読むのは呼び出し側の責務で、exit 0 が言うのは「走査できた」までしかない。exit 2 になるのはパスが読めなかったときだけ。設計根拠は DESIGN §3.13。

## env vars

| Var | Required | 概要 |
|---|---|---|
| `TELEGRAM_BOT_TOKEN` | ✅ | BotFather から取得した bot token |
| `TELEGRAM_SECRETARY_AUTHORIZED_CHATS` | ✅ | JSON array of int (chat_id allowlist) |
| `TELEGRAM_SECRETARY_STATE_DIR` | optional | offset/lease/media の保存先、既定 `./state`（media は `state_dir/media/`） |
| `TELEGRAM_SECRETARY_SESSION_ID` | optional | リース owner ID、省略時は uuid 自動生成。`source bootstrap.sh` で自動 export され、`lease`/`watch`/`send-reply` 全コマンドが同じ owner を共有 |
| `TELEGRAM_SECRETARY_MEDIA_MAX_SIZE_BYTES` | optional | media download のサイズ上限（既定 20MB）。超過は `skip_reason="media_size_exceeded"` で emit、download skip |
| `TELEGRAM_SECRETARY_MEDIA_RETENTION_HOURS` | optional | 保存 media の保持期限（既定 24h）。`cleanup_media_dir` が超過ファイル削除 |
| `TELEGRAM_SECRETARY_MEDIA_ENABLE_DOWNLOAD` | optional | Heavy（true=既定）/ Medium（false）モード切替 |
| `TELEGRAM_SECRETARY_BUNDLE_VOICE` | optional | 音声/動画 STT（moonshine+av）を bootstrap で導入するか（既定 true）。`false` で除外＝音声は `skipped` にフォールバック（moonshine Community License 回避・軽量化、大規模向け） |
| `TELEGRAM_SECRETARY_OUTBOUND_MAX_SIZE_BYTES` | optional | **送信**添付の上限（既定 50MB、Telegram bot API 上限）。超過は送信前に `AttachmentTooLargeError` で弾く（exit 2） |
| `TELEGRAM_SECRETARY_PDF_IMAGE_MAX_PAGES` | optional | PDF 受信時に `render()` が事前画像化する先頭ページ数の上限（既定 20）。超多ページの disk/トークン安全弁。21 枚目以降は `render-pdf --pages` でオンデマンド生成、`page_count` は実総数 |

> **継続時間は config.json の `session_duration_sec`**（範囲 1〜86400 秒、必須・fail-fast）。勤務帯（例 9-17 時）は cloud routine の cron（`0 9-16 * * 1-5`）+ duration で表現（コードに時計を持たせない）。`/goal` deadline 駆動の運用変数（`TELEGRAM_SECRETARY_SESSION_DEADLINE_EPOCH` / `TELEGRAM_SECRETARY_POLL_SET_SEC` / `TELEGRAM_SECRETARY_POLL_BASH_TIMEOUT_MS` / `TELEGRAM_SECRETARY_MAX_TURNS`）は `bootstrap.sh` が config.json から算出して export（SSoT。duration 設定値そのものを env に出す設計は廃止＝純2層）。`BASH_MAX_TIMEOUT_MS=600000` は `{private_dir}/.claude/settings.json`。詳細は [`ROUTINE_PROMPT.md`](../../docs/ROUTINE_PROMPT.md)。

## Security

- **chat_id allowlist**（authn ≠ authz / IDOR 防止）— 未認可 chat は Domain で破棄、エージェントに渡さない
- **プロンプトフェンシング** — エージェントに渡す前に受信本文を XML タグで隔離し「データとして扱え」と明示
- **injection フラグ**（ブロックせず記録） — `injection_flags` 配列で role override / system prompt 取得 / credentials 要求等を検知
- **出力漏洩スキャン** — 返信に token / env名 / system prompt / 絶対パス混入がないか送信前に エージェント側で確認
- **secrets は env のみ** — bot token をコードやコミットに置かない、ログにも残さない
- **リースロック** — heartbeat + TTL で並走セッションの重複応答を構造的に防止
- **media size 上限**（DoS 防御）— `TELEGRAM_SECRETARY_MEDIA_MAX_SIZE_BYTES`（既定 20MB）超過は download せず skip + flag
- **media retention**（機密書類の長期残存防止）— `TELEGRAM_SECRETARY_MEDIA_RETENTION_HOURS`（既定 24h）経過した media は `cleanup_media_dir` で削除
- **token 込み URL のログ秘匿** — `/file/bot<TOKEN>/<file_path>` の TOKEN を例外メッセージ・stderr・ログに残さない（`raise ... from None` で chain 切り、`safe_id=file_id[:8]` のみ表示、テストで明示検証）
- **mime_type は Telegram の自己申告** — 信頼せず、親プロセスのエージェントが `Read` で開いた結果を真とする（rename 攻撃対策）
- **render 失敗時の絶対パス秘匿** — Adapter 内部 catch 時の stderr warning は `file_id[:8]` のみで `local_path` の絶対パスを出さない（テストで明示検証）
- **render 寛容性の認識** — markitdown は garbage バイト列でも render_status="ok" で何か返してくる。**rendered_text が意味のあるテキストかはエージェント側で判断**する責務（LLM 判断をコード外に出す分業）。rename 攻撃で意図しない mime を render させようとする入力にも、エージェントが「内容として妥当か」を判断する層が最終防御
- **PDF テキスト抽出はローカル完結・MIT・pure-python** — `render-pdf --text` の pdfplumber は **ローカルでテキスト層を抽出、PDF が外部に一切出ない**。MIT ライセンスで配布安全。pure-python で OS コマンド実行リスクなし。テキスト層ゼロ（スキャン PDF 等）は render_status="ok" + 空文字で「読めるテキスト無し」を正直に渡す
- **PDF 画像化もローカル完結** — PDF は常に `pypdfium2` で **ローカル画像化**、PDF・派生 png が外部に出ない。受信時は先頭 cap 枚、`render-pdf --pages` で 21 枚目以降をオンデマンド。派生画像は `media/` フラット直下＝既存 `cleanup_media_dir` の retention 対象（機密スキャン画像の残存防止）
- **音声のローカル完結** — Moonshine は**ローカル推論で音声が外部に一切出ない**（機密 voice メモに安全）。Whisper API 等の外部送信 STT を採らなかった設計上の利点
- **transcript の出力漏洩スキャン** — 音声内の機密（パスワード読み上げ等）が transcript 経由で emit に乗る可能性、send-reply 前の漏洩スキャン対象に `rendered_text`(transcript) も含める
- **音声中間ファイルの不在** — PyAV はメモリ内（numpy）で 16kHz mono float へデコードし、**ffmpeg 中間 wav をディスクに書かない**。機密 voice の中間生成物がディスクに残存しない
- **outbound 添付の漏洩スキャン** — エージェント生成物（md/docx/画像/PDF）に token/env名/system prompt/機密が混入していないか**送信前**にエージェント側で確認。コードはバイナリ中身まで検査しない＝エージェントの判断責務
- **outbound サイズ上限**（事故防止）— `TELEGRAM_SECRETARY_OUTBOUND_MAX_SIZE_BYTES`（既定 50MB）超過は送信前に `AttachmentTooLargeError` で弾く
- **送信時 token 込み URL のログ秘匿** — sendPhoto/sendDocument 失敗例外は method/chat_id/file 名のみで URL/token を載せない（受信側 media_downloader と同型、テストで検証）