feat: Add worktree support for scheduled agents with validation

crates/pu-cli/assets/SKILL.md

@@ -85,16 +85,29 @@ pu schedule list                   # list all schedules
 pu schedule list --json            # machine-readable
 pu schedule show <name>            # show schedule details
 pu schedule show <name> --json     # machine-readable
-pu schedule create <name> \
-  --start-at "2026-03-07T14:00:00Z" \
-  --recurrence none \
+
+# Worktree spawn (default) — needs --name
+pu schedule create overnight-build \
+  --start-at "2026-03-07T22:30:00" \
+  --name overnight-build \
+  --trigger inline-prompt \
+  --trigger-prompt "build a feature"   # spawns in worktree pu/overnight-build
+
+# Root spawn — for read-only/cross-project tasks
+pu schedule create morning-status \
+  --start-at "2026-03-07T08:00:00" \
+  --root \
   --trigger inline-prompt \
-  --trigger-prompt "do the thing"  # one-shot scheduled agent
-pu schedule create <name> \
-  --start-at "2026-03-07T14:00:00Z" \
+  --trigger-prompt "scan commits"      # spawns in project root
+
+# Recurring with agent def
+pu schedule create nightly-review \
+  --start-at "2026-03-07T03:00:00" \
   --recurrence daily \
+  --root \
   --trigger agent-def \
-  --trigger-name my-agent          # recurring from saved agent def
+  --trigger-name security-review       # recurring root agent from saved def
+
 pu schedule enable <name>          # enable a disabled schedule
 pu schedule disable <name>         # disable without deleting
 pu schedule delete <name>          # remove a schedule
@@ -104,6 +117,8 @@ pu schedule delete <name>          # remove a schedule
 
 **Trigger types**: `inline-prompt` (with `--trigger-prompt`), `agent-def` (with `--trigger-name`), `swarm-def` (with `--trigger-name`).
 
+**Spawn mode**: By default, scheduled agents spawn into a worktree (requires `--name`). Use `--root` to spawn in the project root instead (for read-only or cross-project tasks).
+
 **Scope**: `--scope local` (default, project-level) or `--scope global`.
 
 ### Other

crates/pu-cli/src/commands/schedule.rs

@@ -30,11 +30,25 @@ pub async fn run_create(
     agent: &str,
     vars: Vec<String>,
     scope: &str,
+    root: bool,
+    agent_name: Option<String>,
     json: bool,
 ) -> Result<(), CliError> {
     daemon_ctrl::ensure_daemon(socket).await?;
     let project_root = commands::cwd_string()?;
 
+    // Validate: --name is required when not --root, and mutually exclusive with --root
+    if !root && agent_name.is_none() {
+        return Err(CliError::Other(
+            "--name is required when not using --root".into(),
+        ));
+    }
+    if root && agent_name.is_some() {
+        return Err(CliError::Other(
+            "--root and --name are mutually exclusive".into(),
+        ));
+    }
+
     let start_at_dt = parse_datetime(start_at)?;
 
     let trigger = match trigger_type {
@@ -77,6 +91,8 @@ pub async fn run_create(
             trigger,
             target: String::new(),
             scope: scope.to_string(),
+            root,
+            agent_name,
         },
     )
     .await?;

crates/pu-cli/src/main.rs

@@ -418,6 +418,12 @@ enum ScheduleAction {
         /// Scope: local or global
         #[arg(long, default_value = "local")]
         scope: String,
+        /// Spawn as root agent (in project root, not a worktree)
+        #[arg(long)]
+        root: bool,
+        /// Worktree/branch name (required when not --root)
+        #[arg(long = "name")]
+        agent_name: Option<String>,
         /// Output as JSON
         #[arg(long)]
         json: bool,
@@ -632,6 +638,8 @@ async fn main() {
                 agent,
                 vars,
                 scope,
+                root,
+                agent_name,
                 json,
             } => {
                 commands::schedule::run_create(
@@ -645,6 +653,8 @@ async fn main() {
                     &agent,
                     vars,
                     &scope,
+                    root,
+                    agent_name,
                     json,
                 )
                 .await

crates/pu-cli/src/output.rs

@@ -466,11 +466,17 @@ pub fn print_response(response: &Response, json_mode: bool) {
             next_run,
             trigger,
             scope,
+            root,
+            agent_name,
             ..
         } => {
             println!("{} ({})", name.bold(), scope.dimmed());
             println!("  Enabled:    {enabled}");
             println!("  Recurrence: {recurrence}");
+            println!("  Root:       {root}");
+            if let Some(an) = agent_name {
+                println!("  Agent name: {an}");
+            }
             println!("  Start at:   {}", start_at.format("%Y-%m-%d %H:%M UTC"));
             if let Some(nr) = next_run {
                 println!("  Next run:   {}", nr.format("%Y-%m-%d %H:%M UTC"));
@@ -898,6 +904,8 @@ mod tests {
                 project_root: "/test".into(),
                 target: String::new(),
                 scope: "local".into(),
+                root: true,
+                agent_name: None,
                 created_at: chrono::Utc::now(),
             }],
         };
@@ -925,6 +933,8 @@ mod tests {
             project_root: "/test".into(),
             target: String::new(),
             scope: "local".into(),
+            root: true,
+            agent_name: None,
             created_at: chrono::Utc::now(),
         };
         print_response(&resp, false);

crates/pu-core/src/protocol.rs

@@ -226,6 +226,10 @@ pub enum Request {
         #[serde(default)]
         target: String,
         scope: String,
+        #[serde(default = "crate::serde_defaults::default_true")]
+        root: bool,
+        #[serde(default)]
+        agent_name: Option<String>,
     },
     DeleteSchedule {
         project_root: String,
@@ -342,6 +346,10 @@ pub struct ScheduleInfo {
     pub project_root: String,
     pub target: String,
     pub scope: String,
+    #[serde(default = "crate::serde_defaults::default_true")]
+    pub root: bool,
+    #[serde(default)]
+    pub agent_name: Option<String>,
     pub created_at: DateTime<Utc>,
 }
 
@@ -513,6 +521,10 @@ pub enum Response {
         project_root: String,
         target: String,
         scope: String,
+        #[serde(default = "crate::serde_defaults::default_true")]
+        root: bool,
+        #[serde(default)]
+        agent_name: Option<String>,
         created_at: DateTime<Utc>,
     },
     DiffResult {
@@ -1939,6 +1951,8 @@ mod tests {
             },
             target: String::new(),
             scope: "local".into(),
+            root: true,
+            agent_name: None,
         };
         let json = serde_json::to_string(&req).unwrap();
         let parsed: Request = serde_json::from_str(&json).unwrap();
@@ -2014,6 +2028,8 @@ mod tests {
                 project_root: "/test".into(),
                 target: String::new(),
                 scope: "local".into(),
+                root: true,
+                agent_name: None,
                 created_at: Utc::now(),
             }],
         };
@@ -2043,6 +2059,8 @@ mod tests {
             project_root: "/test".into(),
             target: String::new(),
             scope: "local".into(),
+            root: false,
+            agent_name: Some("overnight-build".into()),
             created_at: Utc::now(),
         };
         let json = serde_json::to_string(&resp).unwrap();

crates/pu-core/src/schedule_def.rs

@@ -58,12 +58,40 @@ pub struct ScheduleDef {
     pub project_root: String,
     #[serde(default)]
     pub target: String,
+    /// Whether the scheduled agent spawns in the project root (true) or a worktree (false)
+    #[serde(default = "crate::serde_defaults::default_true")]
+    pub root: bool,
+    /// Worktree/branch name when `root` is false
+    #[serde(default)]
+    pub agent_name: Option<String>,
     /// "local" or "global" — set at load time, not serialized
     #[serde(skip)]
     pub scope: String,
     pub created_at: DateTime<Utc>,
 }
 
+impl ScheduleDef {
+    /// Validate that `root` and `agent_name` are consistent:
+    /// - root=true → agent_name must be None
+    /// - root=false → agent_name must be Some(non-empty)
+    pub fn validate(&self) -> Result<(), std::io::Error> {
+        if self.root {
+            if self.agent_name.is_some() {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::InvalidInput,
+                    "agent_name must not be set when root is true",
+                ));
+            }
+        } else if self.agent_name.as_ref().is_none_or(|n| n.is_empty()) {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                "agent_name is required when root is false",
+            ));
+        }
+        Ok(())
+    }
+}
+
 /// Scan both local and global schedule definition directories. Local defs take priority.
 pub fn list_schedule_defs(project_root: &Path) -> Vec<ScheduleDef> {
     let mut seen = HashMap::new();
@@ -111,6 +139,7 @@ pub fn find_schedule_def(project_root: &Path, name: &str) -> Option<ScheduleDef>
 /// Save a schedule definition as a YAML file. Creates the directory if needed.
 pub fn save_schedule_def(dir: &Path, def: &ScheduleDef) -> Result<(), std::io::Error> {
     crate::validation::validate_name(&def.name)?;
+    def.validate()?;
     if def.project_root.is_empty() {
         return Err(std::io::Error::new(
             std::io::ErrorKind::InvalidInput,
@@ -258,6 +287,10 @@ fn scan_dir(dir: &Path, scope: &str) -> Vec<ScheduleDef> {
             if let Ok(content) = std::fs::read_to_string(&path) {
                 match serde_yml::from_str::<ScheduleDef>(&content) {
                     Ok(mut def) => {
+                        if let Err(e) = def.validate() {
+                            eprintln!("warning: invalid schedule {}: {e}", path.display());
+                            continue;
+                        }
                         def.scope = scope.to_string();
                         defs.push(def);
                     }
@@ -277,6 +310,9 @@ fn find_in_dir(dir: &Path, name: &str, scope: &str) -> Option<ScheduleDef> {
     if path.is_file() {
         if let Ok(content) = std::fs::read_to_string(&path) {
             if let Ok(mut def) = serde_yml::from_str::<ScheduleDef>(&content) {
+                if def.validate().is_err() {
+                    return None;
+                }
                 def.scope = scope.to_string();
                 return Some(def);
             }
@@ -308,6 +344,8 @@ mod tests {
             trigger: make_trigger(),
             project_root: "/projects/myapp".to_string(),
             target: String::new(),
+            root: true,
+            agent_name: None,
             scope: String::new(),
             created_at: Utc::now(),
         }
@@ -354,6 +392,77 @@ created_at: "2025-06-01T00:00:00Z"
         assert_eq!(def.recurrence, Recurrence::None); // default none
         assert_eq!(def.target, ""); // default empty
         assert!(def.next_run.is_none()); // default none
+        assert!(def.root); // default true (backward compat)
+        assert!(def.agent_name.is_none()); // default none
+    }
+
+    #[test]
+    fn given_schedule_with_worktree_fields_should_round_trip() {
+        let yaml = r#"
+name: overnight-build
+start_at: "2025-06-01T22:30:00Z"
+trigger:
+  type: inline_prompt
+  prompt: "build a feature"
+project_root: /projects/myapp
+root: false
+agent_name: overnight-build
+created_at: "2025-06-01T00:00:00Z"
+"#;
+        let def: ScheduleDef = serde_yml::from_str(yaml).unwrap();
+        assert!(!def.root);
+        assert_eq!(def.agent_name.as_deref(), Some("overnight-build"));
+
+        // Round-trip through YAML
+        let serialized = serde_yml::to_string(&def).unwrap();
+        let reparsed: ScheduleDef = serde_yml::from_str(&serialized).unwrap();
+        assert!(!reparsed.root);
+        assert_eq!(reparsed.agent_name.as_deref(), Some("overnight-build"));
+    }
+
+    // --- Validation ---
+
+    #[test]
+    fn given_root_true_with_no_agent_name_should_validate() {
+        let def = make_schedule_def("test");
+        assert!(def.validate().is_ok());
+    }
+
+    #[test]
+    fn given_root_true_with_agent_name_should_reject() {
+        let mut def = make_schedule_def("test");
+        def.agent_name = Some("bad".to_string());
+        assert!(def.validate().is_err());
+    }
+
+    #[test]
+    fn given_root_true_with_empty_agent_name_should_reject() {
+        let mut def = make_schedule_def("test");
+        def.agent_name = Some(String::new());
+        assert!(def.validate().is_err());
+    }
+
+    #[test]
+    fn given_root_false_with_agent_name_should_validate() {
+        let mut def = make_schedule_def("test");
+        def.root = false;
+        def.agent_name = Some("my-worktree".to_string());
+        assert!(def.validate().is_ok());
+    }
+
+    #[test]
+    fn given_root_false_with_no_agent_name_should_reject() {
+        let mut def = make_schedule_def("test");
+        def.root = false;
+        assert!(def.validate().is_err());
+    }
+
+    #[test]
+    fn given_root_false_with_empty_agent_name_should_reject() {
+        let mut def = make_schedule_def("test");
+        def.root = false;
+        def.agent_name = Some(String::new());
+        assert!(def.validate().is_err());
     }
 
     #[test]