From 8c507194bda5bb51a7ee62325ad72e461fed90ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E6=B8=A1=E6=B3=95=E5=B8=AB?= <chaodu@openab.dev>
Date: Wed, 24 Jun 2026 16:15:56 +0000
Subject: [PATCH 1/8] =?UTF-8?q?feat:=20add=20pre=5Fseed=20phase=20?=
 =?UTF-8?q?=E2=80=94=20download=20&=20extract=20S3=20zips=20before=20prebo?=
 =?UTF-8?q?ot?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a new [pre_seed] config section that runs before pre_boot hooks.
Downloads up to 5 zip archives from S3 and extracts them in order to
$HOME (or a custom target), implementing a layer system where later
archives overwrite earlier ones.

Closes #1188
---
 Cargo.lock                         |  56 +++++++
 Cargo.toml                         |   3 +-
 config.toml.example                |  15 ++
 crates/openab-core/Cargo.toml      |   4 +-
 crates/openab-core/src/config.rs   |  24 +++
 crates/openab-core/src/lib.rs      |   2 +
 crates/openab-core/src/pre_seed.rs | 259 +++++++++++++++++++++++++++++
 docs/config-reference.md           |  29 ++++
 docs/hooks.md                      |  65 ++++++++
 src/main.rs                        |   6 +
 10 files changed, 461 insertions(+), 2 deletions(-)
 create mode 100644 crates/openab-core/src/pre_seed.rs

diff --git a/Cargo.lock b/Cargo.lock
index 520cbb67f..a04f6fd5f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -99,6 +99,15 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
+[[package]]
+name = "arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
+dependencies = [
+ "derive_arbitrary",
+]
+
 [[package]]
 name = "arc-swap"
 version = "1.9.1"
@@ -1015,6 +1024,12 @@ dependencies = [
  "winnow",
 ]
 
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
 [[package]]
 name = "crypto-bigint"
 version = "0.5.5"
@@ -1113,6 +1128,17 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "derive_arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "digest"
 version = "0.10.7"
@@ -2218,6 +2244,7 @@ dependencies = [
  "urlencoding",
  "uuid",
  "webpki-roots 0.26.11",
+ "zip",
 ]
 
 [[package]]
@@ -4367,12 +4394,41 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "zip"
+version = "2.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fabe6324e908f85a1c52063ce7aa26b68dcb7eb6dbc83a2d148403c9bc3eba50"
+dependencies = [
+ "arbitrary",
+ "crc32fast",
+ "crossbeam-utils",
+ "displaydoc",
+ "flate2",
+ "indexmap",
+ "memchr",
+ "thiserror 2.0.18",
+ "zopfli",
+]
+
 [[package]]
 name = "zmij"
 version = "1.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
 
+[[package]]
+name = "zopfli"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f05cd8797d63865425ff89b5c4a48804f35ba0ce8d125800027ad6017d2b5249"
+dependencies = [
+ "bumpalo",
+ "crc32fast",
+ "log",
+ "simd-adler32",
+]
+
 [[package]]
 name = "zune-core"
 version = "0.5.1"
diff --git a/Cargo.toml b/Cargo.toml
index ef07ba752..042ca6223 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -24,7 +24,7 @@ serenity = { version = "0.12", default-features = false, features = ["client", "
 
 [features]
 # Default: core only (Discord + Slack). Gateway ships as separate binary.
-default = ["discord", "slack", "secrets-aws", "agentcore", "config-s3"]
+default = ["discord", "slack", "secrets-aws", "agentcore", "config-s3", "pre-seed"]
 
 # Opt-in: compile all gateway adapters into a single unified binary
 unified = ["telegram", "line", "feishu", "googlechat", "wecom", "teams"]
@@ -37,6 +37,7 @@ slack = ["openab-core/slack"]
 secrets-aws = ["openab-core/secrets-aws"]
 agentcore = ["openab-core/agentcore"]
 config-s3 = ["openab-core/config-s3"]
+pre-seed = ["openab-core/pre-seed"]
 
 # Gateway adapters (each pulls in the gateway crate + axum for embedded server)
 telegram = ["dep:openab-gateway", "dep:axum", "openab-gateway/telegram"]
diff --git a/config.toml.example b/config.toml.example
index dfa7c68d4..b4d28038c 100644
--- a/config.toml.example
+++ b/config.toml.example
@@ -241,3 +241,18 @@ error_hold_ms = 2500
 # openab = "~/projects/openab"
 # infra  = "~/projects/infra-cdk"
 # web    = "~/projects/frontend"
+
+# --- Pre-seed: download & extract S3 zip archives before pre_boot ---
+# Seeds the agent environment (configs, tools, memory) before any hook runs.
+# Archives are extracted in order — later layers overwrite earlier ones (like container layers).
+# Max 5 sources. Only s3:// URIs with .zip format are supported.
+#
+# [pre_seed]
+# sources = [
+#   "s3://my-bucket/base-env.zip",            # Layer 1: base tools & configs
+#   "s3://my-bucket/shared-memory.zip",       # Layer 2: shared team memory
+#   "s3://my-bucket/agent-specific.zip",      # Layer 3: agent-specific overrides
+# ]
+# target = "/home/agent"                      # extraction target (default: $HOME)
+# timeout_seconds = 300                       # per-source timeout (default: 300)
+# on_failure = "abort"                        # "abort" or "warn" (default: "abort")
diff --git a/crates/openab-core/Cargo.toml b/crates/openab-core/Cargo.toml
index d7b53ded7..964d4a603 100644
--- a/crates/openab-core/Cargo.toml
+++ b/crates/openab-core/Cargo.toml
@@ -39,6 +39,7 @@ tempfile = "3.27.0"
 aws-sdk-secretsmanager = { version = "1", optional = true }
 aws-sdk-s3 = { version = "1", optional = true }
 aws-config = { version = "1", optional = true }
+zip = { version = "2", default-features = false, features = ["deflate"], optional = true }
 aws-sigv4 = { version = "1", optional = true }
 aws-credential-types = { version = "1", optional = true }
 urlencoding = { version = "2", optional = true }
@@ -49,9 +50,10 @@ http = { version = "1", optional = true }
 libc = "0.2"
 
 [features]
-default = ["discord", "slack", "secrets-aws", "agentcore", "config-s3"]
+default = ["discord", "slack", "secrets-aws", "agentcore", "config-s3", "pre-seed"]
 discord = ["dep:serenity"]
 slack = []
 secrets-aws = ["dep:aws-sdk-secretsmanager", "dep:aws-config"]
 config-s3 = ["dep:aws-sdk-s3", "dep:aws-config"]
+pre-seed = ["dep:aws-sdk-s3", "dep:aws-config", "dep:zip"]
 agentcore = ["dep:aws-config", "dep:aws-sigv4", "dep:aws-credential-types", "dep:urlencoding", "dep:hex", "dep:http", "dep:rustls", "dep:tokio-rustls", "dep:webpki-roots"]
diff --git a/crates/openab-core/src/config.rs b/crates/openab-core/src/config.rs
index b4aaf3fb4..9eed47c03 100644
--- a/crates/openab-core/src/config.rs
+++ b/crates/openab-core/src/config.rs
@@ -145,6 +145,8 @@ pub struct Config {
     #[serde(default)]
     pub hooks: HooksConfig,
     #[serde(default)]
+    pub pre_seed: PreSeedConfig,
+    #[serde(default)]
     pub workspace: WorkspaceConfig,
     #[serde(default)]
     pub secrets: SecretsConfig,
@@ -202,6 +204,28 @@ pub struct HooksConfig {
     pub pre_shutdown: Option<HookConfig>,
 }
 
+/// Configuration for the pre_seed phase.
+/// Downloads and extracts zip archives from S3 before pre_boot.
+#[derive(Debug, Clone, Default, Deserialize)]
+pub struct PreSeedConfig {
+    /// S3 URIs of zip archives to download and extract (max 5).
+    /// Extracted in order; later layers overwrite earlier ones.
+    #[serde(default)]
+    pub sources: Vec<String>,
+    /// Extraction target directory. Default: $HOME.
+    pub target: Option<String>,
+    /// Timeout in seconds for each download+extract operation. Default: 300.
+    #[serde(default = "default_pre_seed_timeout")]
+    pub timeout_seconds: u64,
+    /// Failure policy. Default: abort.
+    #[serde(default)]
+    pub on_failure: OnFailure,
+}
+
+fn default_pre_seed_timeout() -> u64 {
+    300
+}
+
 /// Failure policy for a hook.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub enum OnFailure {
diff --git a/crates/openab-core/src/lib.rs b/crates/openab-core/src/lib.rs
index c4af990df..b02848ac3 100644
--- a/crates/openab-core/src/lib.rs
+++ b/crates/openab-core/src/lib.rs
@@ -12,6 +12,8 @@ pub mod hooks;
 pub mod markdown;
 pub mod media;
 pub mod multibot_cache;
+#[cfg(feature = "pre-seed")]
+pub mod pre_seed;
 pub mod reactions;
 #[cfg(feature = "discord")]
 pub mod remind;
diff --git a/crates/openab-core/src/pre_seed.rs b/crates/openab-core/src/pre_seed.rs
new file mode 100644
index 000000000..02efcaf0f
--- /dev/null
+++ b/crates/openab-core/src/pre_seed.rs
@@ -0,0 +1,259 @@
+use crate::config::{OnFailure, PreSeedConfig};
+use std::path::Path;
+use tracing::{error, info, warn};
+
+/// Maximum number of sources allowed.
+const MAX_SOURCES: usize = 5;
+
+/// Run the pre_seed phase: download zip archives from S3 and extract them in order.
+pub async fn run(cfg: &PreSeedConfig) -> anyhow::Result<()> {
+    if cfg.sources.is_empty() {
+        return Ok(());
+    }
+    if cfg.sources.len() > MAX_SOURCES {
+        anyhow::bail!(
+            "pre_seed: too many sources ({}, max {})",
+            cfg.sources.len(),
+            MAX_SOURCES
+        );
+    }
+
+    let target = match &cfg.target {
+        Some(t) => std::path::PathBuf::from(t),
+        None => dirs_home(),
+    };
+
+    info!(
+        sources = cfg.sources.len(),
+        target = %target.display(),
+        "pre_seed: starting"
+    );
+
+    let aws_cfg = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
+    let s3 = aws_sdk_s3::Client::new(&aws_cfg);
+
+    for (i, source) in cfg.sources.iter().enumerate() {
+        let layer = i + 1;
+        info!(layer, source = source.as_str(), "pre_seed: downloading");
+
+        let result = tokio::time::timeout(
+            std::time::Duration::from_secs(cfg.timeout_seconds),
+            download_and_extract(&s3, source, &target),
+        )
+        .await;
+
+        let outcome = match result {
+            Ok(Ok(())) => {
+                info!(layer, "pre_seed: layer extracted successfully");
+                continue;
+            }
+            Ok(Err(e)) => e,
+            Err(_) => anyhow::anyhow!(
+                "pre_seed: layer {layer} timed out after {}s",
+                cfg.timeout_seconds
+            ),
+        };
+
+        match cfg.on_failure {
+            OnFailure::Abort => {
+                error!(layer, error = %outcome, "pre_seed failed (on_failure=abort)");
+                return Err(outcome);
+            }
+            OnFailure::Warn => {
+                warn!(layer, error = %outcome, "pre_seed failed (on_failure=warn), continuing");
+            }
+        }
+    }
+
+    info!("pre_seed: complete");
+    Ok(())
+}
+
+/// Parse s3://bucket/key, download the object, and extract the zip to target.
+async fn download_and_extract(
+    s3: &aws_sdk_s3::Client,
+    uri: &str,
+    target: &Path,
+) -> anyhow::Result<()> {
+    let (bucket, key) = parse_s3_uri(uri)?;
+
+    let resp = s3
+        .get_object()
+        .bucket(&bucket)
+        .key(&key)
+        .send()
+        .await
+        .map_err(|e| anyhow::anyhow!("S3 GetObject failed for {uri}: {e}"))?;
+
+    let body = resp
+        .body
+        .collect()
+        .await
+        .map_err(|e| anyhow::anyhow!("failed to read S3 body for {uri}: {e}"))?;
+    let bytes = body.into_bytes();
+
+    info!(uri, bytes = bytes.len(), "pre_seed: downloaded, extracting");
+
+    let target = target.to_path_buf();
+    let bytes_vec = bytes.to_vec();
+    tokio::task::spawn_blocking(move || extract_zip(&bytes_vec, &target))
+        .await
+        .map_err(|e| anyhow::anyhow!("pre_seed: extract task panicked: {e}"))??;
+
+    Ok(())
+}
+
+/// Extract a zip archive from memory into the target directory.
+fn extract_zip(data: &[u8], target: &Path) -> anyhow::Result<()> {
+    let cursor = std::io::Cursor::new(data);
+    let mut archive = zip::ZipArchive::new(cursor)?;
+
+    for i in 0..archive.len() {
+        let mut file = archive.by_index(i)?;
+        let name = file
+            .enclosed_name()
+            .ok_or_else(|| anyhow::anyhow!("pre_seed: invalid zip entry name at index {i}"))?;
+        let out_path = target.join(name);
+
+        if file.is_dir() {
+            std::fs::create_dir_all(&out_path)?;
+        } else {
+            if let Some(parent) = out_path.parent() {
+                std::fs::create_dir_all(parent)?;
+            }
+            let mut out = std::fs::File::create(&out_path)?;
+            std::io::copy(&mut file, &mut out)?;
+
+            // Preserve unix permissions
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                if let Some(mode) = file.unix_mode() {
+                    std::fs::set_permissions(&out_path, std::fs::Permissions::from_mode(mode))?;
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Parse an s3://bucket/key URI into (bucket, key).
+fn parse_s3_uri(uri: &str) -> anyhow::Result<(String, String)> {
+    let stripped = uri
+        .strip_prefix("s3://")
+        .ok_or_else(|| anyhow::anyhow!("pre_seed: source must start with s3://, got: {uri}"))?;
+    let (bucket, key) = stripped
+        .split_once('/')
+        .ok_or_else(|| anyhow::anyhow!("pre_seed: invalid S3 URI (no key): {uri}"))?;
+    if bucket.is_empty() || key.is_empty() {
+        anyhow::bail!("pre_seed: empty bucket or key in URI: {uri}");
+    }
+    Ok((bucket.to_string(), key.to_string()))
+}
+
+fn dirs_home() -> std::path::PathBuf {
+    std::env::var("HOME")
+        .map(std::path::PathBuf::from)
+        .unwrap_or_else(|_| std::path::PathBuf::from("/home/agent"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_s3_uri_valid() {
+        let (b, k) = parse_s3_uri("s3://my-bucket/path/to/file.zip").unwrap();
+        assert_eq!(b, "my-bucket");
+        assert_eq!(k, "path/to/file.zip");
+    }
+
+    #[test]
+    fn parse_s3_uri_no_prefix() {
+        assert!(parse_s3_uri("https://example.com/file.zip").is_err());
+    }
+
+    #[test]
+    fn parse_s3_uri_no_key() {
+        assert!(parse_s3_uri("s3://bucket-only").is_err());
+    }
+
+    #[test]
+    fn parse_s3_uri_empty_key() {
+        assert!(parse_s3_uri("s3://bucket/").is_err());
+    }
+
+    #[test]
+    fn parse_s3_uri_empty_bucket() {
+        assert!(parse_s3_uri("s3:///key").is_err());
+    }
+
+    #[test]
+    fn extract_zip_basic() {
+        use std::io::Write;
+        let dir = tempfile::tempdir().unwrap();
+
+        // Create a zip in memory
+        let buf = Vec::new();
+        let cursor = std::io::Cursor::new(buf);
+        let mut writer = zip::ZipWriter::new(cursor);
+        let options = zip::write::SimpleFileOptions::default();
+        writer.start_file("hello.txt", options).unwrap();
+        writer.write_all(b"world").unwrap();
+        writer.start_file("sub/nested.txt", options).unwrap();
+        writer.write_all(b"nested content").unwrap();
+        let cursor = writer.finish().unwrap();
+
+        extract_zip(cursor.get_ref(), dir.path()).unwrap();
+
+        assert_eq!(
+            std::fs::read_to_string(dir.path().join("hello.txt")).unwrap(),
+            "world"
+        );
+        assert_eq!(
+            std::fs::read_to_string(dir.path().join("sub/nested.txt")).unwrap(),
+            "nested content"
+        );
+    }
+
+    #[test]
+    fn extract_zip_overwrites() {
+        use std::io::Write;
+        let dir = tempfile::tempdir().unwrap();
+
+        // Write an initial file
+        std::fs::write(dir.path().join("hello.txt"), "original").unwrap();
+
+        // Create a zip that overwrites it
+        let buf = Vec::new();
+        let cursor = std::io::Cursor::new(buf);
+        let mut writer = zip::ZipWriter::new(cursor);
+        let options = zip::write::SimpleFileOptions::default();
+        writer.start_file("hello.txt", options).unwrap();
+        writer.write_all(b"overwritten").unwrap();
+        let cursor = writer.finish().unwrap();
+
+        extract_zip(cursor.get_ref(), dir.path()).unwrap();
+
+        assert_eq!(
+            std::fs::read_to_string(dir.path().join("hello.txt")).unwrap(),
+            "overwritten"
+        );
+    }
+
+    #[tokio::test]
+    async fn run_empty_sources() {
+        let cfg = PreSeedConfig::default();
+        assert!(run(&cfg).await.is_ok());
+    }
+
+    #[tokio::test]
+    async fn run_too_many_sources() {
+        let cfg = PreSeedConfig {
+            sources: vec!["s3://b/k.zip".into(); 6],
+            ..Default::default()
+        };
+        assert!(run(&cfg).await.is_err());
+    }
+}
diff --git a/docs/config-reference.md b/docs/config-reference.md
index dc6bea597..0de6be0d5 100644
--- a/docs/config-reference.md
+++ b/docs/config-reference.md
@@ -237,6 +237,35 @@ Session pool settings for managing concurrent agent sessions.
 
 ---
 
+## `[pre_seed]`
+
+Downloads and extracts zip archives from S3 before `pre_boot`. Seeds the agent environment with configs, tools, and shared memory without requiring AWS CLI in the image. See [hooks.md](hooks.md) for full lifecycle documentation.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `sources` | string[] | `[]` | S3 URIs of zip archives (`s3://bucket/key.zip`). Max 5. Extracted in order; later layers overwrite earlier ones. |
+| `target` | string | `$HOME` | Extraction target directory. |
+| `timeout_seconds` | u64 | `300` | Per-source download+extract timeout in seconds. |
+| `on_failure` | string | `"abort"` | `"abort"` exits openab; `"warn"` logs and continues. |
+
+**Credential resolution** uses the standard AWS provider chain (same as `config-s3` and `secrets-aws`):
+environment variables, shared credentials, IRSA / EKS Pod Identity, ECS task role.
+
+```toml
+[pre_seed]
+sources = [
+  "s3://my-bucket/base-env.zip",
+  "s3://my-bucket/shared-memory.zip",
+  "s3://my-bucket/agent-overrides.zip",
+]
+timeout_seconds = 300
+on_failure = "abort"
+```
+
+> **Feature flag:** requires the `pre-seed` feature (enabled by default).
+
+---
+
 ## `[hooks]`
 
 Lifecycle hooks that run custom scripts at specific points during the container lifecycle. See [hooks.md](hooks.md) for full documentation and examples.
diff --git a/docs/hooks.md b/docs/hooks.md
index 687253876..934660040 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -2,6 +2,71 @@
 
 OpenAB supports lifecycle hooks that run custom scripts at specific points during the container lifecycle. Hooks are configured in `config.toml` under the `[hooks]` table.
 
+## Lifecycle Order
+
+```
+pre_seed → pre_boot → (agent running) → pre_shutdown
+```
+
+| Phase | Purpose | Config |
+|-------|---------|--------|
+| `pre_seed` | Download & extract S3 zip archives to seed the environment | `[pre_seed]` |
+| `pre_boot` | Run custom setup scripts before agent pool creation | `[hooks.pre_boot]` |
+| `pre_shutdown` | Run custom cleanup scripts after pool shutdown | `[hooks.pre_shutdown]` |
+
+## Pre-Seed Phase
+
+The `pre_seed` phase runs **before** any hook. It downloads zip archives from S3 and extracts them into the agent's home directory (or a custom target). This eliminates the need for users to install AWS CLI and write download scripts in `pre_boot`.
+
+### Configuration
+
+```toml
+[pre_seed]
+sources = [
+  "s3://my-bucket/base-env.zip",
+  "s3://my-bucket/shared-memory.zip",
+  "s3://my-bucket/agent-overrides.zip",
+]
+# target = "/home/agent"    # default: $HOME
+# timeout_seconds = 300     # per-source timeout (default: 300)
+# on_failure = "abort"      # "abort" or "warn" (default: "abort")
+```
+
+### Layer Concept
+
+Sources are extracted sequentially (first → last). Files from later archives overwrite earlier ones — like layers in a container image:
+
+```
+Layer 3 (last)   ─── highest priority, overwrites all below
+Layer 2          ─── overwrites layer 1
+Layer 1 (first)  ─── base layer
+─────────────────
+     $HOME
+```
+
+### Constraints
+
+- Maximum **5** sources
+- Only `s3://` URIs supported
+- Only `.zip` format supported
+- Uses the standard AWS credential chain (IRSA, ECS task role, env vars)
+
+### IAM Policy
+
+```json
+{
+  "Effect": "Allow",
+  "Action": ["s3:GetObject"],
+  "Resource": [
+    "arn:aws:s3:::my-bucket/base-env.zip",
+    "arn:aws:s3:::my-bucket/shared-memory.zip",
+    "arn:aws:s3:::my-bucket/agent-overrides.zip"
+  ]
+}
+```
+
+---
+
 ## Available Hooks
 
 | Hook | Timing | Use Case |
diff --git a/src/main.rs b/src/main.rs
index 980590454..274544ce7 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -194,6 +194,12 @@ async fn main() -> anyhow::Result<()> {
         );
     }
 
+    // --- pre_seed: download & extract S3 zips before pre_boot ---
+    #[cfg(feature = "pre-seed")]
+    if !cfg.pre_seed.sources.is_empty() {
+        openab_core::pre_seed::run(&cfg.pre_seed).await?;
+    }
+
     // Validate and run pre_boot hook (before agent pool creation)
     if let Some(ref hook) = cfg.hooks.pre_boot {
         hooks::validate_hook("pre_boot", hook)?;

From 638f41dc5341b868b4af6c3996675ad477e20842 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E6=B8=A1=E6=B3=95=E5=B8=AB?= <chaodu@openab.dev>
Date: Wed, 24 Jun 2026 21:43:42 +0000
Subject: [PATCH 2/8] fix: address all review findings for pre_seed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Move pre_seed under [hooks.pre_seed] (consistent lifecycle grouping)
- Add SHA-256 integrity verification (sha256s field)
- Add max_bytes size cap (default 100 MiB) to prevent OOM
- Extract to temp dir first, then move into target (atomic, fixes
  spawn_blocking timeout race condition)
- Remove bytes.to_vec() — pass Bytes slice directly
- Add region/endpoint_url override (LocalStack/VPC support)
- Use shared parse_s3_uri from config.rs (dedup)
- Move pre-seed to opt-in feature (not in default)
- Manual Default impl (timeout_seconds=300, max_bytes=100MiB)
- Update docs and config example
---
 Cargo.toml                         |   2 +-
 config.toml.example                |  11 +-
 crates/openab-core/Cargo.toml      |   2 +-
 crates/openab-core/src/config.rs   |  35 ++++-
 crates/openab-core/src/pre_seed.rs | 219 ++++++++++++++++++++---------
 docs/config-reference.md           |  29 ++--
 docs/hooks.md                      |  55 ++++++--
 src/main.rs                        |   6 +-
 8 files changed, 262 insertions(+), 97 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 042ca6223..a53aa05b2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -24,7 +24,7 @@ serenity = { version = "0.12", default-features = false, features = ["client", "
 
 [features]
 # Default: core only (Discord + Slack). Gateway ships as separate binary.
-default = ["discord", "slack", "secrets-aws", "agentcore", "config-s3", "pre-seed"]
+default = ["discord", "slack", "secrets-aws", "agentcore", "config-s3"]
 
 # Opt-in: compile all gateway adapters into a single unified binary
 unified = ["telegram", "line", "feishu", "googlechat", "wecom", "teams"]
diff --git a/config.toml.example b/config.toml.example
index b4d28038c..508c1a310 100644
--- a/config.toml.example
+++ b/config.toml.example
@@ -246,13 +246,22 @@ error_hold_ms = 2500
 # Seeds the agent environment (configs, tools, memory) before any hook runs.
 # Archives are extracted in order — later layers overwrite earlier ones (like container layers).
 # Max 5 sources. Only s3:// URIs with .zip format are supported.
+# Requires the `pre-seed` feature flag (opt-in).
 #
-# [pre_seed]
+# [hooks.pre_seed]
 # sources = [
 #   "s3://my-bucket/base-env.zip",            # Layer 1: base tools & configs
 #   "s3://my-bucket/shared-memory.zip",       # Layer 2: shared team memory
 #   "s3://my-bucket/agent-specific.zip",      # Layer 3: agent-specific overrides
 # ]
+# sha256s = [                                 # optional: integrity verification per source
+#   "a1b2c3...",
+#   "d4e5f6...",
+#   "789abc...",
+# ]
 # target = "/home/agent"                      # extraction target (default: $HOME)
+# max_bytes = 104857600                       # max compressed zip size (default: 100 MiB)
 # timeout_seconds = 300                       # per-source timeout (default: 300)
 # on_failure = "abort"                        # "abort" or "warn" (default: "abort")
+# region = "us-west-2"                        # optional: override AWS region
+# endpoint_url = "http://localhost:4566"      # optional: LocalStack / VPC endpoint
diff --git a/crates/openab-core/Cargo.toml b/crates/openab-core/Cargo.toml
index 964d4a603..895914897 100644
--- a/crates/openab-core/Cargo.toml
+++ b/crates/openab-core/Cargo.toml
@@ -50,7 +50,7 @@ http = { version = "1", optional = true }
 libc = "0.2"
 
 [features]
-default = ["discord", "slack", "secrets-aws", "agentcore", "config-s3", "pre-seed"]
+default = ["discord", "slack", "secrets-aws", "agentcore", "config-s3"]
 discord = ["dep:serenity"]
 slack = []
 secrets-aws = ["dep:aws-sdk-secretsmanager", "dep:aws-config"]
diff --git a/crates/openab-core/src/config.rs b/crates/openab-core/src/config.rs
index 9eed47c03..0670d31f5 100644
--- a/crates/openab-core/src/config.rs
+++ b/crates/openab-core/src/config.rs
@@ -145,8 +145,6 @@ pub struct Config {
     #[serde(default)]
     pub hooks: HooksConfig,
     #[serde(default)]
-    pub pre_seed: PreSeedConfig,
-    #[serde(default)]
     pub workspace: WorkspaceConfig,
     #[serde(default)]
     pub secrets: SecretsConfig,
@@ -200,20 +198,32 @@ fn default_exec_timeout() -> u64 {
 
 #[derive(Debug, Clone, Default, Deserialize)]
 pub struct HooksConfig {
+    pub pre_seed: Option<PreSeedConfig>,
     pub pre_boot: Option<HookConfig>,
     pub pre_shutdown: Option<HookConfig>,
 }
 
 /// Configuration for the pre_seed phase.
 /// Downloads and extracts zip archives from S3 before pre_boot.
-#[derive(Debug, Clone, Default, Deserialize)]
+#[derive(Debug, Clone, Deserialize)]
 pub struct PreSeedConfig {
     /// S3 URIs of zip archives to download and extract (max 5).
     /// Extracted in order; later layers overwrite earlier ones.
     #[serde(default)]
     pub sources: Vec<String>,
+    /// Optional SHA-256 checksums for each source (same order as sources).
+    /// If provided, each zip is verified before extraction.
+    #[serde(default)]
+    pub sha256s: Vec<String>,
     /// Extraction target directory. Default: $HOME.
     pub target: Option<String>,
+    /// Override AWS region for S3 access.
+    pub region: Option<String>,
+    /// Override S3 endpoint URL (for LocalStack, VPC endpoints).
+    pub endpoint_url: Option<String>,
+    /// Maximum compressed zip size in bytes. Default: 100 MiB.
+    #[serde(default = "default_max_zip_bytes")]
+    pub max_bytes: u64,
     /// Timeout in seconds for each download+extract operation. Default: 300.
     #[serde(default = "default_pre_seed_timeout")]
     pub timeout_seconds: u64,
@@ -222,6 +232,25 @@ pub struct PreSeedConfig {
     pub on_failure: OnFailure,
 }
 
+impl Default for PreSeedConfig {
+    fn default() -> Self {
+        Self {
+            sources: Vec::new(),
+            sha256s: Vec::new(),
+            target: None,
+            region: None,
+            endpoint_url: None,
+            max_bytes: default_max_zip_bytes(),
+            timeout_seconds: default_pre_seed_timeout(),
+            on_failure: OnFailure::Abort,
+        }
+    }
+}
+
+fn default_max_zip_bytes() -> u64 {
+    100 * 1024 * 1024 // 100 MiB
+}
+
 fn default_pre_seed_timeout() -> u64 {
     300
 }
diff --git a/crates/openab-core/src/pre_seed.rs b/crates/openab-core/src/pre_seed.rs
index 02efcaf0f..8f428a26f 100644
--- a/crates/openab-core/src/pre_seed.rs
+++ b/crates/openab-core/src/pre_seed.rs
@@ -1,4 +1,5 @@
-use crate::config::{OnFailure, PreSeedConfig};
+use crate::config::{parse_s3_uri, OnFailure, PreSeedConfig};
+use sha2::{Digest, Sha256};
 use std::path::Path;
 use tracing::{error, info, warn};
 
@@ -12,11 +13,18 @@ pub async fn run(cfg: &PreSeedConfig) -> anyhow::Result<()> {
     }
     if cfg.sources.len() > MAX_SOURCES {
         anyhow::bail!(
-            "pre_seed: too many sources ({}, max {})",
+            "hooks.pre_seed: too many sources ({}, max {})",
             cfg.sources.len(),
             MAX_SOURCES
         );
     }
+    if !cfg.sha256s.is_empty() && cfg.sha256s.len() != cfg.sources.len() {
+        anyhow::bail!(
+            "hooks.pre_seed: sha256s length ({}) must match sources length ({})",
+            cfg.sha256s.len(),
+            cfg.sources.len()
+        );
+    }
 
     let target = match &cfg.target {
         Some(t) => std::path::PathBuf::from(t),
@@ -26,54 +34,68 @@ pub async fn run(cfg: &PreSeedConfig) -> anyhow::Result<()> {
     info!(
         sources = cfg.sources.len(),
         target = %target.display(),
-        "pre_seed: starting"
+        "hooks.pre_seed: starting"
     );
 
-    let aws_cfg = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
+    let mut s3_config_loader = aws_config::defaults(aws_config::BehaviorVersion::latest());
+    if let Some(ref region) = cfg.region {
+        s3_config_loader = s3_config_loader.region(aws_config::Region::new(region.clone()));
+    }
+    if let Some(ref endpoint) = cfg.endpoint_url {
+        s3_config_loader = s3_config_loader.endpoint_url(endpoint);
+    }
+    let aws_cfg = s3_config_loader.load().await;
     let s3 = aws_sdk_s3::Client::new(&aws_cfg);
 
     for (i, source) in cfg.sources.iter().enumerate() {
         let layer = i + 1;
-        info!(layer, source = source.as_str(), "pre_seed: downloading");
+        let expected_sha = cfg.sha256s.get(i).map(|s| s.as_str());
+        info!(
+            layer,
+            source = source.as_str(),
+            "hooks.pre_seed: downloading"
+        );
 
         let result = tokio::time::timeout(
             std::time::Duration::from_secs(cfg.timeout_seconds),
-            download_and_extract(&s3, source, &target),
+            download_and_extract(&s3, source, &target, expected_sha, cfg.max_bytes),
         )
         .await;
 
         let outcome = match result {
             Ok(Ok(())) => {
-                info!(layer, "pre_seed: layer extracted successfully");
+                info!(layer, "hooks.pre_seed: layer extracted successfully");
                 continue;
             }
             Ok(Err(e)) => e,
             Err(_) => anyhow::anyhow!(
-                "pre_seed: layer {layer} timed out after {}s",
+                "hooks.pre_seed: layer {layer} timed out after {}s",
                 cfg.timeout_seconds
             ),
         };
 
         match cfg.on_failure {
             OnFailure::Abort => {
-                error!(layer, error = %outcome, "pre_seed failed (on_failure=abort)");
+                error!(layer, error = %outcome, "hooks.pre_seed failed (on_failure=abort)");
                 return Err(outcome);
             }
             OnFailure::Warn => {
-                warn!(layer, error = %outcome, "pre_seed failed (on_failure=warn), continuing");
+                warn!(layer, error = %outcome, "hooks.pre_seed failed (on_failure=warn), continuing");
             }
         }
     }
 
-    info!("pre_seed: complete");
+    info!("hooks.pre_seed: complete");
     Ok(())
 }
 
-/// Parse s3://bucket/key, download the object, and extract the zip to target.
+/// Download zip from S3, verify integrity, extract to a temp dir, then move into target.
 async fn download_and_extract(
     s3: &aws_sdk_s3::Client,
     uri: &str,
     target: &Path,
+    expected_sha: Option<&str>,
+    max_bytes: u64,
 ) -> anyhow::Result<()> {
     let (bucket, key) = parse_s3_uri(uri)?;
 
@@ -85,6 +107,13 @@ async fn download_and_extract(
         .await
         .map_err(|e| anyhow::anyhow!("S3 GetObject failed for {uri}: {e}"))?;
 
+    // Check content length before downloading body
+    if let Some(len) = resp.content_length() {
+        if len as u64 > max_bytes {
+            anyhow::bail!("hooks.pre_seed: {uri} too large ({len} bytes, max {max_bytes})");
+        }
+    }
+
     let body = resp
         .body
         .collect()
@@ -92,28 +121,64 @@ async fn download_and_extract(
         .map_err(|e| anyhow::anyhow!("failed to read S3 body for {uri}: {e}"))?;
     let bytes = body.into_bytes();
 
-    info!(uri, bytes = bytes.len(), "pre_seed: downloaded, extracting");
+    if bytes.len() as u64 > max_bytes {
+        anyhow::bail!(
+            "hooks.pre_seed: {uri} too large ({} bytes, max {max_bytes})",
+            bytes.len()
+        );
+    }
+
+    // SHA-256 verification
+    if let Some(expected) = expected_sha {
+        let mut hasher = Sha256::new();
+        hasher.update(&bytes);
+        let actual = format!("{:x}", hasher.finalize());
+        if actual != expected.to_lowercase() {
+            anyhow::bail!(
+                "hooks.pre_seed: SHA-256 mismatch for {uri}: expected {expected}, got {actual}"
+            );
+        }
+        info!(uri, "hooks.pre_seed: SHA-256 verified");
+    }
 
+    info!(
+        uri,
+        bytes = bytes.len(),
+        "hooks.pre_seed: downloaded, extracting"
+    );
+
+    // Extract to a temp dir first, then move files into target.
+    // This ensures that if extraction fails or times out, target is not corrupted.
     let target = target.to_path_buf();
-    let bytes_vec = bytes.to_vec();
-    tokio::task::spawn_blocking(move || extract_zip(&bytes_vec, &target))
+    tokio::task::spawn_blocking(move || extract_to_target(&bytes, &target))
         .await
-        .map_err(|e| anyhow::anyhow!("pre_seed: extract task panicked: {e}"))??;
+        .map_err(|e| anyhow::anyhow!("hooks.pre_seed: extract task panicked: {e}"))??;
 
     Ok(())
 }
 
-/// Extract a zip archive from memory into the target directory.
-fn extract_zip(data: &[u8], target: &Path) -> anyhow::Result<()> {
+/// Extract zip to a temp directory, then move all files into target atomically.
+fn extract_to_target(data: &[u8], target: &Path) -> anyhow::Result<()> {
+    let temp_dir = tempfile::tempdir_in(target.parent().unwrap_or(target))?;
+    extract_zip(data, temp_dir.path())?;
+
+    // Move extracted files from temp dir into target
+    move_recursive(temp_dir.path(), target)?;
+
+    Ok(())
+}
+
+/// Extract a zip archive from memory into the given directory.
+fn extract_zip(data: &[u8], dest: &Path) -> anyhow::Result<()> {
     let cursor = std::io::Cursor::new(data);
     let mut archive = zip::ZipArchive::new(cursor)?;
 
     for i in 0..archive.len() {
         let mut file = archive.by_index(i)?;
-        let name = file
-            .enclosed_name()
-            .ok_or_else(|| anyhow::anyhow!("pre_seed: invalid zip entry name at index {i}"))?;
-        let out_path = target.join(name);
+        let name = file.enclosed_name().ok_or_else(|| {
+            anyhow::anyhow!("hooks.pre_seed: invalid zip entry name at index {i}")
+        })?;
+        let out_path = dest.join(name);
 
         if file.is_dir() {
             std::fs::create_dir_all(&out_path)?;
@@ -124,7 +189,6 @@ fn extract_zip(data: &[u8], target: &Path) -> anyhow::Result<()> {
             let mut out = std::fs::File::create(&out_path)?;
             std::io::copy(&mut file, &mut out)?;
 
-            // Preserve unix permissions
             #[cfg(unix)]
             {
                 use std::os::unix::fs::PermissionsExt;
@@ -138,18 +202,25 @@ fn extract_zip(data: &[u8], target: &Path) -> anyhow::Result<()> {
     Ok(())
 }
 
-/// Parse an s3://bucket/key URI into (bucket, key).
-fn parse_s3_uri(uri: &str) -> anyhow::Result<(String, String)> {
-    let stripped = uri
-        .strip_prefix("s3://")
-        .ok_or_else(|| anyhow::anyhow!("pre_seed: source must start with s3://, got: {uri}"))?;
-    let (bucket, key) = stripped
-        .split_once('/')
-        .ok_or_else(|| anyhow::anyhow!("pre_seed: invalid S3 URI (no key): {uri}"))?;
-    if bucket.is_empty() || key.is_empty() {
-        anyhow::bail!("pre_seed: empty bucket or key in URI: {uri}");
+/// Recursively move files from src directory into dst directory.
+fn move_recursive(src: &Path, dst: &Path) -> anyhow::Result<()> {
+    for entry in std::fs::read_dir(src)? {
+        let entry = entry?;
+        let src_path = entry.path();
+        let dst_path = dst.join(entry.file_name());
+
+        if src_path.is_dir() {
+            std::fs::create_dir_all(&dst_path)?;
+            move_recursive(&src_path, &dst_path)?;
+        } else {
+            // rename is atomic on same filesystem; fallback to copy+remove
+            if std::fs::rename(&src_path, &dst_path).is_err() {
+                std::fs::copy(&src_path, &dst_path)?;
+                std::fs::remove_file(&src_path)?;
+            }
+        }
     }
-    Ok((bucket.to_string(), key.to_string()))
+    Ok(())
 }
 
 fn dirs_home() -> std::path::PathBuf {
@@ -162,39 +233,11 @@ fn dirs_home() -> std::path::PathBuf {
 mod tests {
     use super::*;
 
-    #[test]
-    fn parse_s3_uri_valid() {
-        let (b, k) = parse_s3_uri("s3://my-bucket/path/to/file.zip").unwrap();
-        assert_eq!(b, "my-bucket");
-        assert_eq!(k, "path/to/file.zip");
-    }
-
-    #[test]
-    fn parse_s3_uri_no_prefix() {
-        assert!(parse_s3_uri("https://example.com/file.zip").is_err());
-    }
-
-    #[test]
-    fn parse_s3_uri_no_key() {
-        assert!(parse_s3_uri("s3://bucket-only").is_err());
-    }
-
-    #[test]
-    fn parse_s3_uri_empty_key() {
-        assert!(parse_s3_uri("s3://bucket/").is_err());
-    }
-
-    #[test]
-    fn parse_s3_uri_empty_bucket() {
-        assert!(parse_s3_uri("s3:///key").is_err());
-    }
-
     #[test]
     fn extract_zip_basic() {
         use std::io::Write;
         let dir = tempfile::tempdir().unwrap();
 
-        // Create a zip in memory
         let buf = Vec::new();
         let cursor = std::io::Cursor::new(buf);
         let mut writer = zip::ZipWriter::new(cursor);
@@ -217,15 +260,40 @@ mod tests {
         );
     }
 
+    #[test]
+    fn extract_to_target_atomic() {
+        use std::io::Write;
+        let target = tempfile::tempdir().unwrap();
+
+        // Pre-existing file that should survive
+        std::fs::write(target.path().join("existing.txt"), "keep").unwrap();
+
+        let buf = Vec::new();
+        let cursor = std::io::Cursor::new(buf);
+        let mut writer = zip::ZipWriter::new(cursor);
+        let options = zip::write::SimpleFileOptions::default();
+        writer.start_file("new.txt", options).unwrap();
+        writer.write_all(b"added").unwrap();
+        let cursor = writer.finish().unwrap();
+
+        extract_to_target(cursor.get_ref(), target.path()).unwrap();
+
+        assert_eq!(
+            std::fs::read_to_string(target.path().join("existing.txt")).unwrap(),
+            "keep"
+        );
+        assert_eq!(
+            std::fs::read_to_string(target.path().join("new.txt")).unwrap(),
+            "added"
+        );
+    }
+
     #[test]
     fn extract_zip_overwrites() {
         use std::io::Write;
         let dir = tempfile::tempdir().unwrap();
-
-        // Write an initial file
         std::fs::write(dir.path().join("hello.txt"), "original").unwrap();
 
-        // Create a zip that overwrites it
         let buf = Vec::new();
         let cursor = std::io::Cursor::new(buf);
         let mut writer = zip::ZipWriter::new(cursor);
@@ -234,7 +302,7 @@ mod tests {
         writer.write_all(b"overwritten").unwrap();
         let cursor = writer.finish().unwrap();
 
-        extract_zip(cursor.get_ref(), dir.path()).unwrap();
+        extract_to_target(cursor.get_ref(), dir.path()).unwrap();
 
         assert_eq!(
             std::fs::read_to_string(dir.path().join("hello.txt")).unwrap(),
@@ -256,4 +324,23 @@ mod tests {
         };
         assert!(run(&cfg).await.is_err());
     }
+
+    #[tokio::test]
+    async fn run_sha256s_length_mismatch() {
+        let cfg = PreSeedConfig {
+            sources: vec!["s3://b/k.zip".into()],
+            sha256s: vec!["abc".into(), "def".into()],
+            ..Default::default()
+        };
+        assert!(run(&cfg).await.is_err());
+    }
+
+    #[test]
+    fn default_has_correct_values() {
+        let cfg = PreSeedConfig::default();
+        assert_eq!(cfg.timeout_seconds, 300);
+        assert_eq!(cfg.max_bytes, 100 * 1024 * 1024);
+        assert_eq!(cfg.on_failure, OnFailure::Abort);
+        assert!(cfg.sources.is_empty());
+    }
 }
diff --git a/docs/config-reference.md b/docs/config-reference.md
index 0de6be0d5..97b74f21d 100644
--- a/docs/config-reference.md
+++ b/docs/config-reference.md
@@ -237,39 +237,46 @@ Session pool settings for managing concurrent agent sessions.
 
 ---
 
-## `[pre_seed]`
+## `[hooks]`
+
+Lifecycle hooks that run at specific points during the container lifecycle. See [hooks.md](hooks.md) for full documentation and examples.
+
+### `[hooks.pre_seed]`
 
-Downloads and extracts zip archives from S3 before `pre_boot`. Seeds the agent environment with configs, tools, and shared memory without requiring AWS CLI in the image. See [hooks.md](hooks.md) for full lifecycle documentation.
+Downloads and extracts zip archives from S3 before `pre_boot`. Seeds the agent environment with configs, tools, and shared memory without requiring AWS CLI in the image.
+
+> **Feature flag:** requires the `pre-seed` feature (opt-in, not in default). Enable with `--features pre-seed`.
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | `sources` | string[] | `[]` | S3 URIs of zip archives (`s3://bucket/key.zip`). Max 5. Extracted in order; later layers overwrite earlier ones. |
+| `sha256s` | string[] | `[]` | SHA-256 checksums per source (same order). If provided, must match sources length. |
 | `target` | string | `$HOME` | Extraction target directory. |
+| `max_bytes` | u64 | `104857600` | Max compressed zip size in bytes (100 MiB). Rejects downloads exceeding this. |
 | `timeout_seconds` | u64 | `300` | Per-source download+extract timeout in seconds. |
 | `on_failure` | string | `"abort"` | `"abort"` exits openab; `"warn"` logs and continues. |
+| `region` | string | — | Override AWS region for S3 access. |
+| `endpoint_url` | string | — | Override S3 endpoint URL (for LocalStack, VPC endpoints). |
 
 **Credential resolution** uses the standard AWS provider chain (same as `config-s3` and `secrets-aws`):
 environment variables, shared credentials, IRSA / EKS Pod Identity, ECS task role.
 
 ```toml
-[pre_seed]
+[hooks.pre_seed]
 sources = [
   "s3://my-bucket/base-env.zip",
   "s3://my-bucket/shared-memory.zip",
   "s3://my-bucket/agent-overrides.zip",
 ]
+sha256s = [
+  "a1b2c3d4...",
+  "e5f67890...",
+  "abcdef12...",
+]
 timeout_seconds = 300
 on_failure = "abort"
 ```
 
-> **Feature flag:** requires the `pre-seed` feature (enabled by default).
-
----
-
-## `[hooks]`
-
-Lifecycle hooks that run custom scripts at specific points during the container lifecycle. See [hooks.md](hooks.md) for full documentation and examples.
-
 ### `[hooks.pre_boot]`
 
 Runs **before** agent pool creation. Use for bootstrapping files, syncing from S3, installing CLIs.
diff --git a/docs/hooks.md b/docs/hooks.md
index 934660040..bce8600c0 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -1,37 +1,60 @@
 # Lifecycle Hooks
 
-OpenAB supports lifecycle hooks that run custom scripts at specific points during the container lifecycle. Hooks are configured in `config.toml` under the `[hooks]` table.
+OpenAB supports lifecycle hooks that run at specific points during the container lifecycle. All lifecycle phases are configured in `config.toml` under the `[hooks]` table.
 
 ## Lifecycle Order
 
 ```
-pre_seed → pre_boot → (agent running) → pre_shutdown
+hooks.pre_seed → hooks.pre_boot → (agent running) → hooks.pre_shutdown
 ```
 
-| Phase | Purpose | Config |
-|-------|---------|--------|
-| `pre_seed` | Download & extract S3 zip archives to seed the environment | `[pre_seed]` |
-| `pre_boot` | Run custom setup scripts before agent pool creation | `[hooks.pre_boot]` |
-| `pre_shutdown` | Run custom cleanup scripts after pool shutdown | `[hooks.pre_shutdown]` |
+| Phase | Purpose | Config | Action Type |
+|-------|---------|--------|-------------|
+| `pre_seed` | Download & extract S3 zip archives to seed the environment | `[hooks.pre_seed]` | Built-in S3 download + unzip |
+| `pre_boot` | Run custom setup scripts before agent pool creation | `[hooks.pre_boot]` | User script |
+| `pre_shutdown` | Run custom cleanup scripts after pool shutdown | `[hooks.pre_shutdown]` | User script |
 
 ## Pre-Seed Phase
 
-The `pre_seed` phase runs **before** any hook. It downloads zip archives from S3 and extracts them into the agent's home directory (or a custom target). This eliminates the need for users to install AWS CLI and write download scripts in `pre_boot`.
+The `pre_seed` phase runs **before** `pre_boot`. It downloads zip archives from S3 and extracts them into the agent's home directory (or a custom target). This eliminates the need for users to install AWS CLI and write download scripts in `pre_boot`.
+
+> **Feature flag:** requires the `pre-seed` feature (opt-in, not in default).
 
 ### Configuration
 
 ```toml
-[pre_seed]
+[hooks.pre_seed]
 sources = [
   "s3://my-bucket/base-env.zip",
   "s3://my-bucket/shared-memory.zip",
   "s3://my-bucket/agent-overrides.zip",
 ]
-# target = "/home/agent"    # default: $HOME
-# timeout_seconds = 300     # per-source timeout (default: 300)
-# on_failure = "abort"      # "abort" or "warn" (default: "abort")
+sha256s = [
+  "a1b2c3d4e5f6...",
+  "789abcdef012...",
+  "345678901234...",
+]
+# target = "/home/agent"                  # default: $HOME
+# max_bytes = 104857600                   # max compressed size per zip (default: 100 MiB)
+# timeout_seconds = 300                   # per-source timeout (default: 300)
+# on_failure = "abort"                    # "abort" or "warn" (default: "abort")
+# region = "us-west-2"                    # optional: override AWS region
+# endpoint_url = "http://localhost:4566"  # optional: LocalStack / VPC endpoint
 ```
 
+### Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `sources` | string[] | `[]` | S3 URIs of zip archives. Max 5. Extracted in order. |
+| `sha256s` | string[] | `[]` | SHA-256 checksums per source (same order). If provided, must match sources length. |
+| `target` | string | `$HOME` | Extraction target directory. |
+| `max_bytes` | u64 | `104857600` | Max compressed zip size in bytes (100 MiB). |
+| `timeout_seconds` | u64 | `300` | Per-source download+extract timeout. |
+| `on_failure` | string | `"abort"` | `"abort"` exits openab; `"warn"` logs and continues. |
+| `region` | string | — | Override AWS region. |
+| `endpoint_url` | string | — | Override S3 endpoint URL. |
+
 ### Layer Concept
 
 Sources are extracted sequentially (first → last). Files from later archives overwrite earlier ones — like layers in a container image:
@@ -44,12 +67,20 @@ Layer 1 (first)  ─── base layer
      $HOME
 ```
 
+### Safety
+
+- **Integrity verification**: when `sha256s` is provided, each zip is verified before extraction (matching the security bar of `[hooks.pre_boot]` URL scripts)
+- **Size cap**: downloads exceeding `max_bytes` are rejected before extraction
+- **Atomic extraction**: zips are first extracted to a temp directory, then moved into target — partial failures don't corrupt the environment
+- **Zip Slip prevention**: uses `enclosed_name()` to block path traversal attacks
+
 ### Constraints
 
 - Maximum **5** sources
 - Only `s3://` URIs supported
 - Only `.zip` format supported
 - Uses the standard AWS credential chain (IRSA, ECS task role, env vars)
+- Optional `region`/`endpoint_url` override for LocalStack or VPC endpoints
 
 ### IAM Policy
 
diff --git a/src/main.rs b/src/main.rs
index 274544ce7..15f90db10 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -196,8 +196,10 @@ async fn main() -> anyhow::Result<()> {
 
     // --- pre_seed: download & extract S3 zips before pre_boot ---
     #[cfg(feature = "pre-seed")]
-    if !cfg.pre_seed.sources.is_empty() {
-        openab_core::pre_seed::run(&cfg.pre_seed).await?;
+    if let Some(ref pre_seed) = cfg.hooks.pre_seed {
+        if !pre_seed.sources.is_empty() {
+            openab_core::pre_seed::run(pre_seed).await?;
+        }
     }
 
     // Validate and run pre_boot hook (before agent pool creation)

From 789d7815253f312ae2023a51a86fda03e4496f0f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E6=B8=A1=E6=B3=95=E5=B8=AB?= <chaodu@openab.dev>
Date: Wed, 24 Jun 2026 21:46:45 +0000
Subject: [PATCH 3/8] fix: enforce cooperative deadline in blocking extraction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Replace tokio::time::timeout with cooperative Instant deadline
  passed into the blocking task
- Check deadline before each file extraction and each move operation
- If deadline expires mid-extraction, bail immediately (temp dir
  auto-cleans via Drop) — target never gets partial writes
- Add extracted bytes budget (500 MiB) and file count limit (10k)
  to prevent zip-bomb disk/CPU exhaustion
- Add tests for expired deadline, move deadline enforcement
---
 crates/openab-core/src/pre_seed.rs | 149 ++++++++++++++++++++++-------
 1 file changed, 115 insertions(+), 34 deletions(-)

diff --git a/crates/openab-core/src/pre_seed.rs b/crates/openab-core/src/pre_seed.rs
index 8f428a26f..1a27f4d01 100644
--- a/crates/openab-core/src/pre_seed.rs
+++ b/crates/openab-core/src/pre_seed.rs
@@ -1,11 +1,18 @@
 use crate::config::{parse_s3_uri, OnFailure, PreSeedConfig};
 use sha2::{Digest, Sha256};
 use std::path::Path;
+use std::time::Instant;
 use tracing::{error, info, warn};
 
 /// Maximum number of sources allowed.
 const MAX_SOURCES: usize = 5;
 
+/// Default max extracted (uncompressed) size: 500 MiB.
+const DEFAULT_MAX_EXTRACTED_BYTES: u64 = 500 * 1024 * 1024;
+
+/// Default max file count per zip.
+const DEFAULT_MAX_FILE_COUNT: usize = 10_000;
+
 /// Run the pre_seed phase: download zip archives from S3 and extract them in order.
 pub async fn run(cfg: &PreSeedConfig) -> anyhow::Result<()> {
     if cfg.sources.is_empty() {
@@ -56,22 +63,17 @@ pub async fn run(cfg: &PreSeedConfig) -> anyhow::Result<()> {
             "hooks.pre_seed: downloading"
         );
 
-        let result = tokio::time::timeout(
-            std::time::Duration::from_secs(cfg.timeout_seconds),
-            download_and_extract(&s3, source, &target, expected_sha, cfg.max_bytes),
-        )
-        .await;
+        let deadline = Instant::now() + std::time::Duration::from_secs(cfg.timeout_seconds);
+
+        let result =
+            download_and_extract(&s3, source, &target, expected_sha, cfg.max_bytes, deadline).await;
 
         let outcome = match result {
-            Ok(Ok(())) => {
+            Ok(()) => {
                 info!(layer, "hooks.pre_seed: layer extracted successfully");
                 continue;
             }
-            Ok(Err(e)) => e,
-            Err(_) => anyhow::anyhow!(
-                "hooks.pre_seed: layer {layer} timed out after {}s",
-                cfg.timeout_seconds
-            ),
+            Err(e) => e,
         };
 
         match cfg.on_failure {
@@ -90,15 +92,22 @@ pub async fn run(cfg: &PreSeedConfig) -> anyhow::Result<()> {
 }
 
 /// Download zip from S3, verify integrity, extract to a temp dir, then move into target.
+/// The deadline is enforced cooperatively inside the blocking task.
 async fn download_and_extract(
     s3: &aws_sdk_s3::Client,
     uri: &str,
     target: &Path,
     expected_sha: Option<&str>,
     max_bytes: u64,
+    deadline: Instant,
 ) -> anyhow::Result<()> {
     let (bucket, key) = parse_s3_uri(uri)?;
 
+    // Check deadline before S3 call
+    if Instant::now() >= deadline {
+        anyhow::bail!("hooks.pre_seed: timed out before download for {uri}");
+    }
+
     let resp = s3
         .get_object()
         .bucket(&bucket)
@@ -107,7 +116,6 @@ async fn download_and_extract(
         .await
         .map_err(|e| anyhow::anyhow!("S3 GetObject failed for {uri}: {e}"))?;
 
-    // Check content length before downloading body
     if let Some(len) = resp.content_length() {
         if len as u64 > max_bytes {
             anyhow::bail!("hooks.pre_seed: {uri} too large ({len} bytes, max {max_bytes})");
@@ -141,39 +149,63 @@ async fn download_and_extract(
         info!(uri, "hooks.pre_seed: SHA-256 verified");
     }
 
+    if Instant::now() >= deadline {
+        anyhow::bail!("hooks.pre_seed: timed out after download for {uri}");
+    }
+
     info!(
         uri,
         bytes = bytes.len(),
         "hooks.pre_seed: downloaded, extracting"
     );
 
-    // Extract to a temp dir first, then move files into target.
-    // This ensures that if extraction fails or times out, target is not corrupted.
+    // Extract and move in a blocking task with cooperative deadline checking.
     let target = target.to_path_buf();
-    tokio::task::spawn_blocking(move || extract_to_target(&bytes, &target))
+    let data = bytes.to_vec(); // need owned data for 'static Send
+    tokio::task::spawn_blocking(move || extract_and_apply(&data, &target, deadline))
         .await
         .map_err(|e| anyhow::anyhow!("hooks.pre_seed: extract task panicked: {e}"))??;
 
     Ok(())
 }
 
-/// Extract zip to a temp directory, then move all files into target atomically.
-fn extract_to_target(data: &[u8], target: &Path) -> anyhow::Result<()> {
+/// Extract zip to a temp directory with budget enforcement, then move into target.
+/// Checks deadline cooperatively before each file operation.
+fn extract_and_apply(data: &[u8], target: &Path, deadline: Instant) -> anyhow::Result<()> {
     let temp_dir = tempfile::tempdir_in(target.parent().unwrap_or(target))?;
-    extract_zip(data, temp_dir.path())?;
 
-    // Move extracted files from temp dir into target
-    move_recursive(temp_dir.path(), target)?;
+    extract_zip_with_limits(data, temp_dir.path(), deadline)?;
 
+    // Check deadline before applying to target
+    if Instant::now() >= deadline {
+        // temp_dir drops and cleans up automatically
+        anyhow::bail!("hooks.pre_seed: timed out before applying to target");
+    }
+
+    move_recursive(temp_dir.path(), target, deadline)?;
     Ok(())
 }
 
-/// Extract a zip archive from memory into the given directory.
-fn extract_zip(data: &[u8], dest: &Path) -> anyhow::Result<()> {
+/// Extract a zip archive with cooperative deadline checks and extraction budget.
+fn extract_zip_with_limits(data: &[u8], dest: &Path, deadline: Instant) -> anyhow::Result<()> {
     let cursor = std::io::Cursor::new(data);
     let mut archive = zip::ZipArchive::new(cursor)?;
 
-    for i in 0..archive.len() {
+    let file_count = archive.len();
+    if file_count > DEFAULT_MAX_FILE_COUNT {
+        anyhow::bail!(
+            "hooks.pre_seed: zip contains too many entries ({file_count}, max {DEFAULT_MAX_FILE_COUNT})"
+        );
+    }
+
+    let mut total_extracted: u64 = 0;
+
+    for i in 0..file_count {
+        // Cooperative deadline check per file
+        if i % 100 == 0 && Instant::now() >= deadline {
+            anyhow::bail!("hooks.pre_seed: timed out during extraction at entry {i}");
+        }
+
         let mut file = archive.by_index(i)?;
         let name = file.enclosed_name().ok_or_else(|| {
             anyhow::anyhow!("hooks.pre_seed: invalid zip entry name at index {i}")
@@ -186,6 +218,16 @@ fn extract_zip(data: &[u8], dest: &Path) -> anyhow::Result<()> {
             if let Some(parent) = out_path.parent() {
                 std::fs::create_dir_all(parent)?;
             }
+
+            // Check extracted size budget before writing
+            let uncompressed = file.size();
+            total_extracted += uncompressed;
+            if total_extracted > DEFAULT_MAX_EXTRACTED_BYTES {
+                anyhow::bail!(
+                    "hooks.pre_seed: extracted size exceeds limit ({total_extracted} > {DEFAULT_MAX_EXTRACTED_BYTES})"
+                );
+            }
+
             let mut out = std::fs::File::create(&out_path)?;
             std::io::copy(&mut file, &mut out)?;
 
@@ -203,17 +245,21 @@ fn extract_zip(data: &[u8], dest: &Path) -> anyhow::Result<()> {
 }
 
 /// Recursively move files from src directory into dst directory.
-fn move_recursive(src: &Path, dst: &Path) -> anyhow::Result<()> {
+/// Checks deadline cooperatively.
+fn move_recursive(src: &Path, dst: &Path, deadline: Instant) -> anyhow::Result<()> {
     for entry in std::fs::read_dir(src)? {
+        if Instant::now() >= deadline {
+            anyhow::bail!("hooks.pre_seed: timed out during move to target");
+        }
+
         let entry = entry?;
         let src_path = entry.path();
         let dst_path = dst.join(entry.file_name());
 
         if src_path.is_dir() {
             std::fs::create_dir_all(&dst_path)?;
-            move_recursive(&src_path, &dst_path)?;
+            move_recursive(&src_path, &dst_path, deadline)?;
         } else {
-            // rename is atomic on same filesystem; fallback to copy+remove
             if std::fs::rename(&src_path, &dst_path).is_err() {
                 std::fs::copy(&src_path, &dst_path)?;
                 std::fs::remove_file(&src_path)?;
@@ -237,6 +283,7 @@ mod tests {
     fn extract_zip_basic() {
         use std::io::Write;
         let dir = tempfile::tempdir().unwrap();
+        let deadline = Instant::now() + std::time::Duration::from_secs(60);
 
         let buf = Vec::new();
         let cursor = std::io::Cursor::new(buf);
@@ -248,7 +295,7 @@ mod tests {
         writer.write_all(b"nested content").unwrap();
         let cursor = writer.finish().unwrap();
 
-        extract_zip(cursor.get_ref(), dir.path()).unwrap();
+        extract_zip_with_limits(cursor.get_ref(), dir.path(), deadline).unwrap();
 
         assert_eq!(
             std::fs::read_to_string(dir.path().join("hello.txt")).unwrap(),
@@ -261,11 +308,11 @@ mod tests {
     }
 
     #[test]
-    fn extract_to_target_atomic() {
+    fn extract_and_apply_atomic() {
         use std::io::Write;
         let target = tempfile::tempdir().unwrap();
+        let deadline = Instant::now() + std::time::Duration::from_secs(60);
 
-        // Pre-existing file that should survive
         std::fs::write(target.path().join("existing.txt"), "keep").unwrap();
 
         let buf = Vec::new();
@@ -276,7 +323,7 @@ mod tests {
         writer.write_all(b"added").unwrap();
         let cursor = writer.finish().unwrap();
 
-        extract_to_target(cursor.get_ref(), target.path()).unwrap();
+        extract_and_apply(cursor.get_ref(), target.path(), deadline).unwrap();
 
         assert_eq!(
             std::fs::read_to_string(target.path().join("existing.txt")).unwrap(),
@@ -289,10 +336,32 @@ mod tests {
     }
 
     #[test]
-    fn extract_zip_overwrites() {
+    fn extract_respects_expired_deadline() {
         use std::io::Write;
         let dir = tempfile::tempdir().unwrap();
-        std::fs::write(dir.path().join("hello.txt"), "original").unwrap();
+        // Already expired deadline
+        let deadline = Instant::now() - std::time::Duration::from_secs(1);
+
+        let buf = Vec::new();
+        let cursor = std::io::Cursor::new(buf);
+        let mut writer = zip::ZipWriter::new(cursor);
+        let options = zip::write::SimpleFileOptions::default();
+        writer.start_file("a.txt", options).unwrap();
+        writer.write_all(b"data").unwrap();
+        let cursor = writer.finish().unwrap();
+
+        // extract_and_apply should fail due to expired deadline
+        let result = extract_and_apply(cursor.get_ref(), dir.path(), deadline);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("timed out"));
+    }
+
+    #[test]
+    fn extract_zip_overwrites() {
+        use std::io::Write;
+        let target = tempfile::tempdir().unwrap();
+        let deadline = Instant::now() + std::time::Duration::from_secs(60);
+        std::fs::write(target.path().join("hello.txt"), "original").unwrap();
 
         let buf = Vec::new();
         let cursor = std::io::Cursor::new(buf);
@@ -302,10 +371,10 @@ mod tests {
         writer.write_all(b"overwritten").unwrap();
         let cursor = writer.finish().unwrap();
 
-        extract_to_target(cursor.get_ref(), dir.path()).unwrap();
+        extract_and_apply(cursor.get_ref(), target.path(), deadline).unwrap();
 
         assert_eq!(
-            std::fs::read_to_string(dir.path().join("hello.txt")).unwrap(),
+            std::fs::read_to_string(target.path().join("hello.txt")).unwrap(),
             "overwritten"
         );
     }
@@ -343,4 +412,16 @@ mod tests {
         assert_eq!(cfg.on_failure, OnFailure::Abort);
         assert!(cfg.sources.is_empty());
     }
+
+    #[test]
+    fn move_respects_deadline() {
+        let src = tempfile::tempdir().unwrap();
+        let dst = tempfile::tempdir().unwrap();
+        std::fs::write(src.path().join("f.txt"), "x").unwrap();
+
+        let expired = Instant::now() - std::time::Duration::from_secs(1);
+        let result = move_recursive(src.path(), dst.path(), expired);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("timed out"));
+    }
 }

From ef32eba4acd2318168777e54ed94170016cb1e3a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E6=B8=A1=E6=B3=95=E5=B8=AB?= <chaodu@openab.dev>
Date: Wed, 24 Jun 2026 21:48:06 +0000
Subject: [PATCH 4/8] fix: use Bytes directly (zero-copy) instead of to_vec()

Bytes is Arc-backed; clone is a ref-count bump, not a memcpy.
This eliminates the last unnecessary memory copy.
---
 crates/openab-core/src/pre_seed.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/openab-core/src/pre_seed.rs b/crates/openab-core/src/pre_seed.rs
index 1a27f4d01..69d75a88d 100644
--- a/crates/openab-core/src/pre_seed.rs
+++ b/crates/openab-core/src/pre_seed.rs
@@ -161,8 +161,8 @@ async fn download_and_extract(
 
     // Extract and move in a blocking task with cooperative deadline checking.
     let target = target.to_path_buf();
-    let data = bytes.to_vec(); // need owned data for 'static Send
-    tokio::task::spawn_blocking(move || extract_and_apply(&data, &target, deadline))
+    // Bytes is Arc-backed, Clone is zero-copy (ref-count bump only)
+    tokio::task::spawn_blocking(move || extract_and_apply(&bytes, &target, deadline))
         .await
         .map_err(|e| anyhow::anyhow!("hooks.pre_seed: extract task panicked: {e}"))??;
 

From 5ab9c387307950ba89b94062335077ee1dac494e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E6=B8=A1=E6=B3=95=E5=B8=AB?= <chaodu@openab.dev>
Date: Wed, 24 Jun 2026 21:48:57 +0000
Subject: [PATCH 5/8] fix: add extraction budget tests, clarify non-atomic move
 in docs

- Add test for file count limit (DEFAULT_MAX_FILE_COUNT + 1 entries)
- Add test verifying normal zips pass budget checks
- Update docs/hooks.md: clarify move phase is per-file, not atomic
  (partial apply possible with on_failure=warn)
---
 crates/openab-core/src/pre_seed.rs | 58 ++++++++++++++++++++++++++++++
 docs/hooks.md                      |  2 +-
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/crates/openab-core/src/pre_seed.rs b/crates/openab-core/src/pre_seed.rs
index 69d75a88d..ed04efd55 100644
--- a/crates/openab-core/src/pre_seed.rs
+++ b/crates/openab-core/src/pre_seed.rs
@@ -424,4 +424,62 @@ mod tests {
         assert!(result.is_err());
         assert!(result.unwrap_err().to_string().contains("timed out"));
     }
+
+    #[test]
+    fn extract_rejects_exceeding_extracted_bytes() {
+        use std::io::Write;
+        let dir = tempfile::tempdir().unwrap();
+        let deadline = Instant::now() + std::time::Duration::from_secs(60);
+
+        // Create a zip with content larger than DEFAULT_MAX_EXTRACTED_BYTES
+        // We'll use a file that claims a large uncompressed size by writing enough data
+        // Instead, test with a smaller limit by temporarily checking the logic:
+        // The limit is 500 MiB which is too large to test directly.
+        // We test the mechanism by creating a zip with known sizes and verifying
+        // the tracking works correctly in the success case (covered by other tests).
+        // For the failure case, we verify the error message format.
+
+        // Create a zip with 2 files, each 300 MiB uncompressed size declared
+        // This is impractical to actually write, so we test via the file count limit instead.
+        // See extract_rejects_exceeding_file_count below.
+        // This test verifies the cumulative tracking doesn't false-positive on normal zips.
+        let buf = Vec::new();
+        let cursor = std::io::Cursor::new(buf);
+        let mut writer = zip::ZipWriter::new(cursor);
+        let options = zip::write::SimpleFileOptions::default();
+        for i in 0..100 {
+            writer.start_file(format!("file_{i}.txt"), options).unwrap();
+            writer.write_all(b"small content").unwrap();
+        }
+        let cursor = writer.finish().unwrap();
+
+        // Should succeed — well within limits
+        let result = extract_zip_with_limits(cursor.get_ref(), dir.path(), deadline);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn extract_rejects_exceeding_file_count() {
+        use std::io::Write;
+        let dir = tempfile::tempdir().unwrap();
+        let deadline = Instant::now() + std::time::Duration::from_secs(60);
+
+        // Create a zip with more than DEFAULT_MAX_FILE_COUNT entries
+        let buf = Vec::new();
+        let cursor = std::io::Cursor::new(buf);
+        let mut writer = zip::ZipWriter::new(cursor);
+        let options = zip::write::SimpleFileOptions::default();
+        for i in 0..DEFAULT_MAX_FILE_COUNT + 1 {
+            writer.start_file(format!("f_{i}.txt"), options).unwrap();
+            writer.write_all(b"x").unwrap();
+        }
+        let cursor = writer.finish().unwrap();
+
+        let result = extract_zip_with_limits(cursor.get_ref(), dir.path(), deadline);
+        assert!(result.is_err());
+        assert!(
+            result.unwrap_err().to_string().contains("too many entries"),
+            "should fail on file count limit"
+        );
+    }
 }
diff --git a/docs/hooks.md b/docs/hooks.md
index bce8600c0..95175bd64 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -71,7 +71,7 @@ Layer 1 (first)  ─── base layer
 
 - **Integrity verification**: when `sha256s` is provided, each zip is verified before extraction (matching the security bar of `[hooks.pre_boot]` URL scripts)
 - **Size cap**: downloads exceeding `max_bytes` are rejected before extraction
-- **Atomic extraction**: zips are first extracted to a temp directory, then moved into target — partial failures don't corrupt the environment
+- **Atomic extraction**: zips are first extracted to a temp directory, then moved into target — if extraction fails, target is not corrupted. Note: the move phase is per-file; if it fails mid-way with `on_failure = "warn"`, the target may be partially updated.
 - **Zip Slip prevention**: uses `enclosed_name()` to block path traversal attacks
 
 ### Constraints

From 1396e3d7e83c326e8061158b0202b098b121a52d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E6=B8=A1=E6=B3=95=E5=B8=AB?= <chaodu@openab.dev>
Date: Wed, 24 Jun 2026 21:50:56 +0000
Subject: [PATCH 6/8] fix: add real regression tests for extraction budget
 limits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- extract_rejects_exceeding_extracted_bytes: uses extract_zip_budgeted
  with max_bytes=20, zip has 30 bytes → fails as expected
- extract_rejects_exceeding_file_count: uses extract_zip_budgeted
  with max_file_count=3, zip has 5 files → fails as expected
- Refactored extract_zip_with_limits to delegate to extract_zip_budgeted
  with configurable limits for testability
---
 crates/openab-core/src/pre_seed.rs | 62 ++++++++++++++++++------------
 1 file changed, 38 insertions(+), 24 deletions(-)

diff --git a/crates/openab-core/src/pre_seed.rs b/crates/openab-core/src/pre_seed.rs
index ed04efd55..86e2ab9e7 100644
--- a/crates/openab-core/src/pre_seed.rs
+++ b/crates/openab-core/src/pre_seed.rs
@@ -188,13 +188,30 @@ fn extract_and_apply(data: &[u8], target: &Path, deadline: Instant) -> anyhow::R
 
 /// Extract a zip archive with cooperative deadline checks and extraction budget.
 fn extract_zip_with_limits(data: &[u8], dest: &Path, deadline: Instant) -> anyhow::Result<()> {
+    extract_zip_budgeted(
+        data,
+        dest,
+        deadline,
+        DEFAULT_MAX_FILE_COUNT,
+        DEFAULT_MAX_EXTRACTED_BYTES,
+    )
+}
+
+/// Inner extraction with configurable limits (enables testing with small budgets).
+fn extract_zip_budgeted(
+    data: &[u8],
+    dest: &Path,
+    deadline: Instant,
+    max_file_count: usize,
+    max_extracted_bytes: u64,
+) -> anyhow::Result<()> {
     let cursor = std::io::Cursor::new(data);
     let mut archive = zip::ZipArchive::new(cursor)?;
 
     let file_count = archive.len();
-    if file_count > DEFAULT_MAX_FILE_COUNT {
+    if file_count > max_file_count {
         anyhow::bail!(
-            "hooks.pre_seed: zip contains too many entries ({file_count}, max {DEFAULT_MAX_FILE_COUNT})"
+            "hooks.pre_seed: zip contains too many entries ({file_count}, max {max_file_count})"
         );
     }
 
@@ -222,9 +239,9 @@ fn extract_zip_with_limits(data: &[u8], dest: &Path, deadline: Instant) -> anyho
             // Check extracted size budget before writing
             let uncompressed = file.size();
             total_extracted += uncompressed;
-            if total_extracted > DEFAULT_MAX_EXTRACTED_BYTES {
+            if total_extracted > max_extracted_bytes {
                 anyhow::bail!(
-                    "hooks.pre_seed: extracted size exceeds limit ({total_extracted} > {DEFAULT_MAX_EXTRACTED_BYTES})"
+                    "hooks.pre_seed: extracted size exceeds limit ({total_extracted} > {max_extracted_bytes})"
                 );
             }
 
@@ -431,31 +448,27 @@ mod tests {
         let dir = tempfile::tempdir().unwrap();
         let deadline = Instant::now() + std::time::Duration::from_secs(60);
 
-        // Create a zip with content larger than DEFAULT_MAX_EXTRACTED_BYTES
-        // We'll use a file that claims a large uncompressed size by writing enough data
-        // Instead, test with a smaller limit by temporarily checking the logic:
-        // The limit is 500 MiB which is too large to test directly.
-        // We test the mechanism by creating a zip with known sizes and verifying
-        // the tracking works correctly in the success case (covered by other tests).
-        // For the failure case, we verify the error message format.
-
-        // Create a zip with 2 files, each 300 MiB uncompressed size declared
-        // This is impractical to actually write, so we test via the file count limit instead.
-        // See extract_rejects_exceeding_file_count below.
-        // This test verifies the cumulative tracking doesn't false-positive on normal zips.
+        // Create a zip with 3 files of 10 bytes each (30 bytes total extracted)
         let buf = Vec::new();
         let cursor = std::io::Cursor::new(buf);
         let mut writer = zip::ZipWriter::new(cursor);
         let options = zip::write::SimpleFileOptions::default();
-        for i in 0..100 {
+        for i in 0..3 {
             writer.start_file(format!("file_{i}.txt"), options).unwrap();
-            writer.write_all(b"small content").unwrap();
+            writer.write_all(&[b'x'; 10]).unwrap();
         }
         let cursor = writer.finish().unwrap();
 
-        // Should succeed — well within limits
-        let result = extract_zip_with_limits(cursor.get_ref(), dir.path(), deadline);
-        assert!(result.is_ok());
+        // Set max extracted bytes to 20 — fails on 3rd file (cumulative 30 > 20)
+        let result = extract_zip_budgeted(cursor.get_ref(), dir.path(), deadline, 10_000, 20);
+        assert!(result.is_err());
+        assert!(
+            result
+                .unwrap_err()
+                .to_string()
+                .contains("extracted size exceeds limit"),
+            "should fail on extracted bytes limit"
+        );
     }
 
     #[test]
@@ -464,18 +477,19 @@ mod tests {
         let dir = tempfile::tempdir().unwrap();
         let deadline = Instant::now() + std::time::Duration::from_secs(60);
 
-        // Create a zip with more than DEFAULT_MAX_FILE_COUNT entries
+        // Create a zip with 5 files
         let buf = Vec::new();
         let cursor = std::io::Cursor::new(buf);
         let mut writer = zip::ZipWriter::new(cursor);
         let options = zip::write::SimpleFileOptions::default();
-        for i in 0..DEFAULT_MAX_FILE_COUNT + 1 {
+        for i in 0..5 {
             writer.start_file(format!("f_{i}.txt"), options).unwrap();
             writer.write_all(b"x").unwrap();
         }
         let cursor = writer.finish().unwrap();
 
-        let result = extract_zip_with_limits(cursor.get_ref(), dir.path(), deadline);
+        // Set max file count to 3 — should fail (5 > 3)
+        let result = extract_zip_budgeted(cursor.get_ref(), dir.path(), deadline, 3, u64::MAX);
         assert!(result.is_err());
         assert!(
             result.unwrap_err().to_string().contains("too many entries"),

From 08dca1490df6e88744938face048f46953c23e72 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E6=B8=A1=E6=B3=95=E5=B8=AB?= <chaodu@openab.dev>
Date: Wed, 24 Jun 2026 21:58:12 +0000
Subject: [PATCH 7/8] feat: auto-verify S3-native SHA-256 checksums on download

- Request ChecksumMode::Enabled in GetObject call
- If S3 object has x-amz-checksum-sha256 (uploaded with
  --checksum-algorithm SHA256), verify automatically
- User-provided sha256s still works as additional layer
- Add docs recommending 'aws s3 cp --checksum-algorithm SHA256'
- No config change needed for S3-native verification
---
 crates/openab-core/Cargo.toml      |  2 +-
 crates/openab-core/src/pre_seed.rs | 40 ++++++++++++++++++++++++------
 docs/hooks.md                      | 20 ++++++++++++++-
 3 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/crates/openab-core/Cargo.toml b/crates/openab-core/Cargo.toml
index 895914897..01005c1bf 100644
--- a/crates/openab-core/Cargo.toml
+++ b/crates/openab-core/Cargo.toml
@@ -55,5 +55,5 @@ discord = ["dep:serenity"]
 slack = []
 secrets-aws = ["dep:aws-sdk-secretsmanager", "dep:aws-config"]
 config-s3 = ["dep:aws-sdk-s3", "dep:aws-config"]
-pre-seed = ["dep:aws-sdk-s3", "dep:aws-config", "dep:zip"]
+pre-seed = ["dep:aws-sdk-s3", "dep:aws-config", "dep:zip", "dep:hex"]
 agentcore = ["dep:aws-config", "dep:aws-sigv4", "dep:aws-credential-types", "dep:urlencoding", "dep:hex", "dep:http", "dep:rustls", "dep:tokio-rustls", "dep:webpki-roots"]
diff --git a/crates/openab-core/src/pre_seed.rs b/crates/openab-core/src/pre_seed.rs
index 86e2ab9e7..a62dcec5d 100644
--- a/crates/openab-core/src/pre_seed.rs
+++ b/crates/openab-core/src/pre_seed.rs
@@ -112,6 +112,7 @@ async fn download_and_extract(
         .get_object()
         .bucket(&bucket)
         .key(&key)
+        .checksum_mode(aws_sdk_s3::types::ChecksumMode::Enabled)
         .send()
         .await
         .map_err(|e| anyhow::anyhow!("S3 GetObject failed for {uri}: {e}"))?;
@@ -122,6 +123,9 @@ async fn download_and_extract(
         }
     }
 
+    // Capture S3-native SHA-256 checksum if present (set during upload with --checksum-algorithm SHA256)
+    let s3_checksum_sha256 = resp.checksum_sha256().map(|s| s.to_string());
+
     let body = resp
         .body
         .collect()
@@ -136,17 +140,30 @@ async fn download_and_extract(
         );
     }
 
-    // SHA-256 verification
+    // SHA-256 verification: check S3-native checksum and/or user-provided sha256s
+    let mut hasher = Sha256::new();
+    hasher.update(&bytes);
+    let actual_hex = format!("{:x}", hasher.finalize());
+
+    // 1. Verify against S3 object checksum (auto, if object was uploaded with checksum)
+    if let Some(ref s3_b64) = s3_checksum_sha256 {
+        let s3_hex = base64_sha256_to_hex(s3_b64)?;
+        if actual_hex != s3_hex {
+            anyhow::bail!(
+                "hooks.pre_seed: S3 checksum mismatch for {uri}: expected {s3_hex}, got {actual_hex}"
+            );
+        }
+        info!(uri, "hooks.pre_seed: S3-native SHA-256 verified");
+    }
+
+    // 2. Verify against user-provided sha256s (if configured)
     if let Some(expected) = expected_sha {
-        let mut hasher = Sha256::new();
-        hasher.update(&bytes);
-        let actual = format!("{:x}", hasher.finalize());
-        if actual != expected.to_lowercase() {
+        if actual_hex != expected.to_lowercase() {
             anyhow::bail!(
-                "hooks.pre_seed: SHA-256 mismatch for {uri}: expected {expected}, got {actual}"
+                "hooks.pre_seed: SHA-256 mismatch for {uri}: expected {expected}, got {actual_hex}"
             );
         }
-        info!(uri, "hooks.pre_seed: SHA-256 verified");
+        info!(uri, "hooks.pre_seed: user SHA-256 verified");
     }
 
     if Instant::now() >= deadline {
@@ -286,6 +303,15 @@ fn move_recursive(src: &Path, dst: &Path, deadline: Instant) -> anyhow::Result<(
     Ok(())
 }
 
+/// Decode a base64-encoded SHA-256 (as returned by S3) to lowercase hex.
+fn base64_sha256_to_hex(b64: &str) -> anyhow::Result<String> {
+    use base64::Engine;
+    let decoded = base64::engine::general_purpose::STANDARD
+        .decode(b64)
+        .map_err(|e| anyhow::anyhow!("hooks.pre_seed: invalid base64 in S3 checksum: {e}"))?;
+    Ok(hex::encode(decoded))
+}
+
 fn dirs_home() -> std::path::PathBuf {
     std::env::var("HOME")
         .map(std::path::PathBuf::from)
diff --git a/docs/hooks.md b/docs/hooks.md
index 95175bd64..14b7907cd 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -69,7 +69,9 @@ Layer 1 (first)  ─── base layer
 
 ### Safety
 
-- **Integrity verification**: when `sha256s` is provided, each zip is verified before extraction (matching the security bar of `[hooks.pre_boot]` URL scripts)
+- **Integrity verification**: two layers of protection:
+  1. **S3-native checksum (automatic)**: if the object was uploaded with `--checksum-algorithm SHA256`, OpenAB automatically verifies it on download — no config needed
+  2. **User-provided `sha256s` (optional)**: explicit checksums in config for additional defense-in-depth
 - **Size cap**: downloads exceeding `max_bytes` are rejected before extraction
 - **Atomic extraction**: zips are first extracted to a temp directory, then moved into target — if extraction fails, target is not corrupted. Note: the move phase is per-file; if it fails mid-way with `on_failure = "warn"`, the target may be partially updated.
 - **Zip Slip prevention**: uses `enclosed_name()` to block path traversal attacks
@@ -96,6 +98,22 @@ Layer 1 (first)  ─── base layer
 }
 ```
 
+### Recommended: Enable S3 Checksums on Upload
+
+For automatic integrity verification without maintaining `sha256s` in config, upload zip archives with SHA-256 checksums enabled:
+
+```bash
+# Upload with SHA-256 checksum (recommended)
+aws s3 cp env.zip s3://my-bucket/env.zip --checksum-algorithm SHA256
+
+# Verify it was stored
+aws s3api head-object --bucket my-bucket --key env.zip --checksum-mode ENABLED
+```
+
+When objects have S3-native SHA-256 checksums, OpenAB verifies them automatically on download — no `sha256s` config needed. This is the simplest path to integrity verification.
+
+> **Note:** If `sha256s` is also provided in config, both checks run. The S3-native check uses the base64-encoded checksum from the `x-amz-checksum-sha256` response header. If neither is available, download proceeds without integrity verification (relies on IAM + bucket policy for trust).
+
 ---
 
 ## Available Hooks

From f2f3f87cd4967ccc246e47d3fc917c77c72c8493 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E6=B8=A1=E6=B3=95=E5=B8=AB?= <chaodu@openab.dev>
Date: Wed, 24 Jun 2026 22:02:54 +0000
Subject: [PATCH 8/8] simplify: remove sha256s field, rely on S3-native
 checksum only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

S3 supports native SHA-256 checksums (x-amz-checksum-sha256) when
objects are uploaded with --checksum-algorithm SHA256. OpenAB now
automatically verifies this on download — no user config needed.

Removed the sha256s field to reduce maintenance burden (users had
to update hashes on every zip change). Trust model:
- Object has S3 checksum → auto-verified
- Object has no checksum → trust IAM + bucket policy (same as config-s3)

Users just need: aws s3 cp file.zip s3://bucket/ --checksum-algorithm SHA256
---
 config.toml.example                |  5 ----
 crates/openab-core/src/config.rs   |  5 ----
 crates/openab-core/src/pre_seed.rs | 42 ++++--------------------------
 docs/config-reference.md           |  8 ++----
 docs/hooks.md                      |  6 -----
 5 files changed, 7 insertions(+), 59 deletions(-)

diff --git a/config.toml.example b/config.toml.example
index 508c1a310..83cd74a37 100644
--- a/config.toml.example
+++ b/config.toml.example
@@ -254,11 +254,6 @@ error_hold_ms = 2500
 #   "s3://my-bucket/shared-memory.zip",       # Layer 2: shared team memory
 #   "s3://my-bucket/agent-specific.zip",      # Layer 3: agent-specific overrides
 # ]
-# sha256s = [                                 # optional: integrity verification per source
-#   "a1b2c3...",
-#   "d4e5f6...",
-#   "789abc...",
-# ]
 # target = "/home/agent"                      # extraction target (default: $HOME)
 # max_bytes = 104857600                       # max compressed zip size (default: 100 MiB)
 # timeout_seconds = 300                       # per-source timeout (default: 300)
diff --git a/crates/openab-core/src/config.rs b/crates/openab-core/src/config.rs
index 0670d31f5..f0018572c 100644
--- a/crates/openab-core/src/config.rs
+++ b/crates/openab-core/src/config.rs
@@ -211,10 +211,6 @@ pub struct PreSeedConfig {
     /// Extracted in order; later layers overwrite earlier ones.
     #[serde(default)]
     pub sources: Vec<String>,
-    /// Optional SHA-256 checksums for each source (same order as sources).
-    /// If provided, each zip is verified before extraction.
-    #[serde(default)]
-    pub sha256s: Vec<String>,
     /// Extraction target directory. Default: $HOME.
     pub target: Option<String>,
     /// Override AWS region for S3 access.
@@ -236,7 +232,6 @@ impl Default for PreSeedConfig {
     fn default() -> Self {
         Self {
             sources: Vec::new(),
-            sha256s: Vec::new(),
             target: None,
             region: None,
             endpoint_url: None,
diff --git a/crates/openab-core/src/pre_seed.rs b/crates/openab-core/src/pre_seed.rs
index a62dcec5d..576344f9c 100644
--- a/crates/openab-core/src/pre_seed.rs
+++ b/crates/openab-core/src/pre_seed.rs
@@ -25,13 +25,6 @@ pub async fn run(cfg: &PreSeedConfig) -> anyhow::Result<()> {
             MAX_SOURCES
         );
     }
-    if !cfg.sha256s.is_empty() && cfg.sha256s.len() != cfg.sources.len() {
-        anyhow::bail!(
-            "hooks.pre_seed: sha256s length ({}) must match sources length ({})",
-            cfg.sha256s.len(),
-            cfg.sources.len()
-        );
-    }
 
     let target = match &cfg.target {
         Some(t) => std::path::PathBuf::from(t),
@@ -56,7 +49,6 @@ pub async fn run(cfg: &PreSeedConfig) -> anyhow::Result<()> {
 
     for (i, source) in cfg.sources.iter().enumerate() {
         let layer = i + 1;
-        let expected_sha = cfg.sha256s.get(i).map(|s| s.as_str());
         info!(
             layer,
             source = source.as_str(),
@@ -65,8 +57,7 @@ pub async fn run(cfg: &PreSeedConfig) -> anyhow::Result<()> {
 
         let deadline = Instant::now() + std::time::Duration::from_secs(cfg.timeout_seconds);
 
-        let result =
-            download_and_extract(&s3, source, &target, expected_sha, cfg.max_bytes, deadline).await;
+        let result = download_and_extract(&s3, source, &target, cfg.max_bytes, deadline).await;
 
         let outcome = match result {
             Ok(()) => {
@@ -97,7 +88,6 @@ async fn download_and_extract(
     s3: &aws_sdk_s3::Client,
     uri: &str,
     target: &Path,
-    expected_sha: Option<&str>,
     max_bytes: u64,
     deadline: Instant,
 ) -> anyhow::Result<()> {
@@ -140,13 +130,11 @@ async fn download_and_extract(
         );
     }
 
-    // SHA-256 verification: check S3-native checksum and/or user-provided sha256s
-    let mut hasher = Sha256::new();
-    hasher.update(&bytes);
-    let actual_hex = format!("{:x}", hasher.finalize());
-
-    // 1. Verify against S3 object checksum (auto, if object was uploaded with checksum)
+    // SHA-256 verification: auto-verify S3-native checksum if present
     if let Some(ref s3_b64) = s3_checksum_sha256 {
+        let mut hasher = Sha256::new();
+        hasher.update(&bytes);
+        let actual_hex = format!("{:x}", hasher.finalize());
         let s3_hex = base64_sha256_to_hex(s3_b64)?;
         if actual_hex != s3_hex {
             anyhow::bail!(
@@ -156,16 +144,6 @@ async fn download_and_extract(
         info!(uri, "hooks.pre_seed: S3-native SHA-256 verified");
     }
 
-    // 2. Verify against user-provided sha256s (if configured)
-    if let Some(expected) = expected_sha {
-        if actual_hex != expected.to_lowercase() {
-            anyhow::bail!(
-                "hooks.pre_seed: SHA-256 mismatch for {uri}: expected {expected}, got {actual_hex}"
-            );
-        }
-        info!(uri, "hooks.pre_seed: user SHA-256 verified");
-    }
-
     if Instant::now() >= deadline {
         anyhow::bail!("hooks.pre_seed: timed out after download for {uri}");
     }
@@ -437,16 +415,6 @@ mod tests {
         assert!(run(&cfg).await.is_err());
     }
 
-    #[tokio::test]
-    async fn run_sha256s_length_mismatch() {
-        let cfg = PreSeedConfig {
-            sources: vec!["s3://b/k.zip".into()],
-            sha256s: vec!["abc".into(), "def".into()],
-            ..Default::default()
-        };
-        assert!(run(&cfg).await.is_err());
-    }
-
     #[test]
     fn default_has_correct_values() {
         let cfg = PreSeedConfig::default();
diff --git a/docs/config-reference.md b/docs/config-reference.md
index 97b74f21d..2c8ba482b 100644
--- a/docs/config-reference.md
+++ b/docs/config-reference.md
@@ -250,7 +250,6 @@ Downloads and extracts zip archives from S3 before `pre_boot`. Seeds the agent e
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | `sources` | string[] | `[]` | S3 URIs of zip archives (`s3://bucket/key.zip`). Max 5. Extracted in order; later layers overwrite earlier ones. |
-| `sha256s` | string[] | `[]` | SHA-256 checksums per source (same order). If provided, must match sources length. |
 | `target` | string | `$HOME` | Extraction target directory. |
 | `max_bytes` | u64 | `104857600` | Max compressed zip size in bytes (100 MiB). Rejects downloads exceeding this. |
 | `timeout_seconds` | u64 | `300` | Per-source download+extract timeout in seconds. |
@@ -261,6 +260,8 @@ Downloads and extracts zip archives from S3 before `pre_boot`. Seeds the agent e
 **Credential resolution** uses the standard AWS provider chain (same as `config-s3` and `secrets-aws`):
 environment variables, shared credentials, IRSA / EKS Pod Identity, ECS task role.
 
+**Integrity verification:** If S3 objects are uploaded with `--checksum-algorithm SHA256`, OpenAB automatically verifies the checksum on download. No config needed — see [hooks.md](hooks.md) for details.
+
 ```toml
 [hooks.pre_seed]
 sources = [
@@ -268,11 +269,6 @@ sources = [
   "s3://my-bucket/shared-memory.zip",
   "s3://my-bucket/agent-overrides.zip",
 ]
-sha256s = [
-  "a1b2c3d4...",
-  "e5f67890...",
-  "abcdef12...",
-]
 timeout_seconds = 300
 on_failure = "abort"
 ```
diff --git a/docs/hooks.md b/docs/hooks.md
index 14b7907cd..db1961a5d 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -29,11 +29,6 @@ sources = [
   "s3://my-bucket/shared-memory.zip",
   "s3://my-bucket/agent-overrides.zip",
 ]
-sha256s = [
-  "a1b2c3d4e5f6...",
-  "789abcdef012...",
-  "345678901234...",
-]
 # target = "/home/agent"                  # default: $HOME
 # max_bytes = 104857600                   # max compressed size per zip (default: 100 MiB)
 # timeout_seconds = 300                   # per-source timeout (default: 300)
@@ -47,7 +42,6 @@ sha256s = [
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `sources` | string[] | `[]` | S3 URIs of zip archives. Max 5. Extracted in order. |
-| `sha256s` | string[] | `[]` | SHA-256 checksums per source (same order). If provided, must match sources length. |
 | `target` | string | `$HOME` | Extraction target directory. |
 | `max_bytes` | u64 | `104857600` | Max compressed zip size in bytes (100 MiB). |
 | `timeout_seconds` | u64 | `300` | Per-source download+extract timeout. |