pika-orch-incus-cleanup-5

The branch removes ~300 lines of transfer-mode infrastructure:

1. RemoteLinuxVmIncusMode enum deleted — The Transfer / SingleHostShared distinction is gone. The PIKACI_REMOTE_LINUX_VM_INCUS_MODE environment variable and its parsing are removed.

2. Transfer-only functions deleted — import_remote_incus_closures, import_remote_path_closure_into_incus, stage_snapshot_into_incus_guest, finalize_remote_incus_transfer_workspace, and build_remote_incus_transfer_workspace_finalize_command are all removed.

3. prepare_remote_incus_guest_filesystem and build_remote_incus_prepare_script deleted — The entire guest filesystem preparation script that was dynamically generated and executed via incus exec ... bash -lc is gone. This script previously created directories, symlinks, user ownership, environment variables, and the /usr/local/bin/pikaci-incus-run wrapper inside the guest.

4. ensure_remote_incus_runtime simplified — After creating and starting the instance, the function now only waits for the instance to become ready. Device configuration (configure_remote_incus_devices, renamed from configure_remote_incus_single_host_shared_devices) is called unconditionally.

5. RemoteLinuxVmContext slimmed — The incus_mode and remote_incus_closure_dir fields are removed, and ensure_remote_linux_vm_directories creates one fewer remote directory.

6. Mount paths renamed — Constants like REMOTE_LINUX_VM_INCUS_SHARED_SNAPSHOT_MOUNT_PATH become REMOTE_LINUX_VM_INCUS_SNAPSHOT_MOUNT_PATH (dropping the SHARED infix), and their values change from /mnt/pikaci-* to /workspace/snapshot and /staged/linux-rust/* — matching what the NixOS image provides natively.

Previously build_remote_incus_launch_command invoked /usr/local/bin/pikaci-incus-run — a script generated at runtime by build_remote_incus_prepare_script and pushed into the guest via incus exec. Now:

• build_remote_incus_launch_command takes a &JobSpec parameter and compiles the guest command itself.
• The incus exec invocation uses env to set three variables (PIKACI_INCUS_GUEST_COMMAND, PIKACI_INCUS_TIMEOUT_SECS, PIKACI_INCUS_RUN_AS_ROOT) before invoking /run/current-system/sw/bin/pikaci-incus-run.
• The constant REMOTE_LINUX_VM_INCUS_RUN_BINARY points to the NixOS system path.

The corresponding Nix image definition (nix/incus/pikaci-image.nix) is updated to include a pikaci-incus-run script in the VM's system packages that reads these environment variables and handles directory setup, logging, user switching, and exit-code propagation — all responsibilities previously handled by the injected script.

A new RemoteLinuxVmImageRecord struct is added to model.rs:

pub struct RemoteLinuxVmImageRecord {
    pub project: String,
    pub alias: String,
    pub fingerprint: Option<String>,
}

This is populated by load_remote_incus_image_record, which runs sudo incus image show --project <project> <alias> --format json on the remote host, deserializes the fingerprint, and logs it. The RemoteLinuxVmPhaseRecorder gains a set_incus_image method, and the resulting RemoteLinuxVmExecutionRecord now carries the optional incus_image field. This means every Incus-based CI job's run record includes the exact image fingerprint that was used.

The new pikaci_state_root function in forge.rs computes a deterministic, filesystem-safe path derived from the repo slug:

<canonical_git_dir>/../pikaci-state/<sanitized-repo-name>/

Characters outside [a-zA-Z0-9_-] are replaced with -. When the forge CI runner detects a structured pikaci target, it:

1. Computes the state root path.
2. Creates the directory (fs::create_dir_all).
3. Sets the PIKACI_STATE_ROOT environment variable on the child process.

The pikaci executor (running as the child) uses this variable to persist runs/<run_id>/run.json, per-job log files, and prepared-outputs.json into this directory. The test script in the integration test is also updated to write these fixtures into $PIKACI_STATE_ROOT.

The pikaci crate's public API is extended with several items:

New types:

• RunLogsMetadata — contains a list of RunJobLogMetadata entries, each indicating whether host/guest logs exist and their sizes.
• Logs — holds optional host and guest strings with actual log content.
• LogKind — enum (Host, Guest, Both) controlling which logs to load.
• PreparedOutputsRecord — deserialized from prepared-outputs.json.

New functions in run.rs:

• load_run_record(state_root, run_id) — reads and deserializes runs/<run_id>/run.json.
• load_logs_metadata(state_root, run_id, job_id) — scans the run's job directories and reports which log files exist.
• load_logs(state_root, run_id, job_id, kind) — reads actual log file contents.
• load_prepared_outputs_record(state_root, run_id) — reads prepared-outputs.json if the run record references one.

All functions take the state_root path (from pikaci_state_root) and a run ID, keeping the file layout knowledge encapsulated in the pikaci crate.

Three new GET endpoints are registered on the Axum router:

All three require authentication (require_auth). The logs endpoint accepts optional job and kind query parameters via ForgePikaciLogsQuery.

Each handler delegates to a thin helper (load_pikaci_run, load_pikaci_logs, load_pikaci_prepared_outputs) that resolves the forge repo config, computes the state root, and calls the corresponding pikaci library function. Errors return 404 with a JSON error body.

The ForgeBranchLogsResponse struct gains three new optional fields: pikaci_run, pikaci_log_metadata, and pikaci_prepared_outputs. In api_forge_branch_logs_handler, when the lane has a pikaci_run_id, the code calls load_pikaci_run_bundle which loads all three pieces of data in one shot. The bundle loader treats prepared outputs as best-effort (uses .ok().flatten()) — if the file doesn't exist, the field is simply None.

This is a backward-compatible enrichment: existing API consumers that don't use these fields are unaffected, while new consumers get detailed pikaci execution metadata without extra round-trips.

The branch title references "make payload metadata best-effort," and this manifests in the model layer:

• RemoteLinuxVmExecutionRecord gains an incus_image: Option<RemoteLinuxVmImageRecord> field — old records without this field deserialize cleanly as None.
• RemoteLinuxVmImageRecord.fingerprint is Option<String> — if the image query fails or is skipped, the record still serializes.
• The RunRecord type uses serde(default) on new fields so that run.json files from before this change remain loadable.
• The PreparedOutputsRecord loading is wrapped in .ok().flatten() at the call site, treating it as entirely optional.

This defensive approach prevents the system from failing hard when metadata files are incomplete or from a previous version.

The pikaci-image.nix derivation is updated to include a pikaci-incus-run script (or binary) in the NixOS system's PATH at /run/current-system/sw/bin/pikaci-incus-run. This script reads the environment variables set by the host-side launch command (PIKACI_INCUS_GUEST_COMMAND, PIKACI_INCUS_TIMEOUT_SECS, PIKACI_INCUS_RUN_AS_ROOT) and handles:

• Creating workspace directories (/workspace, /artifacts, /cargo-home, /cargo-target)
• Setting up logging (tee -a /artifacts/guest.log)
• Configuring environment variables (CARGO_HOME, CARGO_TARGET_DIR, SSL_CERT_FILE, etc.)
• Running as root or switching to the pikaci user via runuser
• Writing result.json with status, exit code, and timestamp

This moves guest-side logic from dynamically-generated shell code to a versioned, testable NixOS component.

The linux-rust.nix CI expression is updated to reflect the removal of transfer-mode support and any changes to how the Incus backend is configured. This ensures that the Nix-based CI pipeline definition stays in sync with the executor changes — for example, removing references to the now-deleted PIKACI_REMOTE_LINUX_VM_INCUS_MODE variable or updating paths to match the new mount point conventions.

The test suite is substantially expanded:

forge.rs tests:

• The existing integration test now writes pikaci state fixtures (run.json, host.log, guest.log) into $PIKACI_STATE_ROOT and asserts they exist after the CI command completes.

web.rs tests:

• api_forge_branch_logs_includes_persisted_pikaci_run_metadata — Sets up a branch with a completed pikaci lane, writes fixtures, and asserts the logs API response includes pikaci_run, pikaci_log_metadata, and pikaci_prepared_outputs.
• api_forge_pikaci_handlers_load_persisted_run_and_logs — Tests the standalone run and logs endpoints, verifying JSON structure and log content.
• api_forge_pikaci_prepared_outputs_handler_loads_persisted_record — Tests the prepared-outputs endpoint.
• Helper functions forge_test_config_with_git_dir and write_pikaci_run_fixture create realistic test fixtures.

executor.rs tests:

• The with_incus_mode_env test helper and all transfer-mode-specific tests are removed.
• sample_remote_context and sample_shell_job helpers are introduced, simplifying the remaining test setup by removing the now-deleted incus_mode and remote_incus_closure_dir fields.
• Launch command tests are updated to verify that PIKACI_INCUS_GUEST_COMMAND, PIKACI_INCUS_TIMEOUT_SECS, and PIKACI_INCUS_RUN_AS_ROOT appear in the generated command.

A new docs/incus-migration-plan.md file is added to the repository, documenting the rationale and plan for the Incus executor cleanup. This serves as a design record for the changes in this branch — explaining why the transfer mode was removed, the benefits of the shared-device approach, and any migration considerations for existing deployments.