pika-cloud-arbitrary-guest-config-spike

A new workspace crate pika-incus-guest-role is added with zero external dependencies beyond serde/serde_json.

The central type is:

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum IncusGuestRole {
    ManagedOpenclaw,
    PikaciRunner,
}

Key helpers:

• as_str() — canonical kebab-case identifier (managed-openclaw, pikaci-runner).
• default_image_alias() — the Incus alias each role resolves to when no override is given (pika-agent/dev, pikaci/dev).
• uses_default_image_alias(alias) — returns true only when the active alias matches the role default (used later to decide whether to record the role in metadata).
• flake_package_attr() — the Nix flake package name for the image.
• FromStr — strict parse that rejects unknown strings.

Unit tests pin serde round-trip, alias mapping, and whitespace tolerance.

The pika-managed-agent-contract crate re-exports IncusGuestRole and adds an optional guest_role field to IncusProvisionParams. The field is Option<IncusGuestRole> and serializes only when Some, preserving backward compatibility with existing JSON payloads.

The existing round-trip test is updated to set guest_role: Some(IncusGuestRole::ManagedOpenclaw).

Several interconnected changes propagate the role through CI pipelines:

1. IncusRuntimeConfig gains a guest_role: IncusGuestRole field, set to PikaciRunner for all CI targets (crates/pikaci/src/targets.rs).

2. RemoteIncusContext stores the role and exposes recorded_guest_role(), which returns Some(role) only when the image alias hasn't been overridden (custom aliases suppress the role to avoid misattribution).

3. remote_linux_vm_incus_guest_role() resolves the role from either the PIKACI_REMOTE_LINUX_VM_INCUS_GUEST_ROLE env var or the job's JobRuntimeConfig::Incus config. An invalid env value produces a clear error.

4. remote_linux_vm_incus_image_alias() now accepts a guest_role parameter and falls back to guest_role.default_image_alias() instead of the old REMOTE_LINUX_VM_INCUS_IMAGE_ALIAS_DEFAULT constant (which is deleted).

5. RemoteLinuxVmImageRecord gains an optional guest_role field with #[serde(alias = "role")] for forward compatibility.

6. load_remote_incus_image_record() populates guest_role via recorded_guest_role().

New tests cover: canonical vs. custom alias recording, invalid env rejection, and legacy JSON deserialization with/without the guest_role key (including the role alias).

On the server side:

1. ResolvedIncusParams adds a non-optional guest_role: IncusGuestRole field.

2. default_incus_params_from_env() now returns anyhow::Result and reads PIKA_AGENT_INCUS_GUEST_ROLE via the new incus_guest_role_from_env() helper. Invalid values produce an actionable error message.

3. resolved_incus_params() merges the guest role from env defaults and the caller's request, then asserts guest_role == ManagedOpenclaw (the only role the managed runtime currently supports). The image alias falls back to guest_role.default_image_alias() instead of requiring it from the env.

4. materialized_guest_role() mirrors the CI pattern — the role is included in materialized params only when the image alias matches the role's default.

5. merge_incus_provision_params() and incus_params_provided() now account for the guest_role field.

6. Instance creation stamps user.pika.guest_role into the Incus instance config when a role is materialized.

7. agent_api_healthcheck() propagates the ? from the now-fallible default_incus_params_from_env().

New tests verify: role preservation in materialized params, role omission for custom aliases, and rejection of invalid env values.

The CLI does not yet expose a way to select a guest role, so guest_role is set to None in both the production path and the test fixture. This means the server will apply its own default (currently ManagedOpenclaw).

Previously, flake.nix contained two nearly identical 40-line blocks to build the managed-agent and CI runner Incus images. This branch replaces them with:

1. nix/incus/guest-image-package.nix — A function that takes { system, name, packageName, description, variant, diskSize, modules, specialArgs, buildInstructions, importInstructions } and produces a derivation containing metadata.tar.xz, disk.qcow2, and a README.txt.

2. nix/incus/roles.nix — A declarative attrset mapping role IDs to their image parameters (system, package attr, default alias, disk size, NixOS modules, etc.).

3. flake.nix — Defines mkIncusGuestRoleImagePkg which composes the two, then exports:

   • managed-openclaw-incus-image and pikaci-runner-incus-image as the canonical package names.
   • pika-agent-incus-dev-image and pikaci-incus-dev-image as backward-compatible aliases pointing to the same derivations.

A new scripts/incus-role-image.sh accepts --role ROLE before the subcommand and resolves the alias and Nix package attribute from the role name. It supports build, import, and build-import subcommands, same as before.

Notable improvement: build-import now uses git ls-files -co --exclude-standard -z | tar instead of git archive, which includes untracked (but non-ignored) files — useful when building from a dirty working tree.

The legacy scripts incus-dev-image.sh and pikaci-incus-image.sh become one-liner exec wrappers that delegate to the new script with the appropriate --role flag.

The NixOS module pika-server.nix gains an optional incusGuestRole parameter. When set, it emits PIKA_AGENT_INCUS_GUEST_ROLE into the systemd environment. incusImageAlias becomes optional and is emitted only when explicitly provided — the server's Rust code now derives the alias from the guest role.

The assertion that previously required incusImageAlias is relaxed accordingly.

The production host config (pika-server.nix) switches from incusImageAlias = "pika-agent/dev" to incusGuestRole = "managed-openclaw", which resolves to the same alias via IncusGuestRole::default_image_alias().

• pika-git web tests add guest_role: None to the RemoteLinuxVmImageRecord fixture.
• pikaci adds the pika-incus-guest-role dependency and sets guest_role: IncusGuestRole::PikaciRunner on all CI target runtime configs, since CI jobs always run in the pikaci-runner role.