Struct Controller 

pub struct Controller {
    pub config: Config,
    pub state: State,
}

Fields

config: Config

state: State

Implementations

impl Controller

pub fn session_working_context( &self, session_id: &str, executor: &impl CommandExecutor, ) -> Result<(PathBuf, String)>

Inspect the actual execution checkout in a background worker.

pub fn session_git_status( &self, session_id: &str, executor: &impl CommandExecutor, ) -> Result<SessionGitStatus>

The session checkout’s branch, distance from upstream, and changed files, read with the target’s own git. Builds on Self::session_working_context, so it works wherever that does: a local checkout, a container, or an SSH host.

pub fn resolve_aws_resource_options( &self, target_id: &str, executor: &impl CommandExecutor, ) -> Result<Vec<SessionResourceAllocation>>

pub fn reconnect_command(&self, session_id: &str) -> Result<CommandSpec>

pub fn resource_probe(&self, session_id: &str) -> Result<SessionResourceProbe>

pub fn deployment_capacity_targets(&self) -> Vec<DeploymentCapacityTarget>

pub fn test_target( &self, target_id: &str, executor: &impl CommandExecutor, ) -> Result<()>

The full check behind the Targets pane’s Test action.

pub fn check_target_readiness( &self, target_id: &str, executor: &impl CommandExecutor, ) -> Result<()>

The check a session wizard runs before it offers a target: the same one a launch runs, worded for a launch that has not happened yet.

impl Controller

pub async fn create_recovery_checkpoint_managed_controlled( &self, session_id: &str, manager: &SessionManagerControl, executor: &(impl CommandExecutor + Sync), ) -> Result<CheckpointArtifact>

Create, checksum, and durably install a recovery archive before allowing the relay to garbage-collect through its event frontier.

impl Controller

pub fn session_export_layout( &self, session_id: &str, executor: &(impl CommandExecutor + Sync), ) -> Result<SessionExportLayout>

Where a session’s repositories live on its target, and what each one contributes to an export.

A checkpoint and a diff, a file read or a branch push all need the same answers - which target, which directory, which repository is the primary - so they are derived once here rather than restated wherever a caller reaches the target.

impl Controller

pub async fn checkpoint_session( &mut self, session_id: &str, ) -> Result<CheckpointMetadata>

Materialize and locally verify a complete session checkpoint while the target remains live. A failed export or transfer leaves the previous archive and target untouched.

pub async fn checkpoint_session_controlled( &mut self, session_id: &str, executor: &(impl CommandExecutor + Sync), ) -> Result<CheckpointMetadata>

impl Controller

pub async fn suspend_session(&mut self, session_id: &str) -> Result<()>

Checkpoint, ask the harness to close, and only then tear down the exact provisioned target. Checkpoint failure is deliberately non-destructive, except when the checkpoint’s worker restart left no live worker: that records Error and keeps the target for a later resume or forced close.

pub async fn suspend_session_controlled( &mut self, session_id: &str, executor: &(impl CommandExecutor + Sync), ) -> Result<()>

pub async fn suspend_session_managed_controlled( &mut self, session_id: &str, executor: &(impl CommandExecutor + Sync), manager: &SessionManagerControl, acknowledge_unpublished_work: bool, before_close: Option<BeforeClose>, ) -> Result<bool>

pub async fn recover_interrupted_close_managed( &mut self, session_id: &str, executor: &(impl CommandExecutor + Sync), manager: &SessionManagerControl, acknowledge_unpublished_work: bool, before_close: Option<BeforeClose>, ) -> Result<bool>

Resume the durable closing state after a controller restart. If the relay had accepted Close, wait for it and destroy through the exact installed checkpoint gate. If it had not, take a fresh checkpoint; the previously installed archive may have become stale after EOF released its barrier.

The daemon also closes every live session this way, because it marks the record Closing before the close starts. So the fresh checkpoint’s publication check uses acknowledge_unpublished_work as the caller sent it. A relay already sealed was checked by the close that sealed it, and that close can only go forward.

pub fn fail_interrupted_lifecycle( &mut self, session_id: &str, cause: &str, ) -> Result<bool>

Record that an in-flight lifecycle state has no operation left to finish it, so the session stops waiting for one.

The state is re-checked against the freshly loaded record, because the caller decided what to reconcile from a startup snapshot. Returns whether anything changed.

pub fn fail_unready_session( &mut self, session_id: &str, cause: &str, observed_updated_at: &str, ) -> Result<bool>

Record that a live session’s harness never became usable, so a driver can close it and provision a replacement instead of waiting on a session that will never take a prompt (#1090).

Only a record that still looks exactly as the daemon observed it is failed: a lifecycle operation that started after the observation owns the session, and its own outcome must not be overwritten by this one. Returns whether anything changed.

pub fn record_failed_close( &mut self, session_id: &str, cause: &str, ) -> Result<bool>

Publish a safe lifecycle failure even if a previous internal error exists. Detailed diagnostics belong in logs; the stored outcome must be visible on all control surfaces. Reports whether the session still exists.

pub fn clear_recorded_close_failure(&mut self, session_id: &str) -> Result<bool>

Forget a recorded close failure, because something for this session has since succeeded. Only the sentence a failed close wrote is cleared; a raw error from any other operation is left alone. Reports whether anything changed.

pub fn suspend_session_without_checkpoint( &mut self, session_id: &str, executor: &impl CommandExecutor, ) -> Result<bool>

Close a session that has nothing to checkpoint.

A record still provisioning never reached a running worker, and a record with no target locator has no target to read a workspace from, so in both cases there is no relay to latch and no harness state to archive. Waiting for a relay that does not exist is what left a stuck provisioning session unclosable. Any target the session did leave behind is still torn down, and the checkpoint it already had is kept, so this is a close, not a forced destroy.

Returns whether target storage cleanup was deferred, like the graceful close does.

pub fn cleanup_stopped_target( &mut self, session_id: &str, executor: &impl CommandExecutor, ) -> Result<()>

Finish storage cleanup for a stopped Podman target retained by the quiescence transition. The locator stays durable until every command succeeds, making daemon restart and explicit retry idempotent.

pub fn force_stop( &mut self, session_id: &str, executor: &impl CommandExecutor, ) -> Result<bool>

Tear down the current target without taking a fresh checkpoint, then leave the logical session resumable from its latest verified archive.

pub fn destroy_session_controlled( &mut self, session_id: &str, executor: &impl CommandExecutor, ) -> Result<()>

Permanently destroy an inactive session and every artifact Hel owns for it. External cleanup happens before the durable record is dropped so failures remain visible and retryable.

pub fn destroy_session_controlled_with( &mut self, session_id: &str, executor: &impl CommandExecutor, branch: BranchDisposition, ) -> Result<()>

The same, with a say in what happens to the managed worktree’s branch.

A session that is already Stopped has had its checkout removed by [retire_managed_worktree], so usually only the branch is left for [cleanup_managed_worktree] to take. With BranchDisposition::Keep the record, the checkpoint, and the attachments go and the branch stays, which is what a destroy does unless the user asks otherwise.

pub fn force_destroy_session( &mut self, session_id: &str, executor: &impl CommandExecutor, branch: BranchDisposition, ) -> Result<()>

Permanently destroy a session from any state, without checkpointing and without requiring a recovery archive.

Unlike Controller::destroy_session_controlled, this accepts active states: it tears the live target down with the same close plan a verified close uses, so the owning process group dies before any files go. External cleanup happens before the durable record is dropped so failures stay visible and retryable; the recovery archive is removed, which is what makes the destruction irreversible. The managed worktree’s checkout always goes; its branch goes only when branch says so.

impl Controller

pub async fn prepare_move_session_controlled( &self, selection: MoveSelection, executor: &(impl CommandExecutor + Sync), ) -> Result<MovePreparation>

pub async fn move_session_managed_controlled( &mut self, request: MoveSessionRequest, executor: &(impl CommandExecutor + Sync), manager: &SessionManagerControl, ) -> Result<MoveOutcome>

Called with one daemon lifecycle and recovery reservation already held.

pub async fn recover_move_managed_controlled( &mut self, operation: MoveOperation, executor: &(impl CommandExecutor + Sync), manager: &SessionManagerControl, ) -> Result<MoveOutcome>

impl Controller

pub fn preflight_new_session( &self, bundle_id: &str, target_id: &str, project_directory: Option<&Path>, executor: &impl CommandExecutor, ) -> Result<NewSessionPreflight>

Inspect the selected project without changing it. The caller owns the executor’s cancellation and deadline, and any repair confirmation.

impl Controller

pub fn complete_path( &self, host: &CompletionHost, prefix: &str, kind: CompletionKind, executor: &impl CommandExecutor, ) -> Result<PathCompletion>

Complete prefix on host. Call only from background work: it may run a command on a remote machine.

impl Controller

pub async fn provision_session_controlled_with_commit( &mut self, session_id: &str, executor: &(impl CommandExecutor + Sync), grant_commit: impl FnOnce() -> Result<()>, ) -> Result<()>

pub async fn provision_subagent_session_controlled( &mut self, session_id: &str, executor: &(impl CommandExecutor + Sync), ) -> Result<()>

Start a child worker inside an already-provisioned parent target. Repository, target, and mount setup belong exclusively to the parent.

pub fn mark_worker_connected( &mut self, session_id: &str, native_session_id: Option<String>, ) -> Result<()>

impl Controller

pub fn scan_orphan_workers( &self, executor: &impl CommandExecutor, all_instances: bool, ) -> RecoveryScan

Find managed resources which are not represented by the controller’s current state. Labels/tags establish Hel ownership; the worker marker supplies profile and bundle metadata when it is available.

Unless all_instances is set, only workers stamped with this instance’s identity are listed: a QA instance sharing a host with a production instance must never see the production workers as its own.

pub async fn adopt_orphan_worker( &mut self, session_id: &str, target_id: &str, profile_override: Option<&str>, bundle_override: Option<&str>, all_instances: bool, executor: &impl CommandExecutor, ) -> Result<()>

pub fn destroy_orphan_worker( &self, session_id: &str, target_id: &str, confirmation: &str, all_instances: bool, executor: &impl CommandExecutor, ) -> Result<()>

impl Controller

pub fn preflight_resume_repository_sources( &self, session_id: &str, target_id: &str, executor: &(impl CommandExecutor + Sync), ) -> Result<ResumeRepositorySourcePreflight>

Prove that each configured repository source still supplies the commit boundary its checkpoint bundle expects, before provisioning anything, and describe a local checkout’s conversion so a person can confirm it.

pub fn replace_resume_repository_origin( &mut self, session_id: &str, repository_id: &str, replacement: &str, executor: &(impl CommandExecutor + Sync), ) -> Result<ResumeRepositorySourcePreflight>

Validate a replacement first, then atomically save it and check the remaining sources so multi-repository bundles can report the next moved repository without ever provisioning a partial target.

impl Controller

pub async fn resume_session_with_options( &mut self, session_id: &str, profile_id: &str, target_id: &str, additional_mounts: Option<Vec<AdditionalMount>>, resource_allocation: Option<SessionResourceAllocation>, ) -> Result<MaterializedSession>

Resume a stopped logical session on any configured profile and target. Cross-harness resume restores Git and canonical history, starts a fresh native session, and supplies the prior transcript as its first context turn.

pub async fn resume_session_with_options_and_queue_disposition( &mut self, session_id: &str, profile_id: &str, target_id: &str, additional_mounts: Option<Vec<AdditionalMount>>, resource_allocation: Option<SessionResourceAllocation>, discard_queue: bool, ) -> Result<MaterializedSession>

pub async fn resume_session_controlled( &mut self, session_id: &str, profile_id: &str, target_id: &str, options: SessionResumeOptions, executor: &(impl CommandExecutor + Sync), ) -> Result<MaterializedSession>

pub async fn resume_session_controlled_with_repository_preflight( &mut self, session_id: &str, profile_id: &str, target_id: &str, options: SessionResumeOptions, repository_preflight: Option<ResumeRepositorySourceReceipt>, executor: &(impl CommandExecutor + Sync), ) -> Result<MaterializedSession>

impl Controller

pub fn stage_reviewer_profile( &self, session_id: &str, profile_id: &str, generation: u64, ) -> Result<ReviewerLaunchConfig>

Copy profile_id’s home into the session worker’s reviewer directory and describe how the worker should launch it.

generation distinguishes reviewer lifetimes: bumping it tells the worker to start a new conversation instead of reloading the last one.

pub fn stage_reviewer_profile_with_mcp( &self, session_id: &str, profile_id: &str, generation: u64, mcp_servers: &[ReviewMcpServer], dispatch_tool: bool, ) -> Result<ReviewerLaunchConfig>

Stage a reviewer that also gets mcp_servers, which is how a turn review attaches its analyzer tools.

dispatch_tool adds the review supervisor’s own tool, which is this worker’s binary in another mode. Only the controller knows where that binary and its socket sit on the target, so it is built here rather than by the caller.

pub fn stage_reviewer_profile_controlled( &self, session_id: &str, profile_id: &str, generation: u64, mcp_servers: &[ReviewMcpServer], executor: &impl CommandExecutor, ) -> Result<ReviewerLaunchConfig>

impl Controller

pub async fn park_subagent_worker( &self, session_id: &str, executor: &(impl CommandExecutor + Sync), manager: &SessionManagerControl, ) -> Result<ParkOutcome>

Stop a running sub-agent’s worker while it is idle, and record it as parked.

The worker is reserved the way an idle worker upgrade reserves it: the actor’s connection is leased only while the worker reports nothing running or queued, and the worker holds an idle barrier until it is stopped. A prompt that reaches the actor meanwhile waits behind the lease. The lease is kept until the session manager has dropped the child, which it does once the store says Parked, so such a prompt is rejected as undelivered rather than sent to a stopped worker; the caller that sent it can start the child again and resend it.

Any failure before the record changes leaves the child running: the lease is dropped and the actor reconnects, restarting the worker if the stop got that far.

pub async fn unpark_subagent_worker( &self, session_id: &str, executor: &(impl CommandExecutor + Sync), ) -> Result<()>

Start a parked sub-agent’s worker again in place and record it as running.

The worker binary and launch configuration are refreshed first when this controller would now install different ones, then the restart sequence runs: start the worker on its existing root, connect with the long restart timeout, and wait until the harness has loaded its native session and is idle. The container’s start admission is held around the harness start, as it is for a child’s first start.

A failure stops whatever was started and leaves the record Parked, so the parent can try again. Nothing here connects a session actor: the caller runs this while the daemon keeps the manager off the child, and the manager attaches once the record says Running.

impl Controller

pub fn prepare_subagent_report_root( &self, parent_session_id: &str, executor: &impl CommandExecutor, ) -> Result<String>

Create the directory that holds a parent’s children’s report directories on the parent’s target, and return its absolute path.

It sits outside every repository: under the workspace root that a bundle session’s repositories are checked out below, or, for a bare project whose workspace root is the user’s own directory, inside the project under a path its info/exclude lists.

pub fn register_subagent( &mut self, request: RegisterSubagentRequest, ) -> Result<SubagentRecord>

Register a child without provisioning another target or checkout.

pub fn ensure_subagent_slot_available( &self, parent_session_id: &str, starting: Option<&str>, ) -> Result<()>

Refuse to start another child process tree for parent_session_id when it already has the maximum number of live children.

starting is the child a send_input is about to start again from parked; it is not counted against itself. A spawn passes None.

Every child whose worker may be holding processes in the parent’s container counts, idle or not: those processes are what the cap protects (#1161). A parked, stopped, failed or lost child holds none.

impl Controller

pub fn diagnose_worker(&self, session_id: &str) -> Option<String>

Probe the installed binary and collect the dead worker’s exit record and log tail after a session becomes unreachable. Best-effort; returns None when the target no longer exists or has no diagnostics.

pub fn diagnose_worker_controlled( &self, session_id: &str, executor: &impl CommandExecutor, ) -> Option<String>

pub fn worker_recovery_plan( &self, session_id: &str, ) -> Result<WorkerRecoveryPlan>

A non-destructive liveness probe plus commands that replace a confirmed dead session worker without touching its durable relay files. The session manager runs both off its async actor.

pub fn project_memory_sync_target( &self, session_id: &str, ) -> Result<ProjectMemorySyncTarget>

impl Controller

pub async fn upgrade_session_worker( &self, session_id: &str, executor: &(impl CommandExecutor + Sync), manager: &SessionManagerControl, reported_build: Option<&str>, ) -> Result<WorkerUpgradeOutcome>

Replace a session’s worker with the binary this controller would install, when the session is quiet and its worker is a different build.

reported_build is the digest the worker gave the observer that asked for this. It only saves work: a match returns before anything is leased. The decision that matters is taken again under the lease, against a snapshot read from the worker itself, because a session can start working between an observation and this call.

impl Controller

pub fn managed_worktree_options( &self, target_id: &str, directory: &Path, executor: &impl CommandExecutor, ) -> Result<ManagedWorktreeOptions>

Inspect in a supervised worker, never on a UI event loop.

pub fn resolve_project_directory( &self, target_id: &str, directory: &Path, executor: &impl CommandExecutor, ) -> Result<PathBuf>

Resolve first so validation, review, and launch use the same path.

pub fn validate_project_directory( &self, target_id: &str, directory: &Path, executor: &impl CommandExecutor, ) -> Result<()>

Verify a bare project before leaving the project-directory dialog.

pub fn resolve_session_project_source( &self, session_id: &str, executor: &impl CommandExecutor, ) -> Result<ProjectSourceIdentity>

Resolves a session’s canonical project without doing process work on a UI loop. Raw checkouts use their Git origin when available, then their canonical Git root or local directory.

impl Controller

pub fn load() -> Result<Self>

pub fn reload(&mut self) -> Result<()>

pub fn resolve_input_path( &self, target_id: &str, path: &Path, executor: &impl CommandExecutor, ) -> Result<PathBuf>

Resolve an entered path on its owning host. Call only from background work.

pub fn validate_mount_source( &self, target_id: &str, source: &Path, executor: &impl CommandExecutor, ) -> Result<Option<String>>

Verify a mount source on the host where Mjolnir will consume it, and report the filesystem reason it must be attached read-only, if there is one.

The probe runs in the same round trip as the existence check so the editor learns both answers without a second wait. A probe that cannot answer reports no reason: provisioning decides that authoritatively.

pub fn register_session_with_resources( &mut self, profile_id: &str, bundle_id: &str, target_id: &str, title: impl Into<String>, options: SessionLaunchOptions, ) -> Result<String>

pub fn rename_session( &mut self, session_id: &str, title: &str, ) -> Result<String>

pub fn rename_profile_id(&mut self, old_id: &str, new_id: &str) -> Result<()>

pub fn rename_target_id(&mut self, old_id: &str, new_id: &str) -> Result<()>

pub fn recover_config_id_rename() -> Result<bool>

Finish a profile/target id rename interrupted between the atomic config replacement and SQLite transaction. Each step is idempotent, so a second crash leaves the same intent available for the next startup.

pub fn update_session_container_settings( &mut self, session_id: &str, cpus: Option<String>, memory: Option<String>, additional_mounts: Vec<AdditionalMount>, mount_history: Vec<PathBuf>, executor: &impl CommandExecutor, ) -> Result<()>

Record the per-session container size overrides and attached directories. Nothing is applied to a running container: the values are read the next time the session’s container is created.