記録の開始と管理

デーモンの起動・停止・一時停止・状態確認と、保存データのライフサイクル。

記録はバックグラウンドのデーモン（launchd エージェント）が行い、次のコマンドで制御します。

記録を開始する

zanei start

recorder は起動時に、必要かつ未付与のアクセシビリティと入力監視を 1 回要求します。recorder heartbeat が権限不足を報告すると、バックグラウンド start は終了コード 3 を返しますが、デーモンは degraded 状態で動作を継続します。付与後に zanei stop && zanei start し、zanei doctor で確認してください（権限ガイド）。

フォアグラウンドで試す

デーモン化せずに動きを確かめたいときは 2 つの方法があります。

zanei start --foreground   # デーモンと同じ構成で前面実行（開発・デバッグ用）
zanei record --stream      # 生イベントを NDJSON で stdout に流す

record はパイプ処理や検証向けです。ファイルに書く場合は --out events.jsonl を使います。常用の記録は start です。

状態を確認する

zanei status
zanei status --json   # agent・スクリプト向け

次は抜粋例です。完全な JSON shape と null 条件は CLI リファレンスに定義しています。

{
  "running": true,
  "paused": false,
  "since": "2026-08-16T08:00:00Z",
  "uptime_s": 3600,
  "events_captured": 12345,
  "last_event_ts": "2026-08-16T08:59:58Z",
  "store": { "path": "~/.local/state/zanei/store.sqlite", "size_bytes": 5242880, "retention_hours": 48, "oldest_event_ts": "2026-08-14T09:00:00Z" },
  "capture": { "sources": ["app", "window", "ui", "input", "browser"], "text_content": false },
  "permissions_ok": true
}

対象デーモンが存在しない場合（status / stop など）は終了コード 4 を返します。

recorder の不調を診断する

最初に zanei doctor を実行します。COLLECTOR HEALTH セクションは、現在得られる証拠に基づく状態を報告します。zanei doctor --json では同じ情報を health で取得できます。すべての状態と field は CLI リファレンスに定義しています。

現在の degraded 状態と累積 failure は分けて読みます。

• doctor --json の health.degraded と status --json の degraded は、現在発生している問題だけを示します。人間向け出力では COLLECTOR HEALTH または DEGRADED の下に同じ map を表示します。Chrome と AX の診断 reason は安定した phase / kind と、取得できる場合は元の operation と数値 error code で構成されます。AX で未解消の failure site が複数ある場合は unresolved_sites も報告し、ある PID と operation の回復で別の未解消 site を隠しません。
• collector_failures は collector ごとの失敗回数を永続化した単調増加の count です。人間向け出力では COLLECTOR FAILURES の下に表示します。0 より大きい値は過去に失敗があったことを意味し、それだけでは現在も不調とは判断できません。

fresh かつ current owner に属する recorder status が得られている間、現在の reason は、collector が実際の回復を報告した場合だけ削除されます。collector の予期しない終了後に保持された reason は、再起動した collector が 60 秒間安定稼働した場合にも削除されます。recorder が停止した場合、status が stale になった場合、または永続化済み recorder instance が current owner と一致しなくなった場合、recorder 由来の診断は、回復したためではなく current な証拠が得られないため degraded map から削除されます。retired_store など store の読取時に合成されるエントリは、recorder が動作しているかどうかにかかわらず残ります。recorder 由来の診断がない状態は、CLI リファレンスの正式な定義（recorder health と status field）に従い、状況に応じた health.state（stopped / stale / suspected_unavailable）と store_write_state を併せて解釈してください。回復しても collector_failures は reset されないため、recorder 由来の診断がなく、累積 count が 0 より大きい状態は正常です。

バックグラウンド recorder では、launchd の永続的な診断出力を選択した store の隣に書き込みます。

store path を変更した場合のファイル名は <store>.daemon.stdout.log と <store>.daemon.stderr.log です。どちらも現在のユーザーだけが読み書きできる通常ファイル（0600）です。Zanei はこれらを自動ローテーションしません。含まれるのは recorder の診断情報だけで、捕捉した event payload や text 本文は含まれません。

Zanei は存在しない store directory を mode 0700 で作成し、store と log の配置先 directory が安全でなければ launchd recorder の起動を拒否します。directory は現在のユーザーが所有し、group/world writable であってはなりません。祖先 directory の owner は root または現在のユーザーで、group/world writable な祖先には sticky bit も必要です。アクセスを許可する拡張 ACL entry と、安全に解釈できない ACL entry は拒否されます。

起動 error には安全でない directory が表示されます。意図しない group/world write 権限は削除してください。error が拡張 ACL を示し、その ACL が不要なら、表示された directory から削除します。

chmod go-w /path/to/directory-reported-by-zanei
chmod -N /path/to/directory-reported-by-zanei

その後、zanei start を再実行します。意図的に共有している directory の場合は、この検証を弱めず、owner だけが使用できる store directory を選択してください。

一時停止と再開

会議や画面共有の間だけ記録を止めるには pause を使います。

zanei pause --for 30m   # 30分後に自動で再開
zanei pause             # resume するまで無期限に停止
zanei resume

データのライフサイクル

• 捕捉した event の保存先は、ローカルの SQLite ストア ~/.local/state/zanei/store.sqlite のみです（--store で変更可能）。
• 既定で 48 時間より古いイベントは起動時と定期実行で purge され、読み取り結果からも除外されます（retention_hours、設定）。
• 手動で削除する場合は purge を使います。

zanei purge --before 24h   # 24時間より古いイベントを削除
zanei purge --all          # 全削除（確認プロンプトあり）