feat(suppress): group-suppress warnings + ls + journey + docs (M1.5)

- dangling_suppress_warnings takes an ApplyOwner and walks the group's own
  chain (GROUP_CHAIN_LEVELS_CTE) for a group node; runs for both owners.
- GET /groups/{id}/suppressions + `pic suppress ls --group` (client + cmd +
  main.rs; --app/--group mutually exclusive).
- suppress journey: a child group declines a parent template for its subtree;
  suppress ls --group shows the marker. Docs §4.5 + CLAUDE.md move group-level
  suppression from Deferred to implemented.

Completes M1. (An unrelated pre-existing email_inbound dispatch-timing flake
passes in isolation.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/manager-core/src/apply_api.rs

@@ -45,6 +45,7 @@ pub fn apply_router(service: ApplyService) -> Router {
         .route("/groups/{id}/triggers", get(group_triggers_handler))
         .route("/groups/{id}/routes", get(group_routes_handler))
         .route("/apps/{id}/suppressions", get(app_suppressions_handler))
+        .route("/groups/{id}/suppressions", get(group_suppressions_handler))
         .with_state(service)
 }
 
@@ -64,6 +65,26 @@ async fn app_suppressions_handler(
     Ok(Json(report))
 }
 
+/// Read-only §11 tail M1 suppression report for a group: the inherited templates
+/// it declines for its whole subtree (`target_kind`, `reference`). Viewer-tier
+/// `GroupScriptsRead`. Backs `pic suppress ls --group`.
+async fn group_suppressions_handler(
+    State(svc): State<ApplyService>,
+    Extension(principal): Extension<Principal>,
+    Path(id_or_slug): Path<String>,
+) -> Result<Json<Vec<SuppressionInfo>>, ApplyError> {
+    let group_id = resolve_group_id(svc.groups.as_ref(), &id_or_slug).await?;
+    require(
+        svc.authz.as_ref(),
+        &principal,
+        Capability::GroupScriptsRead(group_id),
+    )
+    .await
+    .map_err(map_authz)?;
+    let report = svc.suppression_report(ApplyOwner::Group(group_id)).await?;
+    Ok(Json(report))
+}
+
 /// Read-only §11 tail route-template report for a group: its own declared route
 /// templates (method, host, path, handler script, dispatch, enabled). Viewer-
 /// tier read. Backs `pic routes ls --group`.

crates/manager-core/src/apply_service.rs

@@ -1293,16 +1293,17 @@ impl ApplyService {
         // A group endpoint is reached by *inheritance* (a descendant app binds
         // it by name), never by its own route, so the "no route/trigger"
         // warning is noise for every group script — emit it for apps only.
-        if let ApplyOwner::App(app_id) = owner {
+        if let ApplyOwner::App(_) = owner {
             report
                 .warnings
                 .extend(unreachable_endpoint_warnings(bundle));
-            // §11 tail: a suppress reference that matches no inherited template
-            // silently does nothing — warn (typo guard), don't fail.
-            report
-                .warnings
-                .extend(self.dangling_suppress_warnings(app_id, bundle).await?);
         }
+        // §11 tail: a suppress reference that matches no inherited template (or
+        // only sealed ones) silently does nothing — warn (typo guard), don't
+        // fail. M1: runs for a group node too (it walks the group's own chain).
+        report
+            .warnings
+            .extend(self.dangling_suppress_warnings(owner, bundle).await?);
 
         self.reconcile_node_tx(
             &mut tx,
@@ -2151,39 +2152,52 @@ impl ApplyService {
     /// refs match an ancestor-group route's path.
     async fn dangling_suppress_warnings(
         &self,
-        app_id: AppId,
+        owner: ApplyOwner,
         bundle: &Bundle,
     ) -> Result<Vec<String>, ApplyError> {
         if bundle.suppress_triggers.is_empty() && bundle.suppress_routes.is_empty() {
             return Ok(Vec::new());
         }
-        // Inherited (ancestor-group) trigger handler names + route paths, each
+        // §11 tail M1: the set of templates a suppression can decline lives on
-        // tagged with whether ANY matching template is un-sealed (i.e. actually
+        // the OWNER's chain — an app walks its ancestor groups (`CHAIN_LEVELS_CTE`
-        // suppressible). `bool_or(NOT sealed)` = true iff at least one match can
+        // bound to the app), a group walks itself + its ancestors
-        // be declined; false = every match is `sealed` (§11 tail), so the
+        // (`GROUP_CHAIN_LEVELS_CTE` bound to the group). Both CTEs expose a
-        // suppression is inert; absent = no inherited template at all (a typo).
+        // `chain` view with a `group_owner` column, so the queries below are
+        // identical modulo which CTE + bind.
+        let (chain_cte, owner_uuid) = match owner {
+            ApplyOwner::App(a) => (CHAIN_LEVELS_CTE, a.into_inner()),
+            ApplyOwner::Group(g) => (
+                crate::config_resolver::GROUP_CHAIN_LEVELS_CTE,
+                g.into_inner(),
+            ),
+        };
+        // Inherited trigger handler names + route paths, each tagged with whether
+        // ANY matching template is un-sealed (i.e. actually suppressible).
+        // `bool_or(NOT sealed)` = true iff at least one match can be declined;
+        // false = every match is `sealed` (§11 tail), so the suppression is
+        // inert; absent = no inherited template at all (a typo).
         let trig_names: Vec<(String, bool)> = sqlx::query_as(&format!(
-            "{CHAIN_LEVELS_CTE} \
+            "{chain_cte} \
              SELECT LOWER(s.name), bool_or(NOT t.sealed) FROM triggers t \
              JOIN scripts s ON s.id = t.script_id \
              JOIN chain c ON t.group_id = c.group_owner \
              WHERE t.group_id IS NOT NULL \
              GROUP BY LOWER(s.name)",
         ))
-        .bind(app_id.into_inner())
+        .bind(owner_uuid)
         .fetch_all(&self.pool)
         .await
         .map_err(|e| ApplyError::Backend(e.to_string()))?;
         let inherited_handlers: HashMap<String, bool> = trig_names.into_iter().collect();
 
         let route_paths: Vec<(String, bool)> = sqlx::query_as(&format!(
-            "{CHAIN_LEVELS_CTE} \
+            "{chain_cte} \
              SELECT r.path, bool_or(NOT r.sealed) FROM routes r \
              JOIN chain c ON r.group_id = c.group_owner \
              WHERE r.group_id IS NOT NULL \
              GROUP BY r.path",
         ))
-        .bind(app_id.into_inner())
+        .bind(owner_uuid)
         .fetch_all(&self.pool)
         .await
         .map_err(|e| ApplyError::Backend(e.to_string()))?;

crates/picloud-cli/src/client.rs

@@ -1385,6 +1385,19 @@ impl Client {
             .await?;
         decode(resp).await
     }
+
+    /// §11 tail M1: a group's own suppressions (declined for its whole subtree).
+    pub async fn group_suppressions_list(&self, group_ident: &str) -> Result<Vec<SuppressionDto>> {
+        let ident = seg(group_ident);
+        let resp = self
+            .request(
+                Method::GET,
+                &format!("/api/v1/admin/groups/{ident}/suppressions"),
+            )
+            .send()
+            .await?;
+        decode(resp).await
+    }
 }
 
 /// One row of the §11 tail suppression report.

crates/picloud-cli/src/cmds/suppress.rs

@@ -1,18 +1,23 @@
-//! `pic suppress ls --app <a>` — read-only view of an app's §11 tail
+//! `pic suppress ls --app <a>` / `--group <g>` — read-only view of an owner's
-//! per-app opt-outs: the inherited group templates it declines. App-only;
+//! §11 tail opt-outs: the inherited group templates it declines. An app declines
-//! authoring is declarative via the `[suppress]` block (`triggers = [...]`
+//! for itself; a group declines for its whole subtree (§11 tail M1). Authoring
-//! handler script names, `routes = [...]` paths).
+//! is declarative via the `[suppress]` block (`triggers = [...]` handler script
+//! names, `routes = [...]` paths).
 
-use anyhow::Result;
+use anyhow::{bail, Result};
 
 use crate::client::Client;
 use crate::config;
 use crate::output::{OutputMode, Table};
 
-pub async fn ls(app: &str, mode: OutputMode) -> Result<()> {
+pub async fn ls(app: Option<&str>, group: Option<&str>, mode: OutputMode) -> Result<()> {
     let creds = config::resolve()?;
     let client = Client::from_creds(&creds)?;
-    let items = client.suppressions_list(app).await?;
+    let items = match (app, group) {
+        (Some(a), None) => client.suppressions_list(a).await?,
+        (None, Some(g)) => client.group_suppressions_list(g).await?,
+        _ => bail!("provide exactly one of --app or --group"),
+    };
 
     let mut table = Table::new(["kind", "reference"]);
     for s in &items {

crates/picloud-cli/src/main.rs

@@ -587,10 +587,14 @@ enum CollectionsCmd {
 
 #[derive(Subcommand)]
 enum SuppressCmd {
-    /// List the inherited templates an app declines (§11 tail). App-only.
+    /// List the inherited templates an owner declines (§11 tail). Exactly one
+    /// of `--app` (declines for itself) or `--group` (declines for its whole
+    /// subtree, §11 tail M1).
     Ls {
+        #[arg(long, conflicts_with = "group")]
+        app: Option<String>,
         #[arg(long)]
-        app: String,
+        group: Option<String>,
     },
 }
 
@@ -2042,8 +2046,8 @@ async fn main() -> ExitCode {
             cmd: CollectionsCmd::Ls { group },
         } => cmds::collections::ls(&group, mode).await,
         Cmd::Suppress {
-            cmd: SuppressCmd::Ls { app },
+            cmd: SuppressCmd::Ls { app, group },
-        } => cmds::suppress::ls(&app, mode).await,
+        } => cmds::suppress::ls(app.as_deref(), group.as_deref(), mode).await,
         Cmd::Files {
             cmd:
                 FilesCmd::Ls {

crates/picloud-cli/tests/suppress.rs

@@ -201,3 +201,100 @@ fn app_suppresses_inherited_route_template() {
         "pruning the suppression must re-inherit the route"
     );
 }
+
+/// §11 tail M1: a CHILD group declares `[suppress]` for a template it inherits
+/// from its PARENT → every app in the child's subtree declines it; a `pic
+/// suppress ls --group` shows the marker.
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn group_suppresses_inherited_route_template_for_subtree() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let parent = common::unique_slug("gsup-p");
+    let child = common::unique_slug("gsup-c");
+
+    let _gp = GroupGuard::new(&env.url, &env.token, &parent);
+    let _gc = GroupGuard::new(&env.url, &env.token, &child);
+    common::pic_as(&env)
+        .args(["groups", "create", &parent])
+        .assert()
+        .success();
+    common::pic_as(&env)
+        .args(["groups", "create", &child, "--parent", &parent])
+        .assert()
+        .success();
+
+    // Parent handler + a route template binding it.
+    let dir = manifest_dir();
+    fs::write(
+        dir.path().join("scripts/phello.rhai"),
+        r#"log::info("parent route"); "ok""#,
+    )
+    .unwrap();
+    common::pic_as(&env)
+        .args(["scripts", "deploy"])
+        .arg(dir.path().join("scripts/phello.rhai"))
+        .args(["--group", &parent, "--name", "phello"])
+        .assert()
+        .success();
+    let _ps = ScriptGuard::new(
+        &env.url,
+        &env.token,
+        &group_script_id(&env, &parent, "phello"),
+    );
+    let pmanifest = format!(
+        "[group]\nslug = \"{parent}\"\nname = \"P\"\n\n\
+         [[routes]]\nscript = \"phello\"\npath = \"/phello\"\npath_kind = \"exact\"\n\
+         host_kind = \"any\"\n"
+    );
+    let ppath = dir.path().join("parent.toml");
+    fs::write(&ppath, &pmanifest).unwrap();
+    common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&ppath)
+        .assert()
+        .success();
+
+    // App under the CHILD group inherits the parent's route template.
+    let app = common::unique_slug("gsup-app");
+    let _a = AppGuard::new(&env.url, &env.token, &app);
+    common::pic_as(&env)
+        .args(["apps", "create", &app, "--group", &child])
+        .assert()
+        .success();
+    assert!(route_matches(&env, &app, "http://localhost/phello"));
+
+    // The CHILD group applies a [suppress] declining /phello → the whole child
+    // subtree stops serving it.
+    let cmanifest = format!(
+        "[group]\nslug = \"{child}\"\nname = \"C\"\n\n\
+         [suppress]\nroutes = [\"/phello\"]\n"
+    );
+    let cpath = dir.path().join("child.toml");
+    fs::write(&cpath, &cmanifest).unwrap();
+    common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&cpath)
+        .assert()
+        .success();
+    assert!(
+        !route_matches(&env, &app, "http://localhost/phello"),
+        "an app under the suppressing group must stop serving the inherited route"
+    );
+
+    // `pic suppress ls --group` shows the child's marker.
+    let ls = String::from_utf8(
+        common::pic_as(&env)
+            .args(["suppress", "ls", "--group", &child])
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(
+        ls.contains("route") && ls.contains("/phello"),
+        "suppress ls --group should list the route suppression:\n{ls}"
+    );
+}

docs/design/groups-and-project-tool.md

@@ -457,7 +457,18 @@ Two distinct constraints:
 > row, like any definitional change). A suppression that matches only sealed templates is an apply-time
 > **warning** ("… is sealed — the suppression has no effect"); `pic triggers/routes ls --group` show a
 > `sealed` column. Pinned by `manager-core/tests/sealed_templates.rs` + the `sealed` journey.
-> **Deferred:** group-level suppression (decline an ancestor's template for a whole subtree).
+>
+> **Group-level suppression (✅, M1).** `template_suppressions` gained a polymorphic owner
+> (`0060_group_suppressions.sql`, mirroring the triggers/routes reshape): a `[group]` may now declare
+> `[suppress]` to decline a template it inherits from a **higher ancestor**, for its **whole subtree**.
+> The two consumption filters generalized to the chain: the trigger anti-join joins the `chain` CTE
+> (`ts.app_id = sc.app_owner OR ts.group_id = sc.group_owner`) so a suppression owned by the firing app OR
+> any ancestor group applies; `list_route_suppressions` expands group-owned suppressions across
+> descendants via the all-apps `app_chain` CTE, so `compile_effective_routes` is unchanged. Still
+> inheritance-only (`t.group_id IS NOT NULL` / `depth > 0`) and `sealed` still overrides. Read-only
+> `pic suppress ls --group`; the dangling/ineffective warning walks the group's own chain
+> (`GROUP_CHAIN_LEVELS_CTE`). Pinned by `manager-core/tests/group_suppression.rs` + the `suppress`
+> journey. **Deferred:** none for suppression.
 
 ### 4.6 Secrets & `pull`