capsule_runtime/

errors.rs

use std::path::PathBuf;

use murmur_artifact::{level_has_phrase, ContractDirection, UnservedInterface};
use thiserror::Error;

/// Where the reference docs state the cgroup delegation a subprocess-capable capsule needs on
/// Linux, cited by [`RuntimeError::CgroupDelegationUnavailable`].
const RESOURCE_LIMITS_PLATFORM_URL: &str =
    murmur_artifact::docs_reference_url!("resource-limits/#platform-behavior");

/// One `capabilities.shell.allow` entry that resolved to a script whose interpreter's package
/// tree nothing declared could reach inside a `sealed` composed root.
///
/// Defined here rather than in [`crate::reachability`] — which is a `pub(crate)` module — because
/// it is a field of a public [`RuntimeError`] variant and so has to be nameable by anything that
/// matches on one (`murmur-cli`'s `CliError` conversion, above all).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnreachableEntrypoint {
    /// The `capabilities.shell.allow` entry, verbatim as the manifest wrote it.
    pub binary: String,
    /// Where that entry resolves on this host — the first `PATH` match, i.e. the one `execvp`
    /// would run.
    pub resolved_path: PathBuf,
    /// The bare interpreter name read out of the file's `#!` line, with one level of
    /// `env NAME` indirection resolved. This is the name a covering
    /// `interpreter_runtime`/`staged_runtime` grant would have to declare.
    pub interpreter: String,
}

impl std::fmt::Display for UnreachableEntrypoint {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "'{}' ({}, a script run by '{}')",
            self.binary,
            self.resolved_path.display(),
            self.interpreter
        )
    }
}

// The four codes below live beside the variants that raise them because two callers name them:
// murmur-cli renders them on the terminal, and the A2A terminal status a process attempt writes
// carries the same code. Defining them twice would let a client and an operator be shown
// different codes for one failure.

/// The code [`RuntimeError::HarnessTurnFailed`] renders under.
pub const E_RUN_033: &str = "E-RUN-033";
/// The code [`RuntimeError::ProcessDriverCallFailed`] renders under.
pub const E_RUN_034: &str = "E-RUN-034";
/// The code [`RuntimeError::ProcessHarnessInactive`] renders under.
pub const E_RUN_035: &str = "E-RUN-035";
/// The code [`RuntimeError::HarnessSessionGone`] renders under.
pub const E_RUN_036: &str = "E-RUN-036";

#[derive(Debug, Error)]
pub enum RuntimeError {
    #[error("artifact {name}@{version} is not in the store")]
    ArtifactNotFound { name: String, version: String },

    #[error("artifact integrity check failed for {name}@{version}")]
    ArtifactIntegrityFailed { name: String, version: String },

    #[error("lockfile missing artifact entry for '{name}'")]
    LockMissingEntry { name: String },

    #[error(
        "lockfile version mismatch for '{name}': manifest requested {requested}, lock pinned {pinned}"
    )]
    LockVersionMismatch {
        name: String,
        requested: String,
        pinned: String,
    },

    /// A `murmur.lock` pin written by `manage.pull()` is declared in a role only an
    /// operator-declared pin may carry. `declared_as` is the offending manifest text:
    /// `runtime: hook`, `runtime: driver`, `gateway:` or `inference.system_prompt_artifact`.
    #[error(
        "murmur.lock pins '{name}@{version}' from a runtime pull by session {session}, and \
         murmur.yaml declares it with {declared_as}, which only an operator-declared pin may carry"
    )]
    RuntimeOriginNotDeclarable {
        name: String,
        version: String,
        session: String,
        declared_as: &'static str,
    },

    #[error("failed to read artifact archive for {name}@{version}: {message}")]
    ArtifactArchive {
        name: String,
        version: String,
        message: String,
    },

    #[error("failed to compile component for {name}@{version}: {message}")]
    ToolComponentCompile {
        name: String,
        version: String,
        message: String,
    },

    #[error("failed to compile capsule component: {0}")]
    CapsuleCompile(String),

    #[error("failed to create workdir at {path}: {source}")]
    CreateWorkdir {
        path: String,
        #[source]
        source: std::io::Error,
    },

    /// A runtime write, append, read, create or removal inside the capsule's workdir met a
    /// symbolic link, a hard-linked or non-regular file, or an invalid path component, and did
    /// nothing. `mur` renders it as `E-RUN-050`.
    #[error("{refusal}")]
    WorkdirPathRefused {
        refusal: crate::workdir_fs::WorkdirRefusal,
    },

    /// `~/.murmur/sessions/<session-id>/`, the session's runtime directory, could not be created
    /// or locked. `mur` renders it as `E-IO-003`.
    #[error("failed to create the runtime directory: {reason}")]
    RuntimeDirUnavailable { reason: String },

    /// `~/.murmur/records/<workdir root>/<session-id>/`, the session's records directory, could not
    /// be created. `mur` renders it as `E-IO-003`.
    #[error("failed to create the records directory: {reason}")]
    RecordsDirUnavailable { reason: String },

    /// `HOME` cannot hold `~/.murmur`, so there is nowhere to put a session's runtime and records
    /// directories. Checked before anything is created; `mur` renders it as `E-IO-004`.
    #[error(transparent)]
    HomeUnusable(#[from] crate::murmur_home::HomeUnusable),

    /// A delegated child's `--workdir` is not the directory its parent created: its
    /// `(st_dev, st_ino)` differs from `--workdir-identity`. Nothing was written. `mur` renders it
    /// as `E-RUN-051`.
    #[error(
        "the workdir {workdir} is not the directory the delegating capsule created (expected \
         {expected}, found {found})"
    )]
    WorkdirIdentityMismatch {
        workdir: String,
        expected: String,
        found: String,
    },

    /// A tool name that is not one normal path component, so its staged manifest would land
    /// outside the runtime directory's `tools/`.
    #[error(
        "tool name '{}' is not a bare name, so its manifest would be written outside the \
         workdir's tools/ directory",
        name.escape_debug()
    )]
    ToolNameNotAComponent { name: String },

    #[error("failed to write tool manifest at {path}: {source}")]
    WriteToolManifest {
        path: String,
        #[source]
        source: std::io::Error,
    },

    #[error("failed to read inference.system_prompt_file at {path}: {source}")]
    SystemPromptFileRead {
        path: String,
        #[source]
        source: std::io::Error,
    },

    #[error("failed to read inference.compaction.system_prompt_file at {path}: {source}")]
    CompactionSystemPromptFileRead {
        path: String,
        #[source]
        source: std::io::Error,
    },

    #[error(
        "inference.system_prompt_artifact '{name}': skill.md not found or unreadable; \
         ensure the skill is declared in artifacts: and the capsule was staged"
    )]
    SystemPromptArtifactRead {
        name: String,
        #[source]
        source: std::io::Error,
    },

    #[error("skill source path not found: {path}")]
    SkillSourceNotFound { path: String },

    #[error("skill source directory '{path}' contains no skill.md")]
    SkillSourceMissingSkillMd { path: String },

    #[error("failed to read skill source at {path}: {source}")]
    SkillSourceRead {
        path: String,
        #[source]
        source: std::io::Error,
    },

    #[error("invalid network capability allow entry '{entry}': {message}")]
    InvalidNetworkAllowEntry { entry: String, message: String },

    #[error("invalid filesystem capability scope '{scope}': {message}")]
    InvalidFilesystemScope { scope: String, message: String },

    /// A `capabilities.filesystem.read_only` entry is not a usable workdir subpath: it is
    /// absolute, or it escapes the workdir via `..`. The exact parallel of
    /// [`Self::InvalidFilesystemScope`], raised from
    /// [`crate::protected_paths::ProtectedPaths::from_declared`] at staging — before any registry
    /// pull, workdir creation or component instantiation — so no call is ever checked against a
    /// rule the runtime could not build.
    #[error("invalid read-only path '{path}': {message}")]
    InvalidReadOnlyPath { path: String, message: String },

    /// An artifact entry's `config:` block cannot be delivered as `MURMUR_ARTIFACT_CONFIG`: it is
    /// not a string-keyed mapping, does not serialize to JSON, or exceeds
    /// [`crate::artifact_config::MAX_ARTIFACT_CONFIG_BYTES`]. Raised at staging (and from `mur run
    /// --explain-scope`), before any registry pull, workdir creation or component instantiation,
    /// so a malformed channel is refused once at launch rather than one tool call at a time.
    #[error("invalid config for artifact '{artifact}': {message}")]
    InvalidArtifactConfig { artifact: String, message: String },

    /// A `capabilities.state.store` name is not a single usable directory segment under
    /// `~/.murmur/state/`. Raised at staging (and from `mur run --explain-scope`), before any
    /// registry pull, workdir creation or component instantiation, so a bad name never gets as far
    /// as creating something on disk.
    #[error("invalid state store name '{store}': {message}")]
    InvalidStateStore { store: String, message: String },

    /// A `context.record_store` value, or a `mur run --context` value, is not a single usable
    /// directory segment of a conversation record path. Raised at staging, before any registry
    /// pull, workdir creation or component instantiation, so a bad name never gets as far as
    /// creating something on disk.
    ///
    /// Distinct from [`Self::InvalidStateStore`] because the remedies point at different keys, and
    /// because a record is on by default while a state store is declared: an operator seeing this
    /// may not have written a `context:` block at all, only a `--context` flag.
    #[error("invalid {field} '{value}': {message}")]
    InvalidConversationRecord {
        field: String,
        value: String,
        message: String,
    },

    /// `mur run --resume` named a session whose context kept no conversation record on disk, so
    /// there is nothing to continue. Raised at staging, before this launch's workdir exists: a
    /// resume that silently started fresh would be indistinguishable from one that worked.
    #[error(
        "cannot resume session {session}: context '{context_id}' has no conversation record ({reason})"
    )]
    ResumeRecordMissing {
        session: String,
        context_id: String,
        reason: String,
    },

    /// `mur run --resume-mode compact` on a capsule with no hook bound to `on-compaction`. There
    /// is nothing to produce the summary, and falling back to `full` would silently give the
    /// operator the mode they did not ask for.
    #[error(
        "--resume-mode compact needs a hook bound to on-compaction; this capsule declares none"
    )]
    ResumeCompactionHookMissing,

    /// `mur run --resume-mode compact` on a `transport: process` capsule. The harness holds the
    /// conversation and the runtime has no message list to hand a compaction hook, so there is
    /// nothing `compact` could summarize.
    #[error(
        "--resume-mode compact is not available under inference.transport: process; the harness \
         holds this conversation and murmur has no history to compact"
    )]
    ResumeCompactUnsupportedTransport,

    /// The state store directory a validated name resolves to could not be resolved or created.
    /// Distinct from [`Self::InvalidStateStore`]: the declaration is well-formed and the failure is
    /// the host's — an unset `HOME`, or a path that cannot be made a `0700` directory.
    #[error("state store '{store}' is unavailable at {path}: {message}")]
    StateStoreUnavailable {
        store: String,
        path: String,
        message: String,
    },

    /// The declared containment floor is stronger than what this host's kernel can back.
    /// Raised in the stage/launch seam, before any registry pull, component compile or workdir
    /// creation — `achieved` always comes from a live host probe, never from the manifest.
    #[error(
        "declared containment class '{declared}' is not achievable on this host (achieved: '{achieved}'): {reason}"
    )]
    ContainmentFloorUnmet {
        declared: murmur_artifact::ContainmentClass,
        achieved: murmur_artifact::ContainmentClass,
        reason: String,
        /// Why the floor is unmet, which decides what the operator is told to change.
        cause: crate::containment::ShortfallCause,
    },
    /// A capsule declares an `exports.files.root` that, once resolved against the session's
    /// accessible workdir, lands somewhere else — the root already exists as a symlink pointing
    /// out of it.
    ///
    /// Refused at launch rather than per request: an export root outside the workdir is a
    /// misconfiguration the operator can fix, and discovering it one served file at a time would
    /// mean the first file had already left.
    #[error(
        "{field} '{declared}' resolves to '{resolved}', which is outside the capsule \
         workdir '{workdir}'"
    )]
    ExportRootOutsideWorkdir {
        /// The manifest key that declared it — `exports.files.root` or
        /// `exports.peer_files.root`. Carried rather than hard-coded because the two roots are
        /// separate authorisers and an operator fixing one must be told which.
        field: String,
        declared: String,
        resolved: String,
        workdir: String,
    },

    /// A capsule declares an artifact whose name collides with a tool the runtime provides
    /// itself.
    ///
    /// Every name in [`crate::runtime::RESERVED_TOOL_NAMES`] is answered inside
    /// `dispatch_agent_tool_unfenced` before any allowlist check is reached, and their synthetic
    /// manifests are written after the staging loop. An artifact installed under one of them would
    /// have its manifest overwritten and every call to it answered by the runtime, so the collision
    /// is refused rather than resolved into a tool the capsule can never reach.
    #[error(
        "artifact '{name}' has the tool name '{}', which collides with a tool the runtime \
         provides itself; the reserved names are {}",
        murmur_artifact::tool_name_of(name),
        crate::runtime::RESERVED_TOOL_NAMES.join(", ")
    )]
    ReservedToolName {
        /// The declared artifact name whose tool name collides.
        name: String,
    },

    /// Two declared artifacts share a tool name, the bare part a session offers the model and
    /// stages under `<runtime dir>/tools/`.
    #[error(
        "artifacts '{first}' and '{second}' share the tool name '{tool}'; a capsule offers each \
         artifact to the model by its tool name, so no two may share one"
    )]
    DuplicateToolName {
        first: String,
        second: String,
        tool: String,
    },

    /// A capsule's `capabilities.env.allow` names variables the credential backstop strips from
    /// every guest environment.
    ///
    /// The strip in `build_declared_env` is not negotiable from a manifest, so the entries
    /// can only ever deliver nothing; the declaration is refused rather than left silently inert.
    #[error(
        "capabilities.env.allow names {}; these entries are removed from every guest environment \
         before any guest is built, so the grant would deliver nothing",
        crate::runtime::describe_stripped_env_allow_entries(entries)
    )]
    EnvAllowStrippedByBackstop {
        /// Every distinct stripped entry, in first-declaration order.
        entries: Vec<crate::runtime::StrippedEnvAllowEntry>,
    },

    /// A synthetic tool manifest was written under a name absent from
    /// [`crate::runtime::RESERVED_TOOL_NAMES`].
    ///
    /// The inverse of [`Self::ReservedToolName`], and the reason a further runtime-provided tool
    /// cannot be added without reserving its name: an unreserved name is claimable by an artifact,
    /// which would then be installed and silently shadowed at dispatch.
    #[error(
        "'{name}' is written as a runtime-provided tool but is not one of {}; add it to \
         RESERVED_TOOL_NAMES so no artifact can claim the name",
        crate::runtime::RESERVED_TOOL_NAMES.join(", ")
    )]
    RuntimeProvidedToolNotReserved {
        /// The name the synthetic write was attempted under.
        name: String,
    },

    /// A capsule declares `exports.peer_files` together with `lifecycle.after_task: sleep`, and
    /// either declared no `max_ttl` or declared one above the persistent ceiling.
    ///
    /// An ephemeral capsule needs no ceiling: teardown destroys the minting key, so every
    /// outstanding handle stops verifying at once and the declared lifetime can never outlive the
    /// process. `sleep` withdraws that bound deliberately, which makes the declared lifetime the
    /// only one there is — so it has to be declared, and it has to be short.
    #[error(
        "exports.peer_files with lifecycle.after_task: sleep requires exports.peer_files.max_ttl \
         to be declared and at most {ceiling_secs}s{}; a handle's lifetime is not a durability \
         mechanism",
        match declared_secs {
            Some(secs) => format!(" (declared {secs}s)"),
            None => String::new(),
        }
    )]
    PersistentCapsuleNeedsHandleTtl {
        /// The declared `max_ttl` in seconds, or `None` when the manifest declared none.
        declared_secs: Option<u64>,
        ceiling_secs: u64,
    },

    /// A capsule declares `capabilities.shell.staged_runtime` without an effective `sealed`
    /// containment floor.
    ///
    /// Deliberately distinct from [`Self::ContainmentFloorUnmet`]: that one compares the declared
    /// floor against what the *host* can back, and its remedy is to lower the floor or move hosts.
    /// This one is decided against the declared floor alone and never looks at the host at all, so
    /// it fires identically on a machine that could deliver `sealed` — a staged runtime has no
    /// composed root to be staged into unless the capsule asked for one, and quietly launching it
    /// without the mount would leave the interpreter simply absent. Its remedy is to raise the
    /// declared floor (or drop the grant), which is the opposite advice.
    ///
    /// `binaries` names every offending `staged_runtime` binary so the operator does not have to
    /// re-run to find the second one.
    #[error(
        "capabilities.shell.staged_runtime is declared for {} but the effective containment floor \
         is '{declared}' — staging a runtime tree requires the 'sealed' floor, because there is no \
         composed root to bind-mount it into below that",
        .binaries.join(", ")
    )]
    StagedRuntimeRequiresSealed {
        binaries: Vec<String>,
        declared: murmur_artifact::ContainmentClass,
    },

    /// A `sealed` capsule allowlists a script whose interpreter's package tree nothing declared
    /// could make reachable inside the composed root.
    ///
    /// Deliberately distinct from [`Self::StagedRuntimeRequiresSealed`], which it sits next to in
    /// `stage_session`: that one fires when a grant *was* declared at too low a floor, this one
    /// fires when no grant was declared at all and the floor is already `sealed`. Their remedies
    /// point in opposite directions — raise the floor there, add a grant here.
    ///
    /// `entries` names every offending allowlist entry so an operator fixing this does not have to
    /// re-run to discover the second script, following the same precedent.
    #[error(
        "capabilities.shell.allow grants {} under the 'sealed' containment floor, but nothing \
         declared makes the interpreted entrypoint's own package tree reachable inside the \
         composed root — the script's ELF/DT_NEEDED closure is empty, so staging it stages \
         nothing its interpreter imports, and the capsule would fail with a module-not-found \
         error partway into a run rather than here. Declare \
         capabilities.shell.interpreter_runtime or capabilities.shell.staged_runtime naming the \
         interpreter (measure the real directories with \
         `strace -f -e trace=openat,getdents64 <the command>`), or use a copy of the interpreter \
         and its packages that already lives under a fixed sealed runtime path",
        .entries
            .iter()
            .map(UnreachableEntrypoint::to_string)
            .collect::<Vec<_>>()
            .join("; ")
    )]
    ShellBinaryPackageUnreachable { entries: Vec<UnreachableEntrypoint> },

    /// A `sealed` session's composed root could not be built in the forked child, *after* the
    /// pre-launch probe reported the mechanism available.
    ///
    /// Deliberately distinct from [`Self::ContainmentFloorUnmet`]: that one is a refusal decided
    /// before anything is staged, on a host that never claimed to offer `sealed`. This one is a
    /// host that claimed it and then failed to deliver — a race, a mount table that changed under
    /// the runtime, or an edge case the cheap probe cannot catch. Conflating the two would tell an
    /// operator to lower their declared floor when the real answer is that something moved.
    ///
    /// `detail` is the message the child wrote to the `pre_exec` diagnostic pipe, which names the
    /// exact step (`unshare`, a specific bind mount, `pivot_root`) and its errno.
    #[error(
        "the sealed containment class was achievable at launch but its composed root could not be \
         built for this subprocess: {detail}"
    )]
    SealedRootConstructionFailed { detail: String },

    /// This host cannot give a capsule's native subprocess tree its own network namespace, so the
    /// egress boundary that mediates `capabilities.network.allow` cannot be built.
    ///
    /// Raised before any registry pull, component compile or workdir creation, and raised for
    /// **every** Linux capsule that can spawn a subprocess — including one whose
    /// `capabilities.network.allow` is empty. That breadth is the point: with the namespace
    /// missing, an empty allowlist would mean *unrestricted* egress rather than none, because the
    /// seccomp `connect`/`sendto` interception that used to back it was deleted as unsound rather
    /// than kept as a fallback. There is deliberately no path that continues at reduced
    /// enforcement.
    ///
    /// Deliberately distinct from [`Self::ContainmentFloorUnmet`], which this would otherwise
    /// look like: that one compares a *declared* containment class against what the host can
    /// back, and its remedy is to lower the declared floor. A network namespace is not part of
    /// the containment ladder — every class needs it equally — so lowering the floor fixes
    /// nothing here, and offering that advice would be actively misleading.
    #[error(
        "this host cannot give the capsule's subprocess tree its own network namespace, so \
         capabilities.network.allow cannot be enforced for it: {reason}"
    )]
    EgressNamespaceUnavailable {
        blocker: crate::network_namespace::EgressNamespaceBlocker,
        reason: String,
    },

    #[error(
        "capsule component missing export murmur:capsule/run@0.1.0#run; rebuild the artifact against the versioned WIT (run `mur install` for a default artifact, or rebuild from source otherwise)"
    )]
    CapsuleExportMissing,

    #[error(
        "tool component '{name}' missing export murmur:tool/run@0.1.0#run; rebuild the artifact against the versioned WIT (run `mur install` for a default artifact, or rebuild from source otherwise)"
    )]
    ToolExportMissing { name: String },

    #[error("capsule execution trapped: {0}")]
    CapsuleTrap(String),

    #[error(
        "capsule execution exceeded its {seconds}s deadline and was interrupted; \
         raise capabilities.limits.deadline_seconds in murmur.yaml if the capsule \
         legitimately needs longer"
    )]
    CapsuleDeadlineExceeded { seconds: u64 },

    #[error("capsule execution exceeded its configured resource limits: {message}")]
    CapsuleResourceLimit { message: String },

    #[error(
        "shell subprocess '{binary}' was killed for exceeding \
         capabilities.resources.{limit}: {detail}"
    )]
    ShellResourceLimitExceeded {
        binary: String,
        limit: String,
        detail: String,
    },

    #[error(
        "tool '{tool}' returned data_path '{path}', which does not resolve to a readable file \
         beneath the session workdir ({code}): {detail}"
    )]
    ToolDataPathRefused {
        tool: String,
        path: String,
        code: String,
        detail: String,
    },

    #[error(
        "this capsule can spawn native subprocesses but no cgroup v2 scope could be created to \
         bound them ({reason}); on Linux the runtime refuses to launch rather than run a \
         subprocess tree with no aggregate memory/pids/cpu ceiling — see the systemd user \
         delegation requirement at {}",
        RESOURCE_LIMITS_PLATFORM_URL
    )]
    CgroupDelegationUnavailable { reason: String },

    #[error(
        "session workdir grew to {observed_bytes} bytes, past the {max_bytes} byte ceiling \
         (capabilities.resources.workdir_max_bytes)"
    )]
    WorkdirSizeExceeded { max_bytes: u64, observed_bytes: u64 },

    #[error("failed to initialize WASI for {path}: {message}")]
    WasiInit { path: String, message: String },

    #[error("inference driver is not configured; add inference.driver.artifact to murmur.yaml")]
    DriverNotConfigured,

    #[error("inference driver '{0}' is not installed in the local tool registry")]
    DriverNotInstalled(String),

    /// An artifact whose operator entry declares `gateway:` has a bundled manifest with no usable
    /// `upstream_auth:` block, so the runtime cannot tell how its upstream expects the key.
    /// Refused at staging, before any component runs, whether or not `gateway.api_key` is set.
    /// `reason` is `None` when the block is absent and says what is wrong when it is malformed.
    #[error(
        "artifact '{name}@{version}' declares no usable upstream_auth: block{}",
        .reason.as_ref().map(|reason| format!(" ({reason})")).unwrap_or_default()
    )]
    GatewayArtifactDeclaresNoUpstreamAuth {
        name: String,
        version: String,
        reason: Option<String>,
    },

    /// A `gateway:` block is declared on a `runtime: tool` entry whose artifact ships a native
    /// implementation. A native tool's requests leave through the egress proxy and never pass the
    /// credential gateway, so the key could never be attached. Refused at staging.
    #[error(
        "artifact '{name}' declares 'gateway:' but ships a native implementation, whose requests \
         never pass the credential gateway"
    )]
    GatewayOnNativeArtifact { name: String },

    /// The launch's `--lifecycle-task-acceptance queue` override turns a manifest that declares
    /// `lifecycle.queue_depth: 0` under another acceptance into a queue with no room for a waiting
    /// task. The manifest refuses `queue` at depth 0 at load; this is the one combination load
    /// cannot see. Refused at staging, before any registry pull or workdir creation.
    #[error(
        "the launch sets lifecycle.task_acceptance to queue, and murmur.yaml declares \
         lifecycle.queue_depth: 0, which leaves the queue no room for a waiting task"
    )]
    QueueWithoutRoom,

    /// An [`crate::types::ArtifactRequest`]'s gateway carries neither a credential nor the
    /// operator's `keyless: true`. The manifest parser refuses that shape first; staging refuses
    /// it again so no caller can build a gateway that sends keyless by omission.
    #[error("artifact '{name}' declares gateway.endpoint '{endpoint}' but binds no credential")]
    GatewayWithoutCredential { name: String, endpoint: String },

    /// `gateway.api_key: ${variable}` on artifact `artifact` names a credential that neither the
    /// global config's `credentials:` map nor the launching environment holds. Refused at staging,
    /// before the session directory exists.
    #[error(
        "murmur.yaml: gateway.api_key on artifact '{artifact}' references ${{{variable}}}, but \
         neither credentials.{variable} in {} nor the environment variable {variable} is set",
        .credentials_file
            .as_ref()
            .map(|path| path.display().to_string())
            .unwrap_or_else(|| "the global config".to_string())
    )]
    GatewayCredentialNotFound {
        artifact: String,
        variable: String,
        credentials_file: Option<std::path::PathBuf>,
    },

    /// `spend.machine_tokens_per_day` is in effect and the shared ledger it is kept in cannot be
    /// used — an unset `HOME`, a `~/.murmur/spend` that cannot be made a `0700` directory, or a
    /// daily file that cannot be opened. Raised at staging, before the session directory exists
    /// and before any provider request.
    #[error("spend ledger at {path} is unavailable: {message}")]
    SpendLedgerUnavailable { path: String, message: String },

    /// A capsule declaring `control:` could not mint its control token or write it beside its
    /// running record. Raised before the door is announced: a capsule whose declared
    /// controllability no controller could reach does not run. `reason` names the path and the
    /// failure, never the token.
    #[error("this capsule declares control: and its control token could not be written: {reason}")]
    ControlTokenUnwritable { reason: String },

    #[error("agent loop failed: {0}")]
    AgentLoopFailed(String),

    /// The launch ran, and the task it was run for did not complete. The session itself shut down
    /// cleanly: everything it records — `out/result.txt`, the trace, a delegated child's
    /// completion — was written before this was returned.
    ///
    /// `exit_status` is the `task_end`/`session_end` vocabulary, never `"ok"`: `"failed"`,
    /// `"max_turns_reached"`, `"spend_ceiling_reached"` or `"canceled"`. `reason` is never empty;
    /// for `"failed"` it is the reason the run's `task_failed` trace line carries.
    #[error("the task ended {exit_status}: {reason}")]
    TaskDidNotComplete {
        exit_status: &'static str,
        reason: String,
    },

    #[error("internal_port {port} is already bound; choose another port or omit internal_port to use an OS-assigned port")]
    PortInUse { port: u16 },

    /// A session whose manifest declares `capabilities.spawn.allow` could not register with
    /// `mur-roost`, so the daemon does not hold the grants it would referee that session's
    /// delegations against.
    ///
    /// Fatal rather than a warning: a capsule that can delegate but is unknown to the daemon is a
    /// capsule running outside the only thing that bounds what it may spawn. A capsule that
    /// declares no spawn capability never registers and never reaches this.
    ///
    /// `reason` is the transport or daemon-side failure verbatim. Neither this nor anything
    /// derived from it carries a credential or an approval: the registration request's tokens
    /// travel in headers, and the HTTP client never puts a request header into an error.
    #[error(
        "failed to register this session with mur-roost at {roost_url}: {reason}; a capsule \
         declaring capabilities.spawn.allow must be known to the daemon that referees its \
         spawns, so the launch is refused rather than run unrefereed"
    )]
    SpawnRegistrationFailed { roost_url: String, reason: String },

    /// `MURMUR_SPAWNER` was set to something that is not a spawner handle.
    ///
    /// `reason` names what about the value could not be read, and nothing derived from it carries
    /// the value itself: a handle names a parent's address and session, which is not this
    /// process's to print back out.
    #[error(
        "MURMUR_SPAWNER does not carry a readable spawner handle: {reason}; a delegated child \
         must be able to tell its spawner that it finished, so the launch is refused rather than \
         run unreportable"
    )]
    SpawnerHandleUnreadable { reason: String },

    /// `MURMUR_FORMATION_ID` was set to something that is not a formation id.
    ///
    /// `reason` names what about the value is wrong — its prefix, its length, or a character
    /// outside lowercase hex — and never carries the value itself.
    #[error(
        "MURMUR_FORMATION_ID does not carry a formation id: {reason}; a session that cannot tell \
         which formation it belongs to would be grouped with the wrong one, so the launch is \
         refused"
    )]
    FormationIdUnreadable { reason: String },

    /// `MURMUR_FORMATION_PEERS` is set in `mur run`'s own process environment, where nothing
    /// legitimately puts it, or a list of peers is not one a guest could be handed.
    ///
    /// `reason` says where the variable was found, or names the pair at fault by its position and
    /// what is wrong with it. It never carries the value.
    #[error("MURMUR_FORMATION_PEERS cannot be used: {reason}, so the launch is refused")]
    FormationPeersUnreadable { reason: String },

    /// The formation channel `MURMUR_FORMATION_CHANNEL` names could not be read: the descriptor is
    /// not open, its first line did not arrive in time or is not a member's bundle, or it names
    /// another formation.
    ///
    /// `reason` names the problem and never quotes the line: the line carries the member's
    /// formation tokens.
    #[error(
        "MURMUR_FORMATION_CHANNEL does not carry this member's formation credentials: {reason}; a \
         member that cannot read what its launcher handed it could neither prove who it is nor \
         call anyone, so the launch is refused"
    )]
    FormationChannelUnreadable { reason: String },

    /// `MURMUR_FORMATION_LIFELINE` does not name a lifeline this session can hold: the value is
    /// not a pipe's read end, it was read twice, it came without a formation id, or the session
    /// cannot honour one (a script capsule, or a caller that does not own its process).
    ///
    /// `reason` names what is wrong, by descriptor number where there is one.
    #[error(
        "MURMUR_FORMATION_LIFELINE does not carry this member's formation lifeline: {reason}; a \
         member that cannot hear its lifeline would keep running after its formation ends, so \
         the launch is refused"
    )]
    FormationLifelineUnreadable { reason: String },

    /// `MURMUR_SPAWNER_LIFELINE` does not name a lifeline this session can hold: the value is not
    /// a pipe's read end, it was read twice, or the launch cannot honour one (a caller that does
    /// not own its process).
    ///
    /// `reason` names what is wrong, by descriptor number where there is one.
    #[error(
        "MURMUR_SPAWNER_LIFELINE does not carry this session's spawner lifeline: {reason}; a \
         delegated child that cannot hear its spawner would keep running after the session that \
         delegated to it has ended, so the launch is refused"
    )]
    SpawnerLifelineUnreadable { reason: String },

    /// A native tool's `bin/<name>` payload was built for another operating system or CPU
    /// architecture than this host.
    ///
    /// Raised before any byte of any native binary in the same staging batch reaches the session
    /// workdir: an image this host cannot exec would otherwise be written, made executable, and
    /// then die on a raw `Exec format error` mid-run, at a point where nothing left says which
    /// artifact was wrong.
    ///
    /// Both platforms are `current_platform()`-shaped strings, or the bare `darwin` a fat Mach-O
    /// identifies as.
    #[error(
        "native tool '{name}' cannot run on this host: its binary is built for \
         {binary_platform}, this host is {host_platform}"
    )]
    NativeBinaryPlatformMismatch {
        name: String,
        binary_platform: String,
        host_platform: String,
    },

    /// The artifact a `transport: process` manifest names under `inference.driver` exports no
    /// version of the `murmur:driver/process` interface at all, so it is not a process driver.
    /// One exporting another version is [`RuntimeError::WitLevelMismatch`] instead.
    #[error(
        "artifact '{name}@{version}' is the transport: process driver but does not export \
         {expected}; a process driver must be built against the process-driver world"
    )]
    ProcessDriverInterfaceMissing {
        name: String,
        version: String,
        expected: String,
    },

    /// An artifact a launch stages names a `murmur:*` interface at a version other than the one
    /// the WIT level this host serves lists for its package. `mismatched` holds every such
    /// interface, in recorded order, and is never empty.
    #[error(
        "artifact '{name}@{version}' does not fit WIT level {level}, the level this mur serves: {}",
        level_mismatch_clauses(*.level, .mismatched)
    )]
    WitLevelMismatch {
        name: String,
        version: String,
        level: u64,
        mismatched: Vec<UnservedInterface>,
    },

    /// The artifact a `transport: http` manifest names under `inference.driver` exports a
    /// `murmur:driver/process@*` instance, so it drives a CLI rather than an HTTP API.
    #[error(
        "artifact '{name}@{version}' is the transport: http inference driver but exports {}, the \
         process driver interface; name it under transport: process, or name an http driver",
        .exported.join(", ")
    )]
    HttpDriverExportsProcessInterface {
        name: String,
        version: String,
        exported: Vec<String>,
    },

    /// A `runtime: driver` artifact imports a `murmur:stream/*` instance at the served version of
    /// the package under another interface name than `expected`, so it names an interface that
    /// does not exist. `imported` holds every such import. A stream or `murmur:text/*` import at
    /// another version is [`RuntimeError::WitLevelMismatch`] instead.
    #[error(
        "artifact '{name}@{version}' imports {}, which this host does not serve; a driver must \
         import {expected} in its place",
        .imported.join(", ")
    )]
    DriverStreamInterfaceNotServed {
        name: String,
        version: String,
        imported: Vec<String>,
        expected: String,
    },

    /// A process driver's `describe().required-env` names variables the manifest's
    /// `capabilities.env.allow` does not declare. `missing` is in the driver's order, each name
    /// once.
    #[error(
        "process driver '{name}@{version}' requires {} in its environment, which \
         capabilities.env.allow does not declare",
        .missing.join(", ")
    )]
    ProcessDriverRequiredEnvNotAllowed {
        name: String,
        version: String,
        missing: Vec<String>,
    },

    /// A spend ceiling is in effect against a process driver whose `describe().reports-usage` is
    /// `false`, so no turn it drives could ever be counted against that ceiling.
    ///
    /// `ceilings` names each ceiling in effect, in the order the operator would read them: the
    /// manifest's `inference.max_session_tokens` first, then the effective config's
    /// `spend.machine_tokens_per_day`.
    #[error(
        "process driver '{name}@{version}' reports no usage — its describe() sets \
         reports-usage: false — so {} could never be enforced",
        .ceilings.join(" and ")
    )]
    ProcessDriverReportsNoUsage {
        name: String,
        version: String,
        ceilings: Vec<String>,
    },

    /// A process driver could not be instantiated with no grants, trapped in `describe`, or
    /// described itself with an unusable `required-env` name. `message` is wasmtime's error, which
    /// names an unsatisfied import, or names the unusable variable.
    #[error("process driver '{name}@{version}' could not be loaded with no grants: {message}")]
    ProcessDriverLoad {
        name: String,
        version: String,
        message: String,
    },

    /// The executable a process capsule's harness runs as could not be resolved at staging.
    /// `binary_source` names where the name came from, so the operator knows which field to
    /// change: `inference.command`, or the process driver's own `describe()`.
    #[error("harness binary '{binary}', named by {binary_source}, was not found on this host")]
    HarnessBinaryNotFound {
        binary: String,
        binary_source: String,
    },

    /// The harness ended a turn in failure. Renders as [`E_RUN_033`]. `kind` is the driver's
    /// `failure-kind`, spelled as it is in the WIT, or `max-turns` when this runtime stopped the
    /// harness at the attempt's turn budget; `origin` distinguishes those two (`harness` /
    /// `runtime`) and is what the trace's `harness_failed.source` records.
    #[error("the harness turn failed ({kind}): {message}")]
    HarnessTurnFailed {
        kind: String,
        message: String,
        origin: String,
    },

    /// A turn launched `mode: resume` failed without the harness ever reporting the session it
    /// was handed: the conversation this context names is gone from the harness's own store.
    /// Renders as [`E_RUN_036`].
    ///
    /// `path` is the map file that still holds the id, or `None` on a launch that kept none. The
    /// entry is deliberately left as it is — the next task in this context fails the same way
    /// rather than quietly starting a new conversation, until somebody asks for it to be dropped
    /// with `mur run --forget-session` or a message whose metadata carries `forgetSession: true`
    /// under the door extension's key.
    #[error(
        "the harness '{harness}' could not continue session {session_id}, which context \
         '{context_id}' names: {detail}{}",
        harness_session_file_tail(.path)
    )]
    HarnessSessionGone {
        context_id: String,
        session_id: String,
        harness: String,
        path: Option<PathBuf>,
        detail: String,
    },

    /// A forget was asked of a capsule that keeps no harness session: only
    /// `inference.transport: process` has one, because only there does a harness own the
    /// conversation. Raised at staging, so the launch leaves nothing behind.
    ///
    /// `transport` is the transport the capsule declared, or `none` for a capsule with no
    /// `inference:` block at all.
    #[error(
        "--forget-session forgets the harness session a context names, and only \
         inference.transport: process has one; this capsule's transport is '{transport}'"
    )]
    ForgetSessionUnsupportedTransport { transport: String },

    /// A call into the process driver trapped, ran out of time, or refused. Renders as
    /// [`E_RUN_034`]. `call` is the WIT function name; `message` is the driver's own refusal or
    /// the failure's description.
    #[error("process driver '{name}@{version}' failed in {call}: {message}")]
    ProcessDriverCallFailed {
        name: String,
        version: String,
        call: String,
        message: String,
    },

    /// The harness went quiet: no stdout line and no bridge request for the whole inactivity
    /// window, so the runtime killed it rather than waiting on a process that had stopped working.
    /// Renders as [`E_RUN_035`].
    #[error(
        "the harness produced neither a line of output nor a tool call for {seconds}s and was \
         killed"
    )]
    ProcessHarnessInactive { seconds: u64 },

    #[error("runtime failure: {0}")]
    Runtime(String),
}

/// The clauses of [`RuntimeError::WitLevelMismatch`]'s message, one per mismatched interface:
/// `it exports <interface>, and level <N> has <package>@<version>`, joined with `; `.
fn level_mismatch_clauses(level: u64, mismatched: &[UnservedInterface]) -> String {
    mismatched
        .iter()
        .map(|mismatch| {
            let direction = match mismatch.direction {
                ContractDirection::Export => "exports",
                ContractDirection::Import => "imports",
            };
            format!(
                "it {direction} {}, and {}",
                mismatch.interface,
                level_has_phrase(level, mismatch)
            )
        })
        .collect::<Vec<_>>()
        .join("; ")
}

/// The tail of [`RuntimeError::HarnessSessionGone`]'s message: where the session id that could
/// not be continued is recorded, so the operator can read it, or that this launch recorded it
/// nowhere.
fn harness_session_file_tail(path: &Option<PathBuf>) -> String {
    match path {
        Some(path) => format!(" (that id is recorded in {})", path.display()),
        None => " (this launch recorded that id in memory only)".to_string(),
    }
}

impl RuntimeError {
    #[must_use]
    pub fn artifact_not_found(name: impl Into<String>, version: impl Into<String>) -> Self {
        Self::ArtifactNotFound {
            name: name.into(),
            version: version.into(),
        }
    }

    #[must_use]
    pub fn artifact_integrity_failed(name: impl Into<String>, version: impl Into<String>) -> Self {
        Self::ArtifactIntegrityFailed {
            name: name.into(),
            version: version.into(),
        }
    }

    #[must_use]
    pub fn wasi(path: PathBuf, message: impl Into<String>) -> Self {
        Self::WasiInit {
            path: path.display().to_string(),
            message: message.into(),
        }
    }
}

impl RuntimeError {
    /// `error` as a runtime error: a refusal is [`Self::WorkdirPathRefused`], and an I/O failure
    /// whatever `io` makes of its path and source.
    pub(crate) fn from_workdir(
        error: crate::workdir_fs::WorkdirError,
        io: impl FnOnce(String, std::io::Error) -> Self,
    ) -> Self {
        match error {
            crate::workdir_fs::WorkdirError::Refused(refusal) => {
                Self::WorkdirPathRefused { refusal }
            }
            crate::workdir_fs::WorkdirError::Io { path, source } => io(path, source),
        }
    }
}

/// A refusal is [`RuntimeError::WorkdirPathRefused`]; any I/O failure is
/// [`RuntimeError::CreateWorkdir`]. Use [`RuntimeError::from_workdir`] where that variant is wrong.
impl From<crate::workdir_fs::WorkdirError> for RuntimeError {
    fn from(error: crate::workdir_fs::WorkdirError) -> Self {
        Self::from_workdir(error, |path, source| Self::CreateWorkdir { path, source })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn cgroup_delegation_refusal_links_the_published_platform_section() {
        let message = RuntimeError::CgroupDelegationUnavailable { reason: "x".into() }.to_string();
        assert!(message.contains("(x)"), "{message}");
        assert!(
            message
                .contains("https://docs.murmur.nexus/reference/resource-limits/#platform-behavior"),
            "{message}"
        );
        assert!(!message.contains("docs/content"), "{message}");
    }
}