warn/errorのTUIへの通知ルート

README.md

@@ -3,16 +3,3 @@
 insomnia(i6a)は不休のエージェントループを回すためのエージェントプラットフォーム。
 
 ワークフローを統括し、四六時中電力を消費し、イテレーションします。
-
-## Crates
-
-| クレート | 概要 |
-|---|---|
-| `insomnia` | トップレベルアプリケーション（未実装） |
-| `llm-worker` | 自律的なLLMシステムを構築するためのライブラリ |
-| `llm-worker-macros` | `llm-worker`用の手続きマクロ (`#[tool_registry]`, `#[tool]`) |
-
-## ドキュメント
-
-- [要件](crates/llm-worker/docs/requirements.md) — llm-workerに求める性能 (R1-R4)
-- [アーキテクチャ](crates/llm-worker/docs/architecture.md) — 3層構成とモジュール配置

TODO.md

@@ -6,6 +6,7 @@
 - [ ] Protocol の設計 → [tickets/protocol-design.md](tickets/protocol-design.md)
 - [ ] パーミッション: パターンベースのツール実行制御 → [tickets/permission-extension-point.md](tickets/permission-extension-point.md)
 - [ ] ネイティブ GUI クライアント MVP → [tickets/native-gui-mvp.md](tickets/native-gui-mvp.md)
+- [ ] Pod Factory: カスケード設定とプロンプト資産 → [tickets/pod-factory.md](tickets/pod-factory.md)
 - [ ] TUI 拡充
   - [ ] 通知チャネル (Warn/Error 可視化) → [tickets/tui-notification-channel.md](tickets/tui-notification-channel.md)
   - [ ] Pod の明示的 shutdown → [tickets/tui-pod-shutdown.md](tickets/tui-pod-shutdown.md)

crates/llm-worker/src/worker.rs

@@ -154,6 +154,11 @@ pub struct Worker<C: LlmClient, S: WorkerState = Mutable> {
     turn_start_cbs: Vec<Box<dyn Fn(usize) + Send + Sync>>,
     /// Turn-end callbacks
     turn_end_cbs: Vec<Box<dyn Fn(usize) + Send + Sync>>,
+    /// Non-fatal warning callbacks. Invoked when the Worker wants to
+    /// surface an advisory message to the upper layer (e.g. Pod) so it
+    /// can be forwarded to the user — distinct from `tracing::warn!`,
+    /// which is for developer-facing logs.
+    warning_cbs: Vec<Box<dyn Fn(&str) + Send + Sync>>,
     /// Request configuration (max_tokens, temperature, etc.)
     request_config: RequestConfig,
     /// Whether the previous run was interrupted
@@ -274,6 +279,23 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
         self.turn_start_cbs.push(Box::new(callback));
     }
 
+    /// Register a non-fatal warning callback.
+    ///
+    /// The callback is invoked with a short human-readable message
+    /// whenever the Worker encounters a condition that should be
+    /// surfaced to a human (e.g. tool output byte-cap truncation).
+    /// This channel is separate from `tracing::warn!`, which remains
+    /// in place for developer logs.
+    pub fn on_warning(&mut self, callback: impl Fn(&str) + Send + Sync + 'static) {
+        self.warning_cbs.push(Box::new(callback));
+    }
+
+    fn emit_warning(&self, message: &str) {
+        for cb in &self.warning_cbs {
+            cb(message);
+        }
+    }
+
     /// Register a turn-end callback (receives 0-based turn number).
     pub fn on_turn_end(&mut self, callback: impl Fn(usize) + Send + Sync + 'static) {
         self.turn_end_cbs.push(Box::new(callback));
@@ -696,6 +718,13 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
                         limit_bytes = limit,
                         "Tool output exceeded byte limit and was truncated"
                     );
+                    self.emit_warning(&format!(
+                        "tool `{}` output truncated from {} to {} bytes (limit {})",
+                        tool_call.name,
+                        before,
+                        content.len(),
+                        limit
+                    ));
                 }
             }
         }
@@ -962,6 +991,7 @@ impl<C: LlmClient> Worker<C, Mutable> {
             max_turns: None,
             turn_start_cbs: Vec::new(),
             turn_end_cbs: Vec::new(),
+            warning_cbs: Vec::new(),
             request_config: RequestConfig::default(),
             last_run_interrupted: false,
             cancel_tx,
@@ -1214,6 +1244,7 @@ impl<C: LlmClient> Worker<C, Mutable> {
             max_turns: self.max_turns,
             turn_start_cbs: self.turn_start_cbs,
             turn_end_cbs: self.turn_end_cbs,
+            warning_cbs: self.warning_cbs,
             request_config: self.request_config,
             last_run_interrupted: self.last_run_interrupted,
 
@@ -1286,6 +1317,7 @@ impl<C: LlmClient> Worker<C, Locked> {
             max_turns: self.max_turns,
             turn_start_cbs: self.turn_start_cbs,
             turn_end_cbs: self.turn_end_cbs,
+            warning_cbs: self.warning_cbs,
             request_config: self.request_config,
             last_run_interrupted: self.last_run_interrupted,
 

crates/pod/src/agents_md.rs

@@ -18,21 +18,43 @@ pub(crate) const AGENTS_MD_LIMIT: usize = 64 * 1024;
 
 const TRUNCATION_NOTICE: &str = "\n\n[truncated: AGENTS.md exceeded 64KB limit]";
 
-/// Read `AGENTS.md` from `cwd` if present. Returns `None` for "absent or
+/// Outcome of an `AGENTS.md` ingestion attempt.
-/// unreadable"; all non-fatal problems are logged via `tracing::warn!`.
 ///
-/// - Absent: `None`, no warn.
+/// `body` carries the text that should be handed to the template
-/// - Over limit: first 64KB (UTF-8 char boundary) + truncation notice, warn.
+/// engine (if any); `warnings` are short human-readable messages that
-/// - Non-UTF-8 or I/O error: `None`, warn.
+/// Pod forwards to the user-facing notification channel. The caller
-pub(crate) fn read_agents_md(cwd: &Path) -> Option<String> {
+/// also gets `tracing::warn!` lines for the developer log.
+pub(crate) struct AgentsMdResult {
+    pub body: Option<String>,
+    pub warnings: Vec<String>,
+}
+
+/// Read `AGENTS.md` from `cwd` if present. All non-fatal problems are
+/// both logged via `tracing::warn!` (developer-facing) and surfaced
+/// via `AgentsMdResult::warnings` (user-facing).
+///
+/// - Absent: `body = None`, no warning.
+/// - Over limit: first 64KB (UTF-8 char boundary) + truncation notice, warning.
+/// - Non-UTF-8 or I/O error: `body = None`, warning.
+pub(crate) fn read_agents_md(cwd: &Path) -> AgentsMdResult {
     let path = cwd.join("AGENTS.md");
+    let mut warnings = Vec::new();
 
     let file = match File::open(&path) {
         Ok(f) => f,
-        Err(e) if e.kind() == ErrorKind::NotFound => return None,
+        Err(e) if e.kind() == ErrorKind::NotFound => {
+            return AgentsMdResult {
+                body: None,
+                warnings,
+            };
+        }
         Err(e) => {
             warn!(path = %path.display(), error = %e, "failed to open AGENTS.md");
-            return None;
+            warnings.push(format!("failed to open AGENTS.md ({}): {}", path.display(), e));
+            return AgentsMdResult {
+                body: None,
+                warnings,
+            };
         }
     };
 
@@ -42,7 +64,11 @@ pub(crate) fn read_agents_md(cwd: &Path) -> Option<String> {
     let read_limit = (AGENTS_MD_LIMIT as u64) + 1;
     if let Err(e) = file.take(read_limit).read_to_end(&mut buf) {
         warn!(path = %path.display(), error = %e, "failed to read AGENTS.md");
-        return None;
+        warnings.push(format!("failed to read AGENTS.md ({}): {}", path.display(), e));
+        return AgentsMdResult {
+            body: None,
+            warnings,
+        };
     }
 
     let truncated = buf.len() > AGENTS_MD_LIMIT;
@@ -69,7 +95,15 @@ pub(crate) fn read_agents_md(cwd: &Path) -> Option<String> {
         }
         Err(e) => {
             warn!(path = %path.display(), error = %e, "AGENTS.md is not valid UTF-8");
-            return None;
+            warnings.push(format!(
+                "AGENTS.md ({}) is not valid UTF-8: {}",
+                path.display(),
+                e
+            ));
+            return AgentsMdResult {
+                body: None,
+                warnings,
+            };
         }
     };
 
@@ -80,10 +114,18 @@ pub(crate) fn read_agents_md(cwd: &Path) -> Option<String> {
             limit = AGENTS_MD_LIMIT,
             "AGENTS.md exceeded size limit; truncating"
         );
+        warnings.push(format!(
+            "AGENTS.md ({}) exceeded {} bytes; the tail was truncated",
+            path.display(),
+            AGENTS_MD_LIMIT
+        ));
         text.push_str(TRUNCATION_NOTICE);
     }
 
-    Some(text)
+    AgentsMdResult {
+        body: Some(text),
+        warnings,
+    }
 }
 
 #[cfg(test)]
@@ -95,17 +137,16 @@ mod tests {
     #[test]
     fn absent_file_returns_none() {
         let dir = TempDir::new().unwrap();
-        assert!(read_agents_md(dir.path()).is_none());
+        assert!(read_agents_md(dir.path()).body.is_none());
     }
 
     #[test]
     fn reads_small_file_verbatim() {
         let dir = TempDir::new().unwrap();
         fs::write(dir.path().join("AGENTS.md"), "# hello\nworld").unwrap();
-        assert_eq!(
+        let result = read_agents_md(dir.path());
-            read_agents_md(dir.path()).as_deref(),
+        assert_eq!(result.body.as_deref(), Some("# hello\nworld"));
-            Some("# hello\nworld"),
+        assert!(result.warnings.is_empty());
-        );
     }
 
     #[test]
@@ -114,11 +155,13 @@ mod tests {
         let body = "a".repeat(AGENTS_MD_LIMIT + 1024);
         fs::write(dir.path().join("AGENTS.md"), &body).unwrap();
 
-        let got = read_agents_md(dir.path()).expect("some");
+        let result = read_agents_md(dir.path());
+        let got = result.body.expect("some");
         assert!(got.ends_with(TRUNCATION_NOTICE));
         let prefix = got.strip_suffix(TRUNCATION_NOTICE).unwrap();
         assert_eq!(prefix.len(), AGENTS_MD_LIMIT);
         assert!(prefix.chars().all(|c| c == 'a'));
+        assert_eq!(result.warnings.len(), 1);
     }
 
     #[test]
@@ -127,9 +170,11 @@ mod tests {
         let body = "a".repeat(AGENTS_MD_LIMIT);
         fs::write(dir.path().join("AGENTS.md"), &body).unwrap();
 
-        let got = read_agents_md(dir.path()).expect("some");
+        let result = read_agents_md(dir.path());
+        let got = result.body.expect("some");
         assert_eq!(got.len(), AGENTS_MD_LIMIT);
         assert!(!got.contains("truncated"));
+        assert!(result.warnings.is_empty());
     }
 
     #[test]
@@ -142,12 +187,23 @@ mod tests {
         body.push_str(&"b".repeat(128));
         fs::write(dir.path().join("AGENTS.md"), &body).unwrap();
 
-        let got = read_agents_md(dir.path()).expect("some");
+        let result = read_agents_md(dir.path());
+        let got = result.body.expect("some");
         assert!(got.ends_with(TRUNCATION_NOTICE));
         let prefix = got.strip_suffix(TRUNCATION_NOTICE).unwrap();
         // The partial 'あ' must have been dropped, leaving only the ASCII prefix.
         assert_eq!(prefix.len(), AGENTS_MD_LIMIT - 1);
         assert!(prefix.chars().all(|c| c == 'a'));
+        assert_eq!(result.warnings.len(), 1);
+    }
+
+    #[test]
+    fn non_utf8_surfaces_warning() {
+        let dir = TempDir::new().unwrap();
+        fs::write(dir.path().join("AGENTS.md"), [0xff, 0xfe, 0xfd]).unwrap();
+        let result = read_agents_md(dir.path());
+        assert!(result.body.is_none());
+        assert_eq!(result.warnings.len(), 1);
     }
 
     #[test]
@@ -159,7 +215,7 @@ mod tests {
         let dir = TempDir::new().unwrap();
         let body = vec![0xffu8; AGENTS_MD_LIMIT + 1024];
         fs::write(dir.path().join("AGENTS.md"), body).unwrap();
-        assert!(read_agents_md(dir.path()).is_none());
+        assert!(read_agents_md(dir.path()).body.is_none());
     }
 
     #[test]
@@ -167,6 +223,6 @@ mod tests {
         let dir = TempDir::new().unwrap();
         // Invalid UTF-8 start byte.
         fs::write(dir.path().join("AGENTS.md"), [0xff, 0xfe, 0xfd]).unwrap();
-        assert!(read_agents_md(dir.path()).is_none());
+        assert!(read_agents_md(dir.path()).body.is_none());
     }
 }

crates/pod/src/controller.rs

@@ -6,11 +6,12 @@ use llm_worker::llm_client::client::LlmClient;
 use session_store::Store;
 use tokio::sync::{broadcast, mpsc};
 
+use crate::notifier::Notifier;
 use crate::pod::{Pod, PodError, PodRunResult};
 use crate::runtime_dir::RuntimeDir;
 use crate::shared_state::{PodSharedState, PodStatus};
 use crate::socket_server::SocketServer;
-use protocol::{ErrorCode, Event, Method, RunResult, TurnResult};
+use protocol::{ErrorCode, Event, Method, NotificationLevel, NotificationSource, RunResult, TurnResult};
 
 // ---------------------------------------------------------------------------
 // PodHandle — client-facing, Clone-able
@@ -22,6 +23,7 @@ pub struct PodHandle {
     event_tx: broadcast::Sender<Event>,
     pub shared_state: Arc<PodSharedState>,
     pub runtime_dir: Arc<RuntimeDir>,
+    pub notifier: Notifier,
 }
 
 impl PodHandle {
@@ -37,6 +39,11 @@ impl PodHandle {
     pub fn send_event(&self, event: Event) -> Result<usize, broadcast::error::SendError<Event>> {
         self.event_tx.send(event)
     }
+
+    /// Emit a user-facing notification. Thin wrapper over `Notifier::notify`.
+    pub fn notify(&self, level: NotificationLevel, source: NotificationSource, message: String) {
+        self.notifier.notify(level, source, message);
+    }
 }
 
 // ---------------------------------------------------------------------------
@@ -56,6 +63,7 @@ impl PodController {
     {
         let (method_tx, mut method_rx) = mpsc::channel::<Method>(32);
         let (event_tx, _) = broadcast::channel::<Event>(256);
+        let notifier = Notifier::new(event_tx.clone());
 
         let manifest_toml = toml::to_string_pretty(pod.manifest()).unwrap_or_default();
         let greeting = build_greeting(&pod);
@@ -78,8 +86,14 @@ impl PodController {
             event_tx: event_tx.clone(),
             shared_state: shared_state.clone(),
             runtime_dir: runtime_dir.clone(),
+            notifier: notifier.clone(),
         };
 
+        // Hand the notifier to the Pod so internal operations (compaction,
+        // AGENTS.md ingestion during the first turn) can emit user-facing
+        // notifications on the same channel.
+        pod.attach_notifier(notifier.clone());
+
         // Start socket server (lives as a background task, cleaned up on drop via RuntimeDir)
         let _socket_server = SocketServer::start(&handle).await?;
         // Keep the server alive by moving it into the controller task
@@ -163,6 +177,15 @@ impl PodController {
                 });
             });
 
+            let notifier_for_worker = notifier.clone();
+            worker.on_warning(move |message| {
+                notifier_for_worker.notify(
+                    NotificationLevel::Warn,
+                    NotificationSource::Worker,
+                    message.to_owned(),
+                );
+            });
+
             // Register the builtin file-manipulation tools (Read / Write /
             // Edit / Glob / Grep). `ScopedFs` carries the pod-lifetime
             // scope/pwd; `Tracker` is session-scoped — a fresh instance per
@@ -215,6 +238,11 @@ impl PodController {
                         if new_status == PodStatus::Idle {
                             if let Err(e) = pod.try_post_run_compact().await {
                                 tracing::warn!(error = %e, "Post-run compaction error");
+                                notifier.notify(
+                                    NotificationLevel::Warn,
+                                    NotificationSource::Compactor,
+                                    format!("post-run compaction error: {e}"),
+                                );
                             }
                         }
 
@@ -249,6 +277,11 @@ impl PodController {
                         if new_status == PodStatus::Idle {
                             if let Err(e) = pod.try_post_run_compact().await {
                                 tracing::warn!(error = %e, "Post-run compaction error");
+                                notifier.notify(
+                                    NotificationLevel::Warn,
+                                    NotificationSource::Compactor,
+                                    format!("post-run compaction error: {e}"),
+                                );
                             }
                         }
 

crates/pod/src/lib.rs

@@ -1,5 +1,6 @@
 pub mod controller;
 pub mod hook;
+pub mod notifier;
 pub mod runtime_dir;
 pub mod shared_state;
 pub mod socket_server;
@@ -17,6 +18,7 @@ mod usage_tracker;
 pub use token_counter::{EstimateSource, SplitPoint, TokenEstimate};
 
 pub use controller::{PodController, PodHandle};
+pub use notifier::Notifier;
 pub use hook::{Hook, HookEventKind, HookRegistryBuilder};
 pub use manifest::{PodManifest, ProviderConfig, ProviderKind, Scope};
 pub use pod::{Pod, PodError, PodRunResult, apply_worker_manifest};

crates/pod/src/notifier.rs

@@ -0,0 +1,191 @@
+//! User-facing notification channel for Pod → client.
+//!
+//! Separate from `tracing` (which is for developer logs). Notifications
+//! are short human-readable messages the Pod layer wants a client to
+//! see — for example "compaction failed", "tool output truncated".
+//!
+//! Each notification is broadcast on the shared `Event` channel and
+//! also appended to an in-memory buffer so that clients connecting
+//! after the fact still see everything emitted during the session.
+
+use std::collections::VecDeque;
+use std::sync::{Arc, Mutex};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use tokio::sync::broadcast;
+
+use protocol::{Event, Notification, NotificationLevel, NotificationSource};
+
+/// Upper bound on buffered notifications. When exceeded, the oldest
+/// entries are discarded so a long-running session cannot leak
+/// memory through a pathological loop of recurring notifications
+/// (e.g. compaction failing every turn).
+const MAX_BUFFERED_NOTIFICATIONS: usize = 512;
+
+#[derive(Clone)]
+pub struct Notifier {
+    inner: Arc<Inner>,
+}
+
+struct Inner {
+    event_tx: broadcast::Sender<Event>,
+    buffer: Mutex<VecDeque<Notification>>,
+}
+
+impl Notifier {
+    pub fn new(event_tx: broadcast::Sender<Event>) -> Self {
+        Self {
+            inner: Arc::new(Inner {
+                event_tx,
+                buffer: Mutex::new(VecDeque::with_capacity(MAX_BUFFERED_NOTIFICATIONS)),
+            }),
+        }
+    }
+
+    /// Record and broadcast a notification.
+    ///
+    /// The broadcast may have no subscribers (e.g. during Pod
+    /// construction before any client has connected); the buffer
+    /// guarantees the message is still delivered once a client
+    /// attaches.
+    ///
+    /// The buffer mutex is held across `broadcast::send` to make
+    /// `subscribe_with_snapshot` race-free — a client that snapshots
+    /// the buffer while holding the same lock sees every notification
+    /// exactly once: older ones from the snapshot, newer ones from
+    /// the freshly-subscribed receiver.
+    pub fn notify(&self, level: NotificationLevel, source: NotificationSource, message: String) {
+        let notification = Notification {
+            level,
+            source,
+            message,
+            timestamp_ms: now_ms(),
+        };
+        if let Ok(mut buf) = self.inner.buffer.lock() {
+            if buf.len() >= MAX_BUFFERED_NOTIFICATIONS {
+                buf.pop_front();
+            }
+            buf.push_back(notification.clone());
+            let _ = self
+                .inner
+                .event_tx
+                .send(Event::Notification(notification));
+        }
+    }
+
+    /// Subscribe and atomically snapshot the current buffer.
+    ///
+    /// The returned snapshot contains notifications emitted before
+    /// this call; the receiver will deliver notifications emitted
+    /// after. A notification cannot appear in both.
+    pub fn subscribe_with_snapshot(&self) -> (Vec<Notification>, broadcast::Receiver<Event>) {
+        let buf = self
+            .inner
+            .buffer
+            .lock()
+            .expect("notifier buffer mutex poisoned");
+        let rx = self.inner.event_tx.subscribe();
+        let snapshot: Vec<Notification> = buf.iter().cloned().collect();
+        (snapshot, rx)
+    }
+}
+
+fn now_ms() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_millis() as i64)
+        .unwrap_or(0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn notify_broadcasts_to_existing_subscriber() {
+        let (tx, _keep) = broadcast::channel::<Event>(8);
+        let notifier = Notifier::new(tx);
+        let (_snapshot, mut rx) = notifier.subscribe_with_snapshot();
+
+        notifier.notify(
+            NotificationLevel::Warn,
+            NotificationSource::Compactor,
+            "test message".into(),
+        );
+
+        match rx.try_recv() {
+            Ok(Event::Notification(n)) => assert_eq!(n.message, "test message"),
+            other => panic!("unexpected event: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn late_subscriber_sees_earlier_notifications_via_snapshot() {
+        let (tx, _keep) = broadcast::channel::<Event>(8);
+        let notifier = Notifier::new(tx);
+
+        notifier.notify(
+            NotificationLevel::Error,
+            NotificationSource::Pod,
+            "first".into(),
+        );
+        notifier.notify(
+            NotificationLevel::Warn,
+            NotificationSource::AgentsMd,
+            "second".into(),
+        );
+
+        let (snapshot, mut rx) = notifier.subscribe_with_snapshot();
+        assert_eq!(snapshot.len(), 2);
+        assert_eq!(snapshot[0].message, "first");
+        assert_eq!(snapshot[1].message, "second");
+        assert!(rx.try_recv().is_err()); // nothing pending on the receiver
+    }
+
+    #[test]
+    fn buffer_discards_oldest_past_cap() {
+        let (tx, _keep) = broadcast::channel::<Event>(1024);
+        let notifier = Notifier::new(tx);
+
+        for i in 0..(MAX_BUFFERED_NOTIFICATIONS + 50) {
+            notifier.notify(
+                NotificationLevel::Warn,
+                NotificationSource::Worker,
+                format!("msg-{i}"),
+            );
+        }
+
+        let (snapshot, _rx) = notifier.subscribe_with_snapshot();
+        assert_eq!(snapshot.len(), MAX_BUFFERED_NOTIFICATIONS);
+        // First 50 were evicted; the oldest remaining is msg-50.
+        assert_eq!(snapshot.first().unwrap().message, "msg-50");
+        let last = format!("msg-{}", MAX_BUFFERED_NOTIFICATIONS + 49);
+        assert_eq!(snapshot.last().unwrap().message, last);
+    }
+
+    #[test]
+    fn subscribe_snapshot_and_live_do_not_overlap() {
+        let (tx, _keep) = broadcast::channel::<Event>(8);
+        let notifier = Notifier::new(tx);
+
+        notifier.notify(
+            NotificationLevel::Warn,
+            NotificationSource::Worker,
+            "historic".into(),
+        );
+        let (snapshot, mut rx) = notifier.subscribe_with_snapshot();
+        notifier.notify(
+            NotificationLevel::Error,
+            NotificationSource::Worker,
+            "live".into(),
+        );
+
+        assert_eq!(snapshot.len(), 1);
+        assert_eq!(snapshot[0].message, "historic");
+        match rx.try_recv() {
+            Ok(Event::Notification(n)) => assert_eq!(n.message, "live"),
+            other => panic!("unexpected: {other:?}"),
+        }
+        assert!(rx.try_recv().is_err());
+    }
+}

crates/pod/src/pod.rs

@@ -21,8 +21,10 @@ use crate::hook::{
     PreToolCall,
 };
 use crate::hook_interceptor::HookInterceptor;
+use crate::notifier::Notifier;
 use crate::system_prompt::{SystemPromptContext, SystemPromptError, SystemPromptTemplate};
 use crate::usage_tracker::UsageTracker;
+use protocol::{NotificationLevel, NotificationSource};
 use async_trait::async_trait;
 use llm_worker::interceptor::PreRequestAction;
 
@@ -97,6 +99,9 @@ pub struct Pod<C: LlmClient, St: Store> {
     /// `Some` until `ensure_system_prompt_materialized` renders it once,
     /// then `None` forever — including after compaction.
     system_prompt_template: Option<SystemPromptTemplate>,
+    /// User-facing notification sink attached by the Controller at
+    /// spawn time. `None` in tests / direct `Pod::new` usage.
+    notifier: Option<Notifier>,
 }
 
 impl<C: LlmClient, St: Store> Pod<C, St> {
@@ -137,6 +142,7 @@ impl<C: LlmClient, St: Store> Pod<C, St> {
             usage_history: Arc::new(Mutex::new(Vec::<UsageRecord>::new())),
             tracker: None,
             system_prompt_template: None,
+            notifier: None,
         };
         pod.apply_prune_from_manifest();
         Ok(pod)
@@ -185,6 +191,7 @@ impl<C: LlmClient, St: Store> Pod<C, St> {
             usage_history: Arc::new(Mutex::new(state.usage_history)),
             tracker: None,
             system_prompt_template: None,
+            notifier: None,
         };
         pod.apply_prune_from_manifest();
         Ok(pod)
@@ -275,6 +282,21 @@ impl<C: LlmClient, St: Store> Pod<C, St> {
         self.tracker.as_ref()
     }
 
+    /// Attach a user-facing notification sink.
+    ///
+    /// Called by the Controller immediately after spawning so that
+    /// Pod-internal operations (compaction failures, AGENTS.md
+    /// ingestion warnings) can surface messages to connected clients.
+    pub fn attach_notifier(&mut self, notifier: Notifier) {
+        self.notifier = Some(notifier);
+    }
+
+    fn notify(&self, level: NotificationLevel, source: NotificationSource, message: String) {
+        if let Some(n) = self.notifier.as_ref() {
+            n.notify(level, source, message);
+        }
+    }
+
     // --- Hook registration ---
 
     fn assert_hooks_open(&self) {
@@ -392,6 +414,7 @@ impl<C: LlmClient, St: Store> Pod<C, St> {
         let Some(template) = self.system_prompt_template.take() else {
             return Ok(());
         };
+        let notifier = self.notifier.clone();
         let worker = self.worker.as_mut().expect("worker present");
         // Materialise any pending tool factories so the template sees the
         // full list of tool names. Redundant with the flush inside
@@ -404,7 +427,17 @@ impl<C: LlmClient, St: Store> Pod<C, St> {
             .map(|d| d.name)
             .collect();
         let mut files = std::collections::BTreeMap::new();
-        if let Some(body) = read_agents_md(&self.pwd) {
+        let agents_md = read_agents_md(&self.pwd);
+        for warning in agents_md.warnings {
+            if let Some(n) = notifier.as_ref() {
+                n.notify(
+                    NotificationLevel::Warn,
+                    NotificationSource::AgentsMd,
+                    warning,
+                );
+            }
+        }
+        if let Some(body) = agents_md.body {
             files.insert("agents_md".to_string(), body);
         }
         let ctx = SystemPromptContext {
@@ -553,6 +586,11 @@ impl<C: LlmClient, St: Store> Pod<C, St> {
                 }
                 Err(e) => {
                     warn!(error = %e, "Compaction failed during run");
+                    self.notify(
+                        NotificationLevel::Error,
+                        NotificationSource::Compactor,
+                        format!("mid-run compaction failed: {e}"),
+                    );
                     if let Some(ref state) = self.compact_state {
                         state.record_compact_failure();
                     }
@@ -583,6 +621,11 @@ impl<C: LlmClient, St: Store> Pod<C, St> {
             }
             Err(e) => {
                 warn!(error = %e, "Proactive post-run compaction failed");
+                self.notify(
+                    NotificationLevel::Warn,
+                    NotificationSource::Compactor,
+                    format!("post-run compaction failed: {e}"),
+                );
                 state.record_compact_failure();
                 Ok(())
             }
@@ -830,6 +873,7 @@ impl<St: Store> Pod<Box<dyn LlmClient>, St> {
             usage_history: Arc::new(Mutex::new(Vec::new())),
             tracker: None,
             system_prompt_template,
+            notifier: None,
         };
         pod.apply_prune_from_manifest();
         Ok(pod)

crates/pod/src/socket_server.rs

@@ -61,7 +61,21 @@ async fn handle_connection(stream: tokio::net::UnixStream, handle: PodHandle) {
     let (reader, writer) = stream.into_split();
     let mut reader = JsonLineReader::new(reader);
     let mut writer = JsonLineWriter::new(writer);
-    let mut rx = handle.subscribe();
+
+    // Atomically subscribe and snapshot buffered notifications so that
+    // warnings emitted before this client connected are replayed
+    // exactly once — they appear in the snapshot, and any notification
+    // arriving afterwards reaches us through `rx`.
+    let (notification_snapshot, mut rx) = handle.notifier.subscribe_with_snapshot();
+    for notification in notification_snapshot {
+        if writer
+            .write(&Event::Notification(notification))
+            .await
+            .is_err()
+        {
+            return;
+        }
+    }
 
     loop {
         tokio::select! {

crates/protocol/src/lib.rs

@@ -68,6 +68,38 @@ pub enum Event {
         items: Vec<serde_json::Value>,
         greeting: Greeting,
     },
+    Notification(Notification),
+}
+
+/// User-facing notification emitted from the Pod layer.
+///
+/// This is a separate channel from `tracing` (developer logs): entries
+/// here are assembled explicitly by the Pod when a condition should be
+/// surfaced to the person driving the client. Keep messages short and
+/// human-readable.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Notification {
+    pub level: NotificationLevel,
+    pub source: NotificationSource,
+    pub message: String,
+    /// Milliseconds since the Unix epoch.
+    pub timestamp_ms: i64,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum NotificationLevel {
+    Warn,
+    Error,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum NotificationSource {
+    Pod,
+    Worker,
+    Compactor,
+    AgentsMd,
 }
 
 /// Pod self-description rendered by the TUI when a session starts empty.
@@ -187,6 +219,23 @@ mod tests {
         assert_eq!(parsed["data"]["greeting"]["tools"][0], "Read");
     }
 
+    #[test]
+    fn event_notification_format() {
+        let event = Event::Notification(Notification {
+            level: NotificationLevel::Warn,
+            source: NotificationSource::Compactor,
+            message: "compaction failed".into(),
+            timestamp_ms: 1_700_000_000_000,
+        });
+        let json = serde_json::to_string(&event).unwrap();
+        let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+        assert_eq!(parsed["event"], "notification");
+        assert_eq!(parsed["data"]["level"], "warn");
+        assert_eq!(parsed["data"]["source"], "compactor");
+        assert_eq!(parsed["data"]["message"], "compaction failed");
+        assert_eq!(parsed["data"]["timestamp_ms"], 1_700_000_000_000i64);
+    }
+
     #[test]
     fn event_error_format() {
         let event = Event::Error {

crates/tui/src/app.rs

@@ -1,4 +1,4 @@
-use protocol::{Event, Greeting, Method};
+use protocol::{Event, Greeting, Method, NotificationLevel, NotificationSource};
 
 pub struct App {
     pub pod_name: String,
@@ -35,6 +35,10 @@ pub enum MessageKind {
     Tool,
     Error,
     TurnStats,
+    /// Pod → user notification, Warn level.
+    NoticeWarn,
+    /// Pod → user notification, Error level.
+    NoticeError,
 }
 
 impl App {
@@ -166,6 +170,21 @@ impl App {
                 self.current_tool = None;
             }
             Event::ToolCallArgsDelta { .. } => {}
+            Event::Notification(notification) => {
+                let kind = match notification.level {
+                    NotificationLevel::Warn => MessageKind::NoticeWarn,
+                    NotificationLevel::Error => MessageKind::NoticeError,
+                };
+                let prefix = match notification.level {
+                    NotificationLevel::Warn => "[notice]",
+                    NotificationLevel::Error => "[notice error]",
+                };
+                let source = notification_source_label(notification.source);
+                self.output_queue.push(OutputItem::Padded(
+                    kind,
+                    format!("{prefix} {source}: {}", notification.message),
+                ));
+            }
             Event::History { items, greeting } => {
                 self.restore_history(&items);
                 if self.turn_index == 0 {
@@ -298,6 +317,15 @@ impl App {
     }
 }
 
+fn notification_source_label(source: NotificationSource) -> &'static str {
+    match source {
+        NotificationSource::Pod => "pod",
+        NotificationSource::Worker => "worker",
+        NotificationSource::Compactor => "compactor",
+        NotificationSource::AgentsMd => "AGENTS.md",
+    }
+}
+
 pub fn fmt_tokens(n: u64) -> String {
     if n >= 1_000_000 {
         format!("{:.1}M", n as f64 / 1_000_000.0)

crates/tui/src/ui.rs

@@ -232,6 +232,14 @@ pub fn kind_style(kind: &MessageKind) -> Style {
         MessageKind::Tool => Style::default().fg(Color::Cyan),
         MessageKind::Error => Style::default().fg(Color::Red),
         MessageKind::TurnStats => Style::default().fg(Color::DarkGray),
+        MessageKind::NoticeWarn => Style::default()
+            .fg(Color::Black)
+            .bg(Color::Yellow)
+            .add_modifier(Modifier::BOLD),
+        MessageKind::NoticeError => Style::default()
+            .fg(Color::White)
+            .bg(Color::Red)
+            .add_modifier(Modifier::BOLD),
     }
 }
 

tickets/pod-factory.md

@@ -0,0 +1,140 @@
+# Pod Factory: 設定カスケードとプロンプト資産による Pod 自動生成
+
+## 背景
+
+現状、Pod を起動するには `test_pod.local.toml` のような完全な `PodManifest` TOML を手書きする必要がある。1 人のユーザーが1 つのエージェントを試験運用するには十分だが、Insomnia が狙う「複数のエージェントが独立プロセスとして spawn されて自律的に動く」世界観では、**Pod のライフサイクル全体が自動化可能でなければならない**。そのためには、Pod の**作成自体**も自動化可能である必要がある。
+
+手書きマニフェストには以下の問題がある:
+
+- 1 Pod = 1 ファイルで、Pod を動的に増やす用途にスケールしない
+- 設定項目が多く（`worker.*` / `provider.*` / `scope.*` / `compaction.*` / `tool_output.*` 等）、毎回コピペしてわずかな差分だけ書き換える苦行になる
+- system_prompt を TOML 文字列に埋め込む形はプロンプト資産の再利用性が低い
+- Pod の起動条件の**共通部分**（プロバイダ・モデル・デフォルトツール設定など）は本来一度書けば良いのに、毎回書かされる
+
+## ゴール
+
+Pod 作成を「**最終的に `PodManifest` を1 つ構築する問題**」として定式化し、その `PodManifest` を**カスケード + 差分上書き**で組み立てる基盤を提供する。手書きが必要な TOML は「ユーザー / プロジェクト単位の**デフォルト上書き**」だけに縮退させ、個別の Pod 起動ごとに人間が TOML を触らない状態を目指す。
+
+プロンプトは手書きマニフェストに文字列を埋め込む方式をやめ、**テンプレート資産ライブラリ**として参照可能にする。
+
+## 方針
+
+### 同じ型で、層で上書きする
+
+- **解決後の型は現行の `manifest::PodManifest` のまま**。Pod 側の契約（`Pod::from_manifest`）は変更しない。
+- カスケードは `PodManifest` より上の「部分的な `PodManifest` を層ごとに保持し、順番にマージして最終形を作る」層として設計する。
+- 各層は**部分形**を持てる（全フィールドを埋める必要はない）。存在するフィールドだけが下層を上書きする。
+
+### カスケードの層
+
+優先順位が低い方から高い方へ:
+
+1. **ビルトインのデフォルト**: コードに焼き込んだ基本値（現在 `PodManifest` 各フィールドの `#[serde(default)]` や `Default` 実装に散っているものを集約）
+2. **ユーザー設定**: `~/.config/insomnia/config.toml` など。ユーザー個人のプロバイダ指定・デフォルトモデル・常用ツール設定等を書く
+3. **プロジェクト設定**: プロジェクト直下の `.insomnia/config.toml` など。プロジェクト固有の scope・compaction 設定・system_prompt のベース等を書く
+4. **プログラマティック上書き**: Pod 生成を呼ぶコード（GUI / CLI / 別 Pod からの spawn 等）が渡す `PodManifestOverlay` 的な部分形。ここで `pod.name` や `pod.pwd` のような**その Pod に固有の値**を与える
+
+各層とも人間が書くときは `PodManifest` と同じ TOML スキーマで書く（サブセット可）。
+
+### マージのセマンティクス
+
+- **スカラー** (`String`, `u32`, `bool` 等): 上層が存在すれば丸ごと置換
+- **Option 型**: 上層が `Some` なら置換、`None` なら据え置き
+- **マップ** (例: `tool_output.per_tool`): キー単位でマージ、同一キーは上層優先
+- **リスト** (例: `scope.allow` / `scope.deny`): **原則置換**（append にすると下層の意図しないルールが漏れる危険）。ただし append したいケースはあるので、設計時に decoration の形式（例: `scope.allow_extra` など）を別途検討
+- 未知フィールドは manifest エラーにせずログ警告
+
+### プロンプト資産ライブラリ
+
+- プロンプトは TOML 文字列ではなく**ファイルとして管理**する。
+- 検索パスはカスケードと対応した3層:
+  1. **ビルトイン**: バイナリに同梱されたデフォルトプロンプト（`coder` / `reviewer` / `planner` 等、設計時に選定）
+  2. **ユーザー**: `~/.config/insomnia/prompts/*.md` 等
+  3. **プロジェクト**: `.insomnia/prompts/*.md` 等
+- 同名があれば**上層が優先**。
+- 既存の `SystemPromptTemplate`（minijinja ベース）のローダを拡張し、テンプレート内から他のプロンプトを `{% include "coder" %}` / `{% import "planner" as p %}` のように参照できるようにする。
+- 層の異なる同名プロンプトを合成するための include 先解決は上記優先順位に従う。
+
+### 設定値のテンプレート参照は扱わない
+
+`worker.max_tokens = "{{ env.INSOMNIA_MAX_TOKENS }}"` のような**設定値の中でテンプレートを展開する機能は本チケットの範囲外**とする。テンプレートエンジンはプロンプト本文の組み立てだけに限定する。設定値の動的化が必要になった時点で別チケットで検討する。
+
+### プログラマティック Pod 作成 API
+
+- `Pod::from_manifest(path)` の隣に、カスケード解決を経由する生成経路を追加する。イメージ:
+
+  ```rust
+  // 層を明示的に指定して最終形を得る
+  let manifest = PodFactory::new()
+      .with_user_config(user_config_path)?     // absent OK
+      .with_project_config(project_root)?      // absent OK
+      .with_overlay(overlay_toml_or_struct)    // programmatic
+      .resolve()?;                             // -> PodManifest
+  Pod::from_manifest(manifest, store).await?;
+  ```
+
+- 細かい形状は設計時に詰める（builder 型 vs 関数型、`overlay` を TOML 文字列か型付きか等）。
+- CLI からは `insomnia spawn --overlay '...'` 相当で同じ経路を叩く想定。
+
+## 要件
+
+### カスケード基盤
+
+- ユーザー設定・プロジェクト設定・プログラマティック overlay を順に重ねた結果が `PodManifest` として取れる。
+- 各層が部分形を許容する（`pod.pwd` だけ書いてあっても良い等）。
+- マージセマンティクスが**フィールドごとに定義**され、テストされる（スカラー / Option / マップ / リスト）。
+- 層が全て空でも**ビルトインデフォルト単体で有効な manifest にならない**（少なくとも `pod.pwd` と `provider` と `scope.allow` は上位層で与える必要がある）。その旨を resolve 時のエラーで明示する。
+
+### プロンプト資産ライブラリ
+
+- 3層の検索パスでプロンプトファイルを解決できる。
+- 同名プロンプトは上層優先で解決される。
+- `SystemPromptTemplate` の minijinja `Environment` にカスタムローダを仕込み、`{% include "name" %}` / `{% import "name" as x %}` で資産を参照できる。
+- プロンプト資産自体もテンプレートとして評価され、現行の `SystemPromptContext`（`now` / `cwd` / `scope` / `tools` / `files` 等）と同じ変数が見える。
+
+### プログラマティック Pod 作成
+
+- 既存の `Pod::from_manifest` を壊さず、追加経路として `PodFactory` 系の API を提供する。
+- TUI / GUI / daemon 等の上位クライアントが、TOML ファイルパスではなく**オーバーレイ + 設定ディレクトリパス**を渡すだけで Pod を起動できる。
+
+### ドキュメント
+
+- カスケード層の優先順位・マージ規則を `docs/` にまとめる。
+- ユーザー設定 / プロジェクト設定ファイルの**最小例**と**全オプション例**を残す。
+
+## 設計で決めること
+
+- **ユーザー設定のパス**: `~/.config/insomnia/config.toml` か、XDG 非準拠のパスも許容するか。環境変数で上書きできるか。
+- **プロジェクト設定の場所**: プロジェクトルートの `.insomnia/config.toml` か、別の命名か。サブディレクトリから起動したときの discovery（上位ディレクトリ探索）の挙動。
+- **プロジェクトルートの判定**: 明示指定 vs `.git` や `.insomnia/` で自動検出
+- **preset の概念を入れるか**: 名前付きの overlay セット（例: `insomnia spawn coder`）を導入するか。導入する場合、preset はユーザー設定内に `[preset.coder]` として持つか、個別ファイル `~/.config/insomnia/presets/coder.toml` として持つか
+- **リストフィールドのマージ方針**: 置換 only にするか、append 用の別フィールド (`scope.allow_extra` 等) を用意するか
+- **ビルトインプロンプトの初期ラインナップ**: どの役割をデフォルトで同梱するか、どこに置くか（`crates/pod/assets/prompts/*.md` を `include_str!` で埋め込む等）
+- **プロンプト資産のファイル形式**: `.md` か `.txt` か、拡張子省略可能にするか、フロントマター（YAML/TOML）で引数デフォルトを持たせるか
+- **プロンプト include 時の context 伝搬**: 親テンプレートの変数を include 先でも見えるようにするか、明示的に `with` で渡させるか
+- **エラー戦略**: 上層で書かれた未知フィールドや型ミスマッチをどこまで寛容に扱うか
+- **既存の `Pod::from_manifest(path)` とのインターフェース整理**: 廃止するか、内部的に PodFactory に委譲するか
+- **CLI コマンド名**: `insomnia spawn` / `insomnia pod new` / その他
+
+## 完了条件
+
+- `PodManifest` の最終形を層のマージで構築する `PodFactory`（または同等の仕組み）が実装され、マージセマンティクスの単体テストが通る。
+- ユーザー設定・プロジェクト設定・プログラマティック overlay のすべての層を使う end-to-end テストで、Pod が TOML ファイルパスを一切渡さずに起動できる。
+- プロンプト資産ライブラリを経由して system_prompt が組み立てられ、`{% include "ビルトイン名" %}` で同梱プロンプトを参照できることをテストで確認できる。
+- ユーザー設定ファイル / プロジェクト設定ファイルのドキュメントが `docs/` に存在する。
+- 既存の `Pod::from_manifest(path)` 経路が動き続ける（回帰させない）。
+
+## 他チケットとの関係
+
+- `tickets/native-gui-mvp.md`: 現状「manifest ファイルを選ぶ UI」を含むが、本チケット完了後はその UI が「preset 選択 + overlay 入力」に置き換わる想定。native-gui-mvp 実装時に本チケットの API を使うか、先に文字列パス渡しで済ませて後から差し替えるかは別途判断
+- `tickets/tui-pod-spawn-ui.md`: 同上。Pod spawn UI は本チケットが提供する API の上に構築される
+- `tickets/protocol-design.md`: Pod ↔ Client protocol 自体は変わらない。spawn 要求を protocol に載せるかどうかは protocol-design 側で検討
+- `docs/system-prompt-template.md` / `crates/pod/src/system_prompt.rs`: プロンプト資産ライブラリはこの minijinja 基盤の拡張として実装される
+
+## 範囲外
+
+- **設定値の中のテンプレート展開**（`max_tokens = "{{ env.X }}"` のような動的値）。プロンプト本文のテンプレート展開のみを扱う
+- **GUI 内での設定ファイル編集 UI**。編集は人間がエディタで TOML を書くだけ（あくまで「Pod 生成時に手書きしない」ことを目指す）
+- **チーム共有・同期**。ユーザー設定とプロジェクト設定は各自・各リポジトリ単位で管理される
+- **秘密情報管理**（API キー等）。既存の `api_key_file` 方式を維持する
+- **設定値の型バリデーション強化**（JSON Schema など）。現行の serde ベースで十分な範囲に留める

tickets/tui-notification-channel.md

@@ -1,5 +1,10 @@
 # TUI 通知チャネル: Warn/Error をユーザーに可視化
 
+## レビュー状態
+
+初回レビュー実施済み。[tui-notification-channel.review.md](tui-notification-channel.review.md) を参照。
+コア要件は達成。残る指摘は (1) `Notifier::buffer` の無制限成長、(2) TUI 側の表示強度（履歴行に紛れるか別立てで見落とさない位置に出すか）の 2 点で、いずれも user 判断待ち。
+
 ## 背景
 
 Pod/Worker 層は現在、通知すべき事象（compaction 失敗、AGENTS.md 読み取り失敗、ツール出力の切り詰め、将来追加される様々な前処理エラー等）をすべて `tracing::warn!` で出している。TUI はこのログを受け取る仕組みを持たないため、**ユーザーは何も気づかないまま Pod が縮退動作している状態**になりうる。

tickets/tui-notification-channel.review.md

@@ -0,0 +1,107 @@
+# レビュー: TUI 通知チャネル
+
+対象差分: `crates/pod/src/{notifier,pod,controller,agents_md,lib,socket_server}.rs`, `crates/llm-worker/src/worker.rs`, `crates/protocol/src/lib.rs`, `crates/tui/src/{app,ui}.rs`（いずれも未コミット）
+
+## 要件達成状況
+
+| 要件 | 状態 |
+|---|---|
+| Pod 層が型付き通知を発行する API を持つ | ✅ `Notifier::notify(level, source, message)`、`PodHandle::notify` / `Pod::notify` ラッパ |
+| `tracing` とは別系統 | ✅ 既存 `tracing::warn!` は並存、通知は `Notifier` 経由のみ |
+| 構造化型（level / source / message / timestamp） | ✅ `protocol::Notification` に全4項目。timestamp は unix ms の i64 |
+| レベルは Warn / Error（Info は設計判断） | ✅ Info は除外（設計判断として妥当） |
+| 発生源の列挙（Pod / Worker / Compactor / Tool 境界等） | ✅ `NotificationSource::{Pod, Worker, Compactor, AgentsMd}`。Tool 境界は Worker に集約 |
+| TUI が受信して表示する | 🟡 表示はする（`MessageKind::NoticeWarn/Error` + 色 + bold）が、**ticket が想定した「一時表示・通知ペイン」レベルには到達していない**。後述 |
+| Error と Warn の視覚的区別 | ✅ Yellow bold / Red bold + `[notice]` / `[notice error]` prefix |
+| 通知履歴が見られる | 🟡 `output_queue` → scrollback に残るのみ。専用ペインでの閲覧は無い |
+| 新着通知の一時表示 | 🟡 普通のメッセージ行として積まれるだけ、トースト / ステータスバー常駐は無し |
+| 複数通知の重ね合わせ | 🟡 単純 append、特段の配慮は無し |
+| 既存 `tracing::warn!` の置換（compaction 失敗） | ✅ `pod.rs` の mid-run / post-run 両経路で notify。並行して tracing も残る |
+| 既存 `tracing::warn!` の置換（ツール出力切り詰め） | ✅ `worker.rs` が `on_warning` コールバック経由で Controller → Notifier に流す |
+| 既存 `tracing::warn!` の置換（AGENTS.md） | ✅ `read_agents_md` が `AgentsMdResult { body, warnings }` を返し、`pod.rs` で notify |
+
+**コア要件は達成**。「TUI の表示方法」は設計議論を含む項目で、ticket の "設計で決めること" に「トースト / ステータスバー / 通知ペイン / その組合せ」と列挙されていた部分を、実装者は**「履歴内の区別された行」に絞った**と読める。これは最小実装としては筋が通るが、ticket 本文の「見落としにくい位置に一時的に表示」という表現とは**乖離**があり、判断を user に返すべき。
+
+## アーキテクチャ統合
+
+### 良い点
+
+- **`Notifier` の race-free 購読**: `subscribe_with_snapshot` が `buffer` の mutex を保持したまま `event_tx.subscribe()` を呼び、snapshot をクローンしてから返すことで、「通知が snapshot と live の両方に現れる」「どちらからも漏れる」の両方を同時に防いでいる。`notifier.rs` のテスト `subscribe_snapshot_and_live_do_not_overlap` で設計意図を lock-in している。late subscriber 対応は本チケットの肝であり、最もよく出来ている部分。
+- **層の分離**: Worker は `on_warning(Box<dyn Fn(&str) + Send + Sync>)` というタイプ消去されたコールバックを受ける形にし、`protocol::Notification*` 型に依存していない。Controller 側で closure に notifier をキャプチャして橋渡しする。Worker が protocol に依存せずに済んでおり、llm-worker は低レベル基盤のままという方針（memory）とも整合。
+- **`read_agents_md` の pure 分離**: 以前は `Option<String>` + 直接 `tracing::warn!` だったが、`AgentsMdResult { body, warnings }` を返す形に変更され、呼び出し側が副作用（notify）を担当する。pure function + 副作用集約の分離として綺麗。
+- **既存 broadcast channel への相乗り**: `Event::Notification(Notification)` という新バリアントとして既存の `broadcast::Sender<Event>` に載せたことで、新しい通信経路を作らずに済んでいる。`socket_server` 側の配線変更も `subscribe_with_snapshot` の snapshot を prelude として書き出し、以降は既存 loop に合流する、という自然な形。
+- **`Pod::attach_notifier` パターン**: Controller が Pod の construction 後に notifier を差し込む（`Pod::new` 自体は notifier を持たない）ため、Pod 直接 new の tests でも Notifier が不要。`None` のときは `Pod::notify` が no-op になる。
+
+### 懸念 1: 🟡 `Notifier::buffer` が無制限に伸びる
+
+```rust
+struct Inner {
+    event_tx: broadcast::Sender<Event>,
+    buffer: Mutex<Vec<Notification>>,
+}
+```
+
+セッションが長寿命かつ通知が頻発するケース（compaction 失敗がループするとか、ツール出力切り詰めが毎ターン起きるとか）で、`buffer` は単調増加する。新規クライアントが接続した瞬間に `subscribe_with_snapshot` が全部クローンするので、**1 接続あたりのメモリ消費と初期送信コストも比例して増える**。
+
+ticket には明示的な上限要件は無いが、実運用での**メモリ健全性**として上限を設けるべき。たとえば:
+
+- 上限件数 (例: 256 件) でリング化（最古から落とす）
+- 時間窓（直近 N 分）
+- 落とした件数だけ "[N older notifications elided]" の synthetic notification を先頭に置く
+
+**判断**: 要検討。後続チケットとして切るか、本チケットの範囲で追補するか。
+
+### 懸念 2: 🟡 TUI 側の表示が ticket 要件の minimum interpretation
+
+ticket 要件:
+> - 新着通知はユーザーが見落としにくい位置に**一時的**に表示される（トースト / ステータスバー等）
+> - 履歴が見られる（キーバインドで通知ペインを開ける等）
+
+実装:
+- `MessageKind::NoticeWarn/Error` として通常のメッセージ行と同じ `output_queue` に積む
+- Yellow/Red の bold + `[notice]` prefix で視覚的に区別
+- トースト・ステータスバー常駐・通知ペインは無し
+
+ユーザーが会話に集中していてスクロールが別位置にあった場合、新着通知は画面外に流れて気付けない可能性が高い。
+
+一方、ticket の "設計で決めること" には 4 択が並んでおり、実装者が minimum viable として「履歴に色付きで積む」を選んだという解釈もできる。
+
+**判断**: user が「これで良い」と言えば OK。「やはり見落とす」となれば別タスクとして追加実装（status 行 1 段拡張でラスト通知を pin する、など）が必要。
+
+### 懸念 3: 🟢 `NotificationSource` に Pod 名が入らない
+
+現状 `NotificationSource` はカテゴリだけ持ち、Pod 名や具体的な tool 名は `message` 本文に埋め込む設計。単一 Pod 前提ではこれで十分。将来 `tickets/native-gui-mvp.md` で GUI が複数 Pod を spawn するようになると「どの Pod の通知か」がメッセージパースでしか分からなくなる。
+
+**判断**: 不問。複数 Pod 対応のチケット（将来）で `Notification` に Pod 名フィールドを追加するのが自然。現時点で先回りする必要は無い。
+
+### 懸念 4: 🟢 `PodHandle::subscribe` の用途
+
+以前は `handle.subscribe()` を直接呼んで broadcast::Receiver を得ていたところが、今は `handle.notifier.subscribe_with_snapshot()` 経由になった。`PodHandle::subscribe` 自体はまだ存在しており、socket_server 以外に呼び出し元があるかは未確認。無ければ将来削除可能。
+
+**判断**: 不問。クリーンアップは別途。
+
+## 完了条件照合
+
+- [x] Pod 層が型付き通知を発行する API を持つ
+- [x] TUI がその通知を受信して表示する
+- [~] 履歴保存 — 一応 scrollback / `Notifier::buffer` には残るが、ticket 本文の「セッション単位で履歴を見られる」は minimal な達成
+- [~] 手動テストで TUI 画面上に現れることの確認 — コードレベルでは通るが、実機確認の記述は無い（これは受け入れテストの話）
+
+## テスト
+
+- `notifier.rs` の 3 ケース（broadcast / late subscriber snapshot / snapshot-live non-overlap）は設計要点を的確にカバー
+- `protocol/lib.rs` で `event_notification_format` が JSON 表現を lock-in
+- `agents_md.rs` のテストは `AgentsMdResult` 変更に追従し、`non_utf8_surfaces_warning` が新規に追加されて warning 経路をカバー
+- Controller / Pod / socket_server レベルの integration test は無し。`Notifier` の単体テストで十分と割り切った判断と見える
+
+## 結論
+
+**コア要件は達成、アーキテクチャは筋が良い**。特に race-free subscribe と層の分離は見事。
+
+残る指摘:
+
+1. 🟡 **buffer 無制限**: 実運用でメモリ単調増加の可能性。上限の検討要
+2. 🟡 **TUI 表示の強度**: ticket 文面からは「通知は見落とされないべき」と読めるが、実装は履歴行に紛れる最小形。user 判断待ち
+3. 🟢 **Pod 名フィールド** / 🟢 **`PodHandle::subscribe` の残存**: 不問
+
+**受け入れ可否**: 指摘1・2について user 判断。採否次第で「このまま受け入れ」「buffer 上限だけ追補」「TUI 表示も強化」の 3 パスに分岐する。