feat(agents): add manifest-driven gator agent

architecture/sandbox.md

@@ -72,7 +72,9 @@ relay settings.
 
 Credential placeholders in proxied HTTP requests can be resolved by the proxy
 when policy allows the target endpoint. Secrets must not be logged in OCSF or
-plain tracing output.
+plain tracing output. The supervisor uses revision-scoped placeholders for
+rotating provider credentials; provider environment keys beginning with
+`v<digits>_` are reserved for that placeholder namespace.
 
 ## Connect and Logs
 

crates/openshell-ocsf/src/format/shorthand.rs

@@ -154,12 +154,13 @@ impl OcsfEvent {
                     (false, true) => format!(" {action}"),
                     (false, false) => format!(" {action}{arrow}"),
                 };
-                let message_ctx =
-                    if detail.is_empty() && rule_ctx.is_empty() && reason_ctx.is_empty() {
-                        message_tag(&e.base)
-                    } else {
-                        String::new()
-                    };
+                let include_message = activity == "FAIL"
+                    || (detail.is_empty() && rule_ctx.is_empty() && reason_ctx.is_empty());
+                let message_ctx = if include_message {
+                    message_tag(&e.base)
+                } else {
+                    String::new()
+                };
                 format!("NET:{activity} {sev}{detail}{rule_ctx}{reason_ctx}{message_ctx}")
             }
 
@@ -580,6 +581,34 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_network_activity_shorthand_fail_shows_message_with_destination() {
+        let event = OcsfEvent::NetworkActivity(NetworkActivityEvent {
+            base: {
+                let mut b = base(4001, "Network Activity", 4, "Network Activity", 6, "Fail");
+                b.severity = crate::enums::SeverityId::Low;
+                b.set_message("TLS relay error: unexpected eof");
+                b
+            },
+            src_endpoint: None,
+            dst_endpoint: Some(Endpoint::from_domain("api.github.com", 443)),
+            proxy_endpoint: None,
+            actor: None,
+            firewall_rule: None,
+            connection_info: None,
+            action: None,
+            disposition: None,
+            observation_point_id: None,
+            is_src_dst_assignment_known: None,
+        });
+
+        let shorthand = event.format_shorthand();
+        assert_eq!(
+            shorthand,
+            "NET:FAIL [LOW] api.github.com:443 [msg:TLS relay error: unexpected eof]"
+        );
+    }
+
     #[test]
     fn test_network_activity_shorthand_shows_message_when_no_key_fields() {
         let event = OcsfEvent::NetworkActivity(NetworkActivityEvent {

crates/openshell-providers/src/profiles.rs

@@ -980,6 +980,15 @@ pub fn validate_profile_set(
                         "credentials.env_vars",
                         "credential env var must not be empty",
                     ));
+                } else if uses_reserved_placeholder_revision_namespace(env_var.trim()) {
+                    diagnostics.push(ProfileValidationDiagnostic::error(
+                        source,
+                        profile_id,
+                        "credentials.env_vars",
+                        format!(
+                            "credential env var '{env_var}' uses reserved OpenShell placeholder revision namespace"
+                        ),
+                    ));
                 } else if !env_vars.insert(env_var.trim().to_string()) {
                     diagnostics.push(ProfileValidationDiagnostic::error(
                         source,
@@ -1106,6 +1115,19 @@ fn endpoint_is_valid(endpoint: &EndpointProfile) -> bool {
     (1..=65_535).contains(&endpoint.port)
 }
 
+fn uses_reserved_placeholder_revision_namespace(key: &str) -> bool {
+    let Some(suffix) = key.strip_prefix('v') else {
+        return false;
+    };
+    let Some((revision, key)) = suffix.split_once('_') else {
+        return false;
+    };
+    !revision.is_empty()
+        && revision.bytes().all(|b| b.is_ascii_digit())
+        && !key.is_empty()
+        && key.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_')
+}
+
 static DEFAULT_PROFILES: OnceLock<Vec<ProviderTypeProfile>> = OnceLock::new();
 
 #[must_use]
@@ -1456,7 +1478,7 @@ credentials:
     env_vars: [BROKEN_TOKEN]
     auth_style: query
   - name: api_key
-    env_vars: [BROKEN_TOKEN, ""]
+    env_vars: [BROKEN_TOKEN, "", v10_GITHUB_TOKEN]
     auth_style: unknown
 discovery:
   credentials: [api_key, missing_key]
@@ -1477,6 +1499,11 @@ binaries: ["", /usr/bin/broken]
         assert!(messages.contains(&"duplicate credential name: api_key"));
         assert!(messages.contains(&"duplicate credential env var 'BROKEN_TOKEN'"));
         assert!(messages.contains(&"credential env var must not be empty"));
+        assert!(
+            messages.iter().any(
+                |message| message.contains("reserved OpenShell placeholder revision namespace")
+            )
+        );
         assert!(messages.contains(&"query_param is required for query auth"));
         assert!(messages.contains(&"unsupported auth_style: unknown"));
         assert!(messages.contains(&"unknown discovery credential: missing_key"));

crates/openshell-sandbox/src/provider_credentials.rs

@@ -226,4 +226,50 @@ mod tests {
             Some("new")
         );
     }
+
+    #[test]
+    fn stale_generation_falls_back_to_current_credential_after_retention_window() {
+        let state = ProviderCredentialState::from_environment(
+            10,
+            HashMap::from([("GITHUB_TOKEN".to_string(), "old".to_string())]),
+            HashMap::new(),
+        );
+
+        for revision in 11..20 {
+            state.install_environment(
+                revision,
+                HashMap::from([("GITHUB_TOKEN".to_string(), format!("new-{revision}"))]),
+                HashMap::new(),
+            );
+        }
+
+        let resolver = state.resolver().expect("resolver");
+        assert_eq!(
+            resolver.resolve_placeholder("openshell:resolve:env:v10_GITHUB_TOKEN"),
+            Some("new-19")
+        );
+    }
+
+    #[test]
+    fn stale_removed_generation_fails_closed_after_retention_window() {
+        let state = ProviderCredentialState::from_environment(
+            10,
+            HashMap::from([("GITHUB_TOKEN".to_string(), "old".to_string())]),
+            HashMap::new(),
+        );
+
+        for revision in 11..20 {
+            state.install_environment(
+                revision,
+                HashMap::from([("OTHER_TOKEN".to_string(), format!("other-{revision}"))]),
+                HashMap::new(),
+            );
+        }
+
+        let resolver = state.resolver().expect("retained resolver");
+        assert_eq!(
+            resolver.resolve_placeholder("openshell:resolve:env:v10_GITHUB_TOKEN"),
+            None
+        );
+    }
 }

crates/openshell-sandbox/src/secrets.rs

@@ -177,6 +177,13 @@ impl SecretResolver {
         let mut by_placeholder = HashMap::with_capacity(provider_env.len());
 
         for (key, value) in provider_env {
+            if uses_reserved_revision_namespace(&key) {
+                tracing::warn!(
+                    provider_env_key = %key,
+                    "skipping provider credential env var in reserved placeholder namespace"
+                );
+                continue;
+            }
             let placeholder = placeholder_for_env_key_for_revision(&key, revision);
             let secret = SecretValue {
                 value,
@@ -192,7 +199,11 @@ impl SecretResolver {
             }
         }
 
-        (child_env, Some(Self { by_placeholder }))
+        if by_placeholder.is_empty() {
+            (child_env, None)
+        } else {
+            (child_env, Some(Self { by_placeholder }))
+        }
     }
 
     pub(crate) fn merge<'a>(resolvers: impl IntoIterator<Item = &'a Self>) -> Option<Self> {
@@ -215,7 +226,7 @@ impl SecretResolver {
         let secret = if let Some(secret) = self.by_placeholder.get(value) {
             secret
         } else {
-            let key = alias_env_key(value)?;
+            let key = revisioned_placeholder_env_key(value).or_else(|| alias_env_key(value))?;
             let canonical = placeholder_for_env_key(key);
             self.by_placeholder.get(&canonical)?
         };
@@ -469,6 +480,34 @@ fn alias_env_key(token: &str) -> Option<&str> {
     (key_end == token.len() && key_end > key_start).then_some(&token[key_start..key_end])
 }
 
+fn revisioned_placeholder_env_key(token: &str) -> Option<&str> {
+    let suffix = token.strip_prefix(PLACEHOLDER_PREFIX)?;
+    let suffix = suffix.strip_prefix('v')?;
+    let underscore = suffix.find('_')?;
+    let (revision, key) = suffix.split_at(underscore);
+    if revision.is_empty() || !revision.bytes().all(|b| b.is_ascii_digit()) {
+        return None;
+    }
+    let key = &key[1..];
+    if key.is_empty() || !key.bytes().all(is_env_key_char) {
+        return None;
+    }
+    Some(key)
+}
+
+fn uses_reserved_revision_namespace(key: &str) -> bool {
+    let Some(suffix) = key.strip_prefix('v') else {
+        return false;
+    };
+    let Some((revision, key)) = suffix.split_once('_') else {
+        return false;
+    };
+    !revision.is_empty()
+        && revision.bytes().all(|b| b.is_ascii_digit())
+        && !key.is_empty()
+        && key.bytes().all(is_env_key_char)
+}
+
 fn token_boundary_ok(text: &str, abs_start: usize, token_end: usize, token: &str) -> bool {
     if token.starts_with(PLACEHOLDER_PREFIX) {
         return token_end == text.len()
@@ -1044,6 +1083,18 @@ mod tests {
         );
     }
 
+    #[test]
+    fn provider_env_rejects_revision_namespace_keys() {
+        let (child_env, resolver) = SecretResolver::from_provider_env(
+            [("v10_GITHUB_TOKEN".to_string(), "ambiguous".to_string())]
+                .into_iter()
+                .collect(),
+        );
+
+        assert!(child_env.is_empty());
+        assert!(resolver.is_none());
+    }
+
     #[test]
     fn rewrites_exact_placeholder_header_values() {
         let (_, resolver) = SecretResolver::from_provider_env(
@@ -1077,6 +1128,28 @@ mod tests {
         );
     }
 
+    #[test]
+    fn rewrites_stale_revisioned_bearer_placeholder_to_current_alias() {
+        let (_, resolver) = SecretResolver::from_provider_env_for_revision_with_current_aliases(
+            [("GITHUB_TOKEN".to_string(), "ghp-current".to_string())]
+                .into_iter()
+                .collect(),
+            HashMap::new(),
+            42,
+            true,
+        );
+        let resolver = resolver.expect("resolver");
+
+        assert_eq!(
+            rewrite_header_line_checked(
+                "Authorization: Bearer openshell:resolve:env:v10_GITHUB_TOKEN",
+                &resolver,
+            )
+            .expect("stale revision should fall back to current alias"),
+            "Authorization: Bearer ghp-current"
+        );
+    }
+
     #[test]
     fn rewrites_provider_shaped_alias_header_values() {
         let (_, resolver) = SecretResolver::from_provider_env(

docs/sandboxes/providers-v2.mdx

@@ -239,7 +239,7 @@ binaries:
 
 `category` groups profiles in `openshell provider list-profiles`. Use one of the values in the category enum.
 
-`credentials` declares the credential names, environment variables, auth metadata, and optional refresh metadata for the provider type. The current runtime still exposes configured credential keys as placeholder environment variables and resolves placeholders in outbound HTTP requests.
+`credentials` declares the credential names, environment variables, auth metadata, and optional refresh metadata for the provider type. The current runtime still exposes configured credential keys as placeholder environment variables and resolves placeholders in outbound HTTP requests. Credential environment variable names must not use the reserved `v<digits>_` prefix, such as `v10_GITHUB_TOKEN`, because OpenShell uses that namespace for revision-scoped placeholders.
 
 `discovery` controls what `--from-existing` scans when
 `providers_v2_enabled=true`. Each entry in `discovery.credentials` must name a

openshell-agents/Dockerfile.gator

@@ -0,0 +1,94 @@
+# syntax=docker/dockerfile:1
+
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Gator sandbox image.
+#
+# This mirrors the OpenShell Community base image's core system and developer
+# tooling, but keeps the initial agent surface focused on Codex + GitHub tooling
+# for the gator-gate workflow.
+
+FROM nvcr.io/nvidia/base/ubuntu:noble-20251013 AS system
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /sandbox
+
+# Core system dependencies copied from the community base sandbox image.
+# iproute2: network namespace management (ip netns, veth pairs)
+# iptables: legacy bypass detection (kept for transition)
+# nftables: bypass detection; log + reject rules for direct connection diagnostics
+# dnsutils: dig, nslookup
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        dnsutils \
+        iproute2 \
+        iptables \
+        nftables \
+        iputils-ping \
+        net-tools \
+        netcat-openbsd \
+        openssh-sftp-server \
+        procps \
+        traceroute \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN groupadd -r supervisor && useradd -r -g supervisor -s /usr/sbin/nologin supervisor && \
+    groupadd -r sandbox && useradd -r -g sandbox -d /sandbox -s /bin/bash sandbox
+
+FROM system AS devtools
+
+# Node.js 22 + build toolchain. Keep the default apt installs aligned with the
+# community base image, then add the small CLI tools gator commonly needs.
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
+    apt-get install -y --no-install-recommends \
+        build-essential \
+        git \
+        jq \
+        less \
+        nodejs=22.22.1-1nodesource1 \
+        ripgrep \
+        vim-tiny \
+        nano \
+    && rm -rf /var/lib/apt/lists/* \
+    && npm install -g npm@11.11.0
+
+# GitHub CLI
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+        -o /usr/share/keyrings/githubcli-archive-keyring.gpg && \
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        > /etc/apt/sources.list.d/github-cli.list && \
+    apt-get update && apt-get install -y --no-install-recommends gh && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY runtime/harnesses/codex/install-codex.sh /usr/local/bin/install-codex.sh
+ARG CODEX_VERSION=latest
+RUN chmod 755 /usr/local/bin/install-codex.sh && \
+    /usr/local/bin/install-codex.sh "$CODEX_VERSION"
+
+# Provider profiles include both /usr/bin and /usr/local/bin variants for common
+# tools. Create the /usr/local/bin aliases in this image so sandbox symlink
+# resolution does not warn about missing alternate paths during policy reloads.
+RUN ln -sf /usr/bin/gh /usr/local/bin/gh && \
+    ln -sf /usr/bin/git /usr/local/bin/git && \
+    ln -sf /usr/bin/codex /usr/local/bin/codex
+
+FROM devtools AS final
+
+ENV PATH="/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin"
+
+RUN mkdir -p /etc/openshell
+COPY gator/policy.yaml /etc/openshell/policy.yaml
+
+RUN printf 'export PATH="/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin"\nexport PS1="\\u@\\h:\\w\\$ "\n' \
+        > /sandbox/.bashrc && \
+    printf '[ -f ~/.bashrc ] && . ~/.bashrc\n' > /sandbox/.profile && \
+    chown -R sandbox:sandbox /sandbox
+
+USER sandbox
+
+ENTRYPOINT ["/bin/bash"]