Ship workflow (Technology Preview)

Ship targets Camel Main at the configured camel.main.version: a -p camel.main.version=…​ override, then the -c file or ~/.camel-kit/config.properties, then the bundled default.

Context is optional: a bare camel-kit ship starts a short discovery conversation. Text and documents are added to the discovery input before any question, and open points come back as grouped unresolved questions.

--resume, --status, --abort, --submit and --start-from are mutually exclusive. Runtime and configuration options apply when starting, resuming or submitting; repeat --stage-timeout, --maven-repository and -c/-p on every resume and submission, because they are not persisted. With --json, a failed workflow returns the run state with exit code 1; some command errors return only stderr.

Unanswered questions and applied defaults are kept per stage and listed in the final summary and in --status; later stages receive them as worker-reported context, not as human-confirmed answers. Under always and smart, answer a paused question with --resume <run-id> --text "…​".

The result of validation is the Stamp: a local run report with a pass or fail status derived from the required checks. For each command it records the executable and its version, the redacted arguments, the exit status and timing, and the retained logs with their digests. A failed mandatory check fails the run under every policy; there is no waiver. The Stamp describes what ran on this machine and is not a signed attestation.

Run state lives under .camel-kit/ship/state/ in the project, or under CAMEL_KIT_SHIP_STATE_HOME. The .camel-kit/ship/ subtree is reserved for the controller: never copied into the staged workspace, never part of the staleness digests, never published, and ignored by its own .gitignore. Git discovery stops at the staged workspace, so commands run by the execute worker or by validation do not see the project’s repository; for that reason project and state paths containing a colon are rejected. Runs recorded by pre-0.4.0 development builds under the user state directory are found only when CAMEL_KIT_SHIP_STATE_HOME points there.

Each run prints its ID. --status shows the stage, the policy, any pause report and the next actionable command. --resume re-reads the recorded inputs and artifacts, compares their digests, and restarts the earliest stale or incomplete stage; later stages are reset, so your own edits are detected rather than ignored. Context can be added only to a paused run; adding it after validation restarts from discovery and discards the Stamp, with a warning first.

--start-from design needs text or document context and a manual active pipeline in .camel-kit/pipeline.json; --start-from plan also imports that pipeline’s approved design-spec.md. Existing plans, execution reports and validation reports cannot be imported, and starting from execute or validate is unsupported because those stages need the controller’s own plan and evidence.

Accepted changes reach the live project only after the configured approval and validation gates. Before applying anything the controller re-verifies every completed stage as recorded and checks that the live tree has not changed; a changed tree stops publication and asks you to resume. The apply is journaled: if it is interrupted, the next locked mutating operation attempts a rollback first, and may stop for manual resolution. Ordinary process interruption is recoverable with the run ID; OS or power loss is not guaranteed against, and the invoking OS account is trusted.

With the Pi backend, Ship runs an external Pi worker. Eligible IBM Bob 2, GitHub Copilot CLI, Claude Code and Google Antigravity and Qwen Code sessions can instead relay the controller’s stage tasks to their own read-only native subagents; OpenAI Codex CLI joins them in the development snapshot. The contract is the same for every host:

The skill selects the native backend for an eligible new run unless you choose one explicitly; when native dispatch is unavailable, a new run keeps the Pi model, and an existing run keeps its recorded backend for its lifetime: hosts never switch during recovery. Native stages use the active session’s authentication and model; Camel Kit starts no second host process and does not look for Pi or Node. Host versions are caller-reported diagnostics, not a certification.

A fresh context is not an OS sandbox: read access follows the parent’s permitted paths. Do not broaden permissions, add directories or substitute another role when a task cannot reach its inputs.

Recovery is shared. After an interruption inspect --status --json, wait for a still-running child or submit its saved response, and never dispatch the same pending task twice. A task keeps its deadline; --resume after expiry fails that attempt and a second explicit resume issues a new task. handoff-read-failed means the pending task could not be verified: resume once to record the failure, then resume again for a fresh task, without editing the stored evidence. Ship cannot stop a host-owned child; use the host’s cancellation controls, and --abort invalidates the run and rejects late results. Failed runs return JSON with exit code 1 and run.message; stop after any command error, including stale-stage-input or a permission denial, and wait for a new instruction.

Workspaces generated before the controller-owned Ship must be regenerated with the same agent and command surface (camel-kit init --here --ai <same-agent> --force, after backing up customizations). Re-initialization installs the current entry point and removes the obsolete prompt-owned Ship guides. A pre-controller .camel-kit/ship-state.json, or a .camel-kit/pipeline.json not in manual mode, makes Ship fail closed: archive it outside the project first.

Maintainers run the Pi live gate manually with the linux-ship-certification Maven profile and the CAMEL_KIT_SHIP_LIVE_PI and CAMEL_KIT_SHIP_LIVE_NODE variables; it is not part of CI and not something users run.