sarusctl: Distinguish negative Parallax image checks from --exist invocation failures

[Madeeks]

sarusctl currently treats every nonzero exit from parallax --exist as confirmation that an image is absent. This makes command-
line misuse, unsupported Parallax versions, and internal Parallax failures indistinguishable from a valid negative result.

Before #25, this was exposed by the smoke test in test/smoke/30_annotations_sarusctl.bats. The CI environment used Parallax 0.10.1, while
--exist was introduced in 0.10.3. The unsupported option returned a nonzero status, which was interpreted as false, eventually
producing:

Pulling busybox:latest with Podman...
Migrating busybox:latest with Parallax...
Image busybox:latest is still missing after migration

The message incorrectly suggests that migration completed but failed to store the image. The actual problem was that the
verification command itself was invalid for the installed Parallax version.

Current behavior

parallax_exist() in crates/podman-driver/src/lib.rs executes the command and reduces its result to:

Ok(output.status.success())

Consequently:

Process result	Returned result
Exit code 0	Ok(true)
Image genuinely absent	Ok(false)
Unsupported --exist option	Ok(false)
Invalid arguments	Ok(false)
Parallax runtime failure	Ok(false)
Executable cannot be started	Err(...)

The exit code and stderr are discarded for every successfully spawned process.

sarusctl therefore cannot distinguish a valid negative result from an execution failure. After migration, either condition is
reported as:

Image is still missing after migration

Expected behavior

A valid negative existence check should remain distinct from an unsuccessful check.

Examples:

Image busybox:latest is still missing after migration

should be used only when Parallax successfully checked the store and confirmed that the image is absent.

Invocation or compatibility failures should instead produce a runtime error containing the relevant context, for example:

Configured Parallax 0.10.1 does not support --exist; version 0.10.3 or newer is required

or:

parallax --exist failed for busybox:latest with exit code 2: unknown option --exist

Possible approach

1. Define an explicit exit-status contract for parallax --exist, such as:

   • 0: image exists
   • 1: image does not exist
   • Other exit codes: invocation or runtime failure

2. Update podman-driver to inspect the complete process result rather than calling only status.success().

3. Preserve the exit code and stderr in errors returned to sarusctl.

4. Add a Parallax version or capability check before using --exist. At minimum, sarusctl should report clearly that Parallax
   0.10.3 or newer is required.

5. Consider representing the result explicitly, for example:

   Result<ImagePresence, ParallaxError>

   where ImagePresence is Present or Absent.

If Parallax currently uses the same exit code for “image absent” and argument/runtime errors, its CLI contract or output format
may also need to change before these cases can be reliably distinguished.

Testing

Add coverage for:

• Image exists.
• Image is genuinely absent.
• Parallax does not support --exist.
• Parallax returns an unexpected nonzero exit code.
• Parallax writes diagnostic information to stderr.
• The executable cannot be started.
• Initial image lookup failure is propagated without attempting a pull.
• Post-migration lookup failure is reported as a runtime error rather than “image missing.”

The sarusctl fake runtime currently queues only boolean existence results. It will need to support queued Result<bool, AppError>
values so error propagation can be tested.

Additionally, the podman-driver unit test for commands::parallax() currently needs adjustment because the function now returns
Result<Command, _> while the test treats it as a plain Command.

Related CI configuration

The immediate smoke-test failure can be resolved separately by updating all Parallax defaults to at least 0.10.3:

• .github/workflows/host-tools.yml

  • Reusable workflow default: currently 0.10.1
  • Manual workflow default: currently 0.9.12
  • Cache-key fallback: currently 0.9.12

• scripts/ci/static/build-host-tools-bundle.sh

  • Script fallback: currently 0.10.0

Updating CI fixes the immediate compatibility problem, but this issue should remain open to track robust classification and
reporting of future Parallax command failures.