refactor: fold scaffolding-only crates and collapse duplicate enums (#10597)

* refactor(cli): collapse the duplicate command-family and stdout-mode enums

CommandDispatchFamily was a byte-identical twin of CommandJsonFamily joined
by an identity From impl, and CommandStdoutMode was a twin of
CommandResponseMode differing only in the name of one variant. Both pairs
encoded one concept under two types, forcing an identity conversion at every
boundary.

Delete both duplicates. The exported contract JSON is unchanged: json_family
and dispatch_family were equal for every command by construction and still
are, and response_mode/stdout_mode keep their distinct spellings (json vs
json_envelope) by rendering the one enum through two functions. Two tests
lock that wire shape.

Also drops CommandSpec::dispatch_family and the never-called
registered_command_dispatch_family, both of which became literal aliases.

Refs #10295

* refactor: fold four scaffolding-only crates into their single consumers

43 workspace members -> 39.

homeboy-output (714 LOC) and homeboy-process (1332 LOC) were leaf crates with
exactly one and two dependents. Core re-exported both wholesale, so every call
site already spelled them crate::output:: / crate::process:: and no import
churn was needed. Neither is depended on by anything below core, so folding
them in cannot reintroduce a cycle: homeboy-output has no internal
dependencies at all, and homeboy-process depends only on homeboy-error, which
core already depends on.

homeboy-cli-contract (41 LOC: Placement) and homeboy-agents-contract (45 LOC:
AgentTaskProviderRunnerSource) each held one type. Both move into
homeboy-lab-runner-contract, which is already the below-core home for
behavior-free runner contracts and is already a dependency of every consumer
except homeboy-cli. Placement's stated rationale -- give core a place to name
the type without a core -> commands edge -- holds there unchanged, and every
value Placement takes is a statement about the Lab runner.

Six process items that were only pub to cross the old crate boundary
(SIGNAL_TERMINATE, SIGNAL_KILL, signal_pid, wait_for_pid_exit,
pid_has_ownership_token, terminate_pid_with_sigterm_and_wait) narrow back to
pub(crate); all six are consumed only by core's daemon module.

Adds the first tests either folded contract type has had: Placement's
operator-facing --placement value names and routing predicates, and the
provider source-root wire shape (optional fields stay optional, unknown keys
land in extra).

Refs #10296

* refactor(process): drop dead terminate_process_tree_best_effort

Zero callers across the workspace (verified with grep -rn plus a control
grep). Superseded by the timeout-bounded owned-tree termination below it.

* build: drop the folded crates from Cargo.lock

CI passes --locked, so a stale lock fails every gate before compilation.
Regenerated with cargo metadata (resolve only, no build): removes the
four folded packages and repoints homeboy-lab-runner-contract. No
version bumps.

---------

Co-authored-by: chubes-bot <266378653+homeboy-ci[bot]@users.noreply.github.com>

Author: chubes4

Cargo.lock

@@ -4,7 +4,7 @@ version = "0.1.0"
 edition = "2021"
 license = "MIT"
 authors = ["Chris Huber <chubes@extrachill.com>"]
-description = "Shared runner contract types + env-var constants for homeboy. Behavior-free data that both homeboy-core and the optional homeboy-runner feature crate depend on, so core can reference runner concepts without depending on runner behavior."
+description = "Shared runner contract types + env-var constants for homeboy, including the requested execution Placement and the managed provider source-root contract. Behavior-free data that both homeboy-core and the optional homeboy-runner feature crate depend on, so core can reference runner concepts without depending on runner behavior."
 repository = "https://github.com/Extra-Chill/homeboy"
 publish = false
 
@@ -13,5 +13,6 @@ name = "homeboy_lab_runner_contract"
 path = "src/lib.rs"
 
 [dependencies]
+clap = { version = "4.5", features = ["derive", "string"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"

crates/contracts/homeboy-agents-contract/Cargo.toml

@@ -6,6 +6,22 @@
 //! (e.g. the runner kind, or the env-var markers used when an exec crosses a
 //! remote-runner boundary). Those plain-data contracts live here so core can
 //! reference them without a `core -> runner` edge.
+//!
+//! Two single-type crates were folded in here for the same reason they existed
+//! separately — both are behavior-free runner contracts below core, and both
+//! were already depended on by a subset of this crate's dependents:
+//!
+//! - [`Placement`] (was `homeboy-cli-contract`): the requested execution
+//!   location, read by core's Lab routing and by the runner's Lab selection.
+//! - [`AgentTaskProviderRunnerSource`] (was `homeboy-agents-contract`): a
+//!   managed source checkout homeboy keeps synced on the runner, read by core's
+//!   agent-runtime manifest and by `homeboy-agents`.
+
+mod placement;
+mod provider_source_types;
+
+pub use placement::Placement;
+pub use provider_source_types::AgentTaskProviderRunnerSource;
 
 use std::collections::{BTreeMap, BTreeSet};
 

crates/contracts/homeboy-agents-contract/src/lib.rs

@@ -0,0 +1,103 @@
+//! Requested execution placement.
+//!
+//! [`Placement`] sits at the boundary between the CLI argument surface and core
+//! Lab routing. It lives below core, in this crate rather than in the CLI, so
+//! `core` can name it without depending on the full `commands`/clap CLI
+//! definition (which would create a `core -> commands` dependency edge).
+//!
+//! It belongs with the rest of the runner contract because every value it takes
+//! is a statement about the Lab runner: whether to attempt an offload, and
+//! whether controller execution is an acceptable fallback.
+
+use clap::ValueEnum;
+use serde::{Deserialize, Serialize};
+
+/// The requested execution location. This is normalized once at the CLI
+/// boundary and is the only placement input used by routing code.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum, Serialize, Deserialize)]
+#[value(rename_all = "lower")]
+pub enum Placement {
+    Auto,
+    Local,
+    Lab,
+    #[value(name = "lab-or-local")]
+    LabOrLocal,
+}
+
+impl Default for Placement {
+    fn default() -> Self {
+        Self::Auto
+    }
+}
+
+impl Placement {
+    /// Explicitly permit controller execution when an intended Lab offload
+    /// cannot proceed. `Auto` retains the existing default routing behavior.
+    pub const fn allows_local_fallback(self) -> bool {
+        matches!(self, Self::LabOrLocal)
+    }
+
+    /// Whether the operator requested a Lab attempt instead of leaving the
+    /// command to its automatic routing policy.
+    pub const fn requests_lab(self) -> bool {
+        matches!(self, Self::Lab | Self::LabOrLocal)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// `--placement <value>` is an operator-facing surface: the accepted
+    /// spellings are part of the CLI contract, not an implementation detail of
+    /// whichever crate happens to hold the enum. Asserted here so relocating
+    /// the type cannot quietly rename a flag value.
+    #[test]
+    fn placement_keeps_its_operator_facing_value_names() {
+        let names: Vec<String> = Placement::value_variants()
+            .iter()
+            .map(|variant| {
+                variant
+                    .to_possible_value()
+                    .expect("every placement variant is selectable")
+                    .get_name()
+                    .to_string()
+            })
+            .collect();
+
+        assert_eq!(names, ["auto", "local", "lab", "lab-or-local"]);
+    }
+
+    #[test]
+    fn placement_defaults_to_auto_routing() {
+        assert_eq!(Placement::default(), Placement::Auto);
+        assert!(!Placement::default().requests_lab());
+        assert!(!Placement::default().allows_local_fallback());
+    }
+
+    /// Only `lab-or-local` both requests a Lab attempt and permits falling back
+    /// to the controller; `lab` requests without permitting, and `local`/`auto`
+    /// do neither.
+    #[test]
+    fn only_lab_or_local_both_requests_lab_and_permits_local_fallback() {
+        let matrix = [
+            (Placement::Auto, false, false),
+            (Placement::Local, false, false),
+            (Placement::Lab, true, false),
+            (Placement::LabOrLocal, true, true),
+        ];
+
+        for (placement, requests_lab, allows_fallback) in matrix {
+            assert_eq!(
+                placement.requests_lab(),
+                requests_lab,
+                "{placement:?} requests_lab"
+            );
+            assert_eq!(
+                placement.allows_local_fallback(),
+                allows_fallback,
+                "{placement:?} allows_local_fallback"
+            );
+        }
+    }
+}