dsh-ops 0.0.0-stage → 0.2.2

package/vendor/fastctx/src/session.rs

@@ -0,0 +1,629 @@
+// Modified by dsh-ops (https://github.com/T-Auto/dsh-ops): replaced the deleted Codex provider detection with the selected-tier output policy and dropped the Codex profile paths it read.
+//! Immutable per-connection working directory, environment, and output policy.
+
+use crate::budget::{
+    GLOB_TOKEN_BUDGET_ENV, GLOBAL_TOKEN_BUDGET_ENV, GREP_TOKEN_BUDGET_ENV,
+    JOB_OUTPUT_TOKEN_BUDGET_ENV, READ_TOKEN_BUDGET_ENV, RUN_TOKEN_BUDGET_ENV,
+};
+use crate::context_guard::{BURST_GAP, BurstTicket, GuardedBurstPool};
+use crate::control::paths::ControlPaths;
+use crate::control::settings::{FastCtxSettings, Tier, ToolBudgetPreferences, ToolBudgets};
+use std::cell::RefCell;
+use std::env::VarError;
+use std::ffi::{OsStr, OsString};
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use std::sync::Arc;
+
+/// Effective output mode for one configuration snapshot.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum EffectiveOutputMode {
+    /// The user's selected tier is effective.
+    SelectedTier,
+    /// The provider route is unverified or compacts locally, so Guarded ceilings are effective.
+    ///
+    /// Nothing selects this mode since the Codex provider detection was removed; the guarded burst
+    /// machinery that reads it is retained unchanged.
+    Guarded,
+}
+
+/// Concrete output limits consumed by one runtime session.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct EffectiveOutput {
+    /// User preference retained independently from the environment-derived mode.
+    pub selected_tier: Tier,
+    /// Environment-derived effective mode.
+    pub mode: EffectiveOutputMode,
+    /// Host token limit the removed Apply path used to write.
+    pub host_limit: i64,
+    /// Global FastCtx response budget.
+    pub fastctx_budget: usize,
+    /// Concrete per-tool shares, including defaults for the effective mode.
+    pub tool_budgets: ToolBudgets,
+}
+
+/// Resolves the output policy for one connection.
+///
+/// Provider detection was removed with the Codex integration, so the user's selected tier is
+/// always effective — the unguarded policy this crate already used whenever no Codex profile was
+/// readable.
+fn effective_output(selected_tier: Tier, preferences: ToolBudgetPreferences) -> EffectiveOutput {
+    EffectiveOutput {
+        selected_tier,
+        mode: EffectiveOutputMode::SelectedTier,
+        host_limit: selected_tier.host_limit(),
+        fastctx_budget: selected_tier.fastctx_budget(),
+        tool_budgets: preferences.resolve(selected_tier),
+    }
+}
+
+thread_local! {
+    static ACTIVE_ENVIRONMENT: RefCell<Option<Arc<SessionEnvironment>>> = const { RefCell::new(None) };
+}
+
+/// The native process state captured by one stdio proxy before it connects.
+///
+/// Environment values remain `OsString`s so Unix bytes and Windows unpaired UTF-16 units survive
+/// the IPC handshake without lossy conversion.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SessionEnvironment {
+    cwd: PathBuf,
+    variables: Arc<Vec<(OsString, OsString)>>,
+}
+
+#[derive(serde::Deserialize, serde::Serialize)]
+struct SessionEnvironmentWire {
+    cwd: NativeOsString,
+    variables: Vec<(NativeOsString, NativeOsString)>,
+}
+
+#[derive(serde::Deserialize, serde::Serialize)]
+#[serde(transparent)]
+struct NativeOsString(String);
+
+impl serde::Serialize for SessionEnvironment {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        SessionEnvironmentWire {
+            cwd: NativeOsString::encode(self.cwd.as_os_str()),
+            variables: self
+                .variables
+                .iter()
+                .map(|(name, value)| (NativeOsString::encode(name), NativeOsString::encode(value)))
+                .collect(),
+        }
+        .serialize(serializer)
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for SessionEnvironment {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let wire = SessionEnvironmentWire::deserialize(deserializer)?;
+        let cwd = PathBuf::from(wire.cwd.decode().map_err(serde::de::Error::custom)?);
+        let variables = wire
+            .variables
+            .into_iter()
+            .map(|(name, value)| {
+                Ok((
+                    name.decode().map_err(serde::de::Error::custom)?,
+                    value.decode().map_err(serde::de::Error::custom)?,
+                ))
+            })
+            .collect::<Result<Vec<_>, D::Error>>()?;
+        Ok(Self::new(cwd, variables))
+    }
+}
+
+impl NativeOsString {
+    fn encode(value: &OsStr) -> Self {
+        use base64::Engine;
+        Self(base64::engine::general_purpose::STANDARD_NO_PAD.encode(native_bytes(value)))
+    }
+
+    fn decode(self) -> Result<OsString, String> {
+        use base64::Engine;
+        let bytes = base64::engine::general_purpose::STANDARD_NO_PAD
+            .decode(self.0)
+            .map_err(|error| format!("invalid native environment encoding: {error}"))?;
+        native_string(bytes)
+    }
+}
+
+#[cfg(unix)]
+pub(crate) fn native_bytes(value: &OsStr) -> Vec<u8> {
+    use std::os::unix::ffi::OsStrExt;
+    value.as_bytes().to_vec()
+}
+
+#[cfg(windows)]
+pub(crate) fn native_bytes(value: &OsStr) -> Vec<u8> {
+    use std::os::windows::ffi::OsStrExt;
+    value
+        .encode_wide()
+        .flat_map(u16::to_le_bytes)
+        .collect::<Vec<_>>()
+}
+
+#[cfg(not(any(unix, windows)))]
+pub(crate) fn native_bytes(value: &OsStr) -> Vec<u8> {
+    value.to_string_lossy().as_bytes().to_vec()
+}
+
+#[cfg(unix)]
+fn native_string(bytes: Vec<u8>) -> Result<OsString, String> {
+    use std::os::unix::ffi::OsStringExt;
+    Ok(OsString::from_vec(bytes))
+}
+
+#[cfg(windows)]
+fn native_string(bytes: Vec<u8>) -> Result<OsString, String> {
+    use std::os::windows::ffi::OsStringExt;
+    if !bytes.len().is_multiple_of(2) {
+        return Err("invalid odd-length native Windows environment value".to_string());
+    }
+    let units = bytes
+        .as_chunks::<2>()
+        .0
+        .iter()
+        .map(|pair| u16::from_le_bytes(*pair))
+        .collect::<Vec<_>>();
+    Ok(OsString::from_wide(&units))
+}
+
+#[cfg(not(any(unix, windows)))]
+fn native_string(bytes: Vec<u8>) -> Result<OsString, String> {
+    String::from_utf8(bytes)
+        .map(OsString::from)
+        .map_err(|error| format!("invalid native environment UTF-8: {error}"))
+}
+
+impl SessionEnvironment {
+    /// Captures the current process state without reading any configuration file.
+    pub fn capture() -> Result<Self, String> {
+        let cwd = std::env::current_dir()
+            .map_err(|error| format!("Cannot determine the session working directory: {error}."))?;
+        Ok(Self::new(cwd, std::env::vars_os().collect()))
+    }
+
+    /// Builds an immutable snapshot from native values received over IPC.
+    pub fn new(cwd: PathBuf, variables: Vec<(OsString, OsString)>) -> Self {
+        Self {
+            cwd,
+            variables: Arc::new(variables),
+        }
+    }
+
+    /// The exact working directory captured by the stdio proxy.
+    pub fn cwd(&self) -> &Path {
+        &self.cwd
+    }
+
+    /// The exact native environment captured by the stdio proxy.
+    pub fn variables(&self) -> &[(OsString, OsString)] {
+        self.variables.as_slice()
+    }
+
+    /// Looks up one environment value using the platform's variable-name rules.
+    pub fn var_os(&self, name: &str) -> Option<OsString> {
+        self.variables
+            .iter()
+            .rev()
+            .find(|(candidate, _)| environment_name_eq(candidate, name))
+            .map(|(_, value)| value.clone())
+    }
+
+    /// Looks up one UTF-8 environment value with `std::env::var`-compatible failures.
+    pub fn var(&self, name: &str) -> Result<String, VarError> {
+        match self.var_os(name) {
+            Some(value) => value.into_string().map_err(VarError::NotUnicode),
+            None => Err(VarError::NotPresent),
+        }
+    }
+
+    /// Replaces a child command's inherited environment with this exact snapshot.
+    pub fn configure_command(&self, command: &mut Command) {
+        command.env_clear().envs(self.variables.iter().cloned());
+    }
+
+    /// Runs synchronous work with legacy budget/path helpers bound to this connection.
+    pub(crate) fn activate<R>(self: &Arc<Self>, operation: impl FnOnce() -> R) -> R {
+        let _scope = SessionEnvironmentScope::install(Arc::clone(self));
+        operation()
+    }
+
+    fn with_guarded_output(&self, output: EffectiveOutput) -> Self {
+        if output.mode != EffectiveOutputMode::Guarded {
+            return self.clone();
+        }
+        let mut variables = self
+            .variables
+            .iter()
+            .filter(|(name, _)| !is_budget_variable(name))
+            .cloned()
+            .collect::<Vec<_>>();
+        variables.push((
+            OsString::from(GLOBAL_TOKEN_BUDGET_ENV),
+            OsString::from(output.fastctx_budget.to_string()),
+        ));
+        append_tool_budget(
+            &mut variables,
+            READ_TOKEN_BUDGET_ENV,
+            output.tool_budgets.read.resolve(output.fastctx_budget),
+        );
+        append_tool_budget(
+            &mut variables,
+            GREP_TOKEN_BUDGET_ENV,
+            output.tool_budgets.grep.resolve(output.fastctx_budget),
+        );
+        append_tool_budget(
+            &mut variables,
+            GLOB_TOKEN_BUDGET_ENV,
+            output.tool_budgets.glob.resolve(output.fastctx_budget),
+        );
+        append_tool_budget(
+            &mut variables,
+            RUN_TOKEN_BUDGET_ENV,
+            output.tool_budgets.run.resolve(output.fastctx_budget),
+        );
+        append_tool_budget(
+            &mut variables,
+            JOB_OUTPUT_TOKEN_BUDGET_ENV,
+            output
+                .tool_budgets
+                .job_output
+                .resolve(output.fastctx_budget),
+        );
+        Self::new(self.cwd.clone(), variables)
+    }
+}
+
+/// All immutable state derived once when a control-center connection is accepted.
+#[derive(Clone, Debug)]
+pub struct SessionContext {
+    /// Exact native cwd/env captured by this connection's stdio proxy.
+    ///
+    /// This stays the sole basis for FastCtx's own identity — control paths, endpoint, budgets —
+    /// so restoring the machine's persisted environment can never relocate a user's state.
+    pub environment: Arc<SessionEnvironment>,
+    /// Session state used only by FastCtx's internal path and response-budget helpers.
+    tool_environment: Arc<SessionEnvironment>,
+    /// Environment handed to commands the user runs, with the machine's persisted values restored.
+    pub command_environment: Arc<SessionEnvironment>,
+    /// Per-user paths resolved exclusively from the connection environment.
+    pub control_paths: ControlPaths,
+    /// Saved FastCtx preferences visible to this connection.
+    pub settings: FastCtxSettings,
+    /// Provider-aware output policy made for this connection.
+    pub effective_output: EffectiveOutput,
+    /// Aggregate response pool owned by this connection when Guarded is effective.
+    guarded_burst: Option<Arc<GuardedBurstPool>>,
+}
+
+impl SessionContext {
+    /// Captures and resolves one standalone server process as a single connection.
+    pub fn capture() -> Result<Arc<Self>, String> {
+        Self::from_environment(SessionEnvironment::capture()?)
+    }
+
+    /// Resolves per-user paths, settings, provider, and runtime budgets from one handshake.
+    pub fn from_environment(environment: SessionEnvironment) -> Result<Arc<Self>, String> {
+        let control_paths = control_paths_from_environment(&environment)?;
+        let settings = crate::control::settings::load(&control_paths)?;
+        let effective_output = effective_output(settings.tier, settings.tool_budgets);
+        let tool_environment = Arc::new(environment.with_guarded_output(effective_output));
+        let guarded_burst = guarded_burst_for(effective_output);
+        let command_environment =
+            Arc::new(crate::os_environment::command_environment(&environment));
+        let environment = Arc::new(environment);
+        Ok(Arc::new(Self {
+            environment,
+            tool_environment,
+            command_environment,
+            control_paths,
+            settings,
+            effective_output,
+            guarded_burst,
+        }))
+    }
+
+    /// Best-effort context used only by direct library constructors that cannot return startup errors.
+    pub(crate) fn library_default() -> Arc<Self> {
+        Self::capture().unwrap_or_else(|_| {
+            let environment = SessionEnvironment::capture().unwrap_or_else(|_| {
+                SessionEnvironment::new(PathBuf::from("."), std::env::vars_os().collect())
+            });
+            let home = environment
+                .var_os("HOME")
+                .filter(|value| !value.is_empty())
+                .or_else(|| {
+                    environment
+                        .var_os("USERPROFILE")
+                        .filter(|value| !value.is_empty())
+                })
+                .map(PathBuf::from)
+                .unwrap_or_else(|| environment.cwd().to_path_buf());
+            let control_paths = ControlPaths::for_home(home);
+            let settings = FastCtxSettings::default();
+            let effective_output = effective_output(settings.tier, settings.tool_budgets);
+            let tool_environment = Arc::new(environment.with_guarded_output(effective_output));
+            let guarded_burst = guarded_burst_for(effective_output);
+            let command_environment =
+                Arc::new(crate::os_environment::command_environment(&environment));
+            Arc::new(Self {
+                tool_environment,
+                command_environment,
+                environment: Arc::new(environment),
+                control_paths,
+                settings,
+                effective_output,
+                guarded_burst,
+            })
+        })
+    }
+
+    /// Runs synchronous FastCtx work with this connection's cwd and effective response budgets.
+    pub(crate) fn activate<R>(&self, operation: impl FnOnce() -> R) -> R {
+        self.tool_environment.activate(operation)
+    }
+
+    /// Effective per-tool shares retained for diagnostics and tests.
+    pub fn tool_budgets(&self) -> ToolBudgets {
+        self.effective_output.tool_budgets
+    }
+
+    /// Registers one tool response with this connection's Guarded burst, when active.
+    pub(crate) fn begin_guarded_response(&self) -> Option<BurstTicket> {
+        self.guarded_burst.as_ref().map(GuardedBurstPool::begin)
+    }
+}
+
+fn guarded_burst_for(output: EffectiveOutput) -> Option<Arc<GuardedBurstPool>> {
+    if output.mode != EffectiveOutputMode::Guarded {
+        return None;
+    }
+    Some(GuardedBurstPool::new(output.fastctx_budget, BURST_GAP))
+}
+
+struct SessionEnvironmentScope {
+    previous: Option<Arc<SessionEnvironment>>,
+}
+
+impl SessionEnvironmentScope {
+    fn install(environment: Arc<SessionEnvironment>) -> Self {
+        let previous = ACTIVE_ENVIRONMENT.with(|slot| slot.borrow_mut().replace(environment));
+        Self { previous }
+    }
+}
+
+impl Drop for SessionEnvironmentScope {
+    fn drop(&mut self) {
+        ACTIVE_ENVIRONMENT.with(|slot| *slot.borrow_mut() = self.previous.take());
+    }
+}
+
+/// Clones the active connection environment for work that must cross a thread boundary.
+#[cfg(feature = "pdf")]
+pub(crate) fn active_environment() -> Option<Arc<SessionEnvironment>> {
+    ACTIVE_ENVIRONMENT.with(|slot| slot.borrow().clone())
+}
+
+/// Returns the active connection cwd, falling back only for non-daemon library/control callers.
+pub(crate) fn current_dir() -> std::io::Result<PathBuf> {
+    ACTIVE_ENVIRONMENT.with(|slot| {
+        slot.borrow()
+            .as_ref()
+            .map(|environment| environment.cwd.clone())
+            .map(Ok)
+            .unwrap_or_else(std::env::current_dir)
+    })
+}
+
+/// Returns an active native environment value, falling back only outside a tool request.
+#[cfg(feature = "pdf")]
+pub(crate) fn var_os(name: &str) -> Option<OsString> {
+    ACTIVE_ENVIRONMENT.with(|slot| match slot.borrow().as_ref() {
+        Some(environment) => environment.var_os(name),
+        None => std::env::var_os(name),
+    })
+}
+
+/// Returns an active connection variable, falling back only outside a tool request.
+pub(crate) fn var(name: &str) -> Result<String, VarError> {
+    ACTIVE_ENVIRONMENT.with(|slot| {
+        slot.borrow()
+            .as_ref()
+            .map(|environment| environment.var(name))
+            .unwrap_or_else(|| std::env::var(name))
+    })
+}
+
+/// Resolves a temporary directory from the active session without consulting daemon state.
+#[cfg(feature = "pdf")]
+pub(crate) fn temp_dir() -> PathBuf {
+    let Some(environment) = active_environment() else {
+        return std::env::temp_dir();
+    };
+    let names: &[&str] = if cfg!(windows) {
+        &["TMP", "TEMP"]
+    } else {
+        &["TMPDIR", "TMP", "TEMP"]
+    };
+    if let Some(path) = names
+        .iter()
+        .filter_map(|name| environment.var_os(name))
+        .find(|value| !value.is_empty())
+        .map(PathBuf::from)
+    {
+        return if path.is_absolute() {
+            path
+        } else {
+            environment.cwd().join(path)
+        };
+    }
+    #[cfg(windows)]
+    {
+        environment
+            .var_os("USERPROFILE")
+            .filter(|value| !value.is_empty())
+            .map(PathBuf::from)
+            .map(|path| path.join("AppData/Local/Temp"))
+            .unwrap_or_else(|| environment.cwd().join(".fastctx-tmp"))
+    }
+    #[cfg(not(windows))]
+    {
+        PathBuf::from("/tmp")
+    }
+}
+
+fn control_paths_from_environment(
+    environment: &SessionEnvironment,
+) -> Result<ControlPaths, String> {
+    let home = environment
+        .var_os("HOME")
+        .filter(|value| !value.is_empty())
+        .or_else(|| {
+            environment
+                .var_os("USERPROFILE")
+                .filter(|value| !value.is_empty())
+        })
+        .map(PathBuf::from)
+        .ok_or_else(|| {
+            "Cannot determine the user home directory. Set HOME or USERPROFILE and retry."
+                .to_string()
+        })?;
+    Ok(ControlPaths::for_home(home))
+}
+
+fn append_tool_budget(
+    variables: &mut Vec<(OsString, OsString)>,
+    name: &'static str,
+    value: Option<usize>,
+) {
+    if let Some(value) = value {
+        variables.push((OsString::from(name), OsString::from(value.to_string())));
+    }
+}
+
+fn is_budget_variable(name: &OsStr) -> bool {
+    [
+        GLOBAL_TOKEN_BUDGET_ENV,
+        READ_TOKEN_BUDGET_ENV,
+        GREP_TOKEN_BUDGET_ENV,
+        GLOB_TOKEN_BUDGET_ENV,
+        RUN_TOKEN_BUDGET_ENV,
+        JOB_OUTPUT_TOKEN_BUDGET_ENV,
+    ]
+    .iter()
+    .any(|candidate| environment_name_eq(name, candidate))
+}
+
+#[cfg(windows)]
+pub(crate) fn environment_name_eq(candidate: &OsStr, expected: &str) -> bool {
+    candidate
+        .to_str()
+        .is_some_and(|candidate| candidate.eq_ignore_ascii_case(expected))
+}
+
+#[cfg(not(windows))]
+pub(crate) fn environment_name_eq(candidate: &OsStr, expected: &str) -> bool {
+    candidate == OsStr::new(expected)
+}
+
+/// Compares two native variable names under the same rules `environment_name_eq` applies.
+pub(crate) fn environment_name_eq_os(candidate: &OsStr, expected: &OsStr) -> bool {
+    match expected.to_str() {
+        Some(expected) => environment_name_eq(candidate, expected),
+        None => candidate == expected,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{EffectiveOutputMode, SessionContext, SessionEnvironment};
+    use crate::budget::{GLOBAL_TOKEN_BUDGET_ENV, GREP_TOKEN_BUDGET_ENV, tool_token_budget};
+    use crate::control::settings::Tier;
+    use std::ffi::OsString;
+    use std::path::PathBuf;
+    use std::sync::Arc;
+
+    #[test]
+    fn session_resolves_the_selected_tier_and_preserves_native_state() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path().join("home");
+        std::fs::create_dir_all(&home).unwrap();
+        let environment = SessionEnvironment::new(
+            temp.path().to_path_buf(),
+            vec![
+                (OsString::from("HOME"), home.into_os_string()),
+                (
+                    OsString::from(GLOBAL_TOKEN_BUDGET_ENV),
+                    OsString::from("54000"),
+                ),
+                (
+                    OsString::from(GREP_TOKEN_BUDGET_ENV),
+                    OsString::from("10800"),
+                ),
+                (OsString::from("SESSION_SENTINEL"), OsString::from("kept")),
+            ],
+        );
+
+        let session = SessionContext::from_environment(environment).unwrap();
+        assert_eq!(
+            session.effective_output.mode,
+            EffectiveOutputMode::SelectedTier
+        );
+        assert_eq!(
+            session.tool_budgets(),
+            Tier::Standard.default_budgets(),
+            "a default profile follows the standard tier's recommended shares"
+        );
+        assert_eq!(
+            session.environment.var(GLOBAL_TOKEN_BUDGET_ENV).unwrap(),
+            "54000"
+        );
+        assert_eq!(
+            session.environment.var(GREP_TOKEN_BUDGET_ENV).unwrap(),
+            "10800"
+        );
+        assert_eq!(session.environment.var("SESSION_SENTINEL").unwrap(), "kept");
+        session.activate(|| {
+            assert_eq!(
+                tool_token_budget(GREP_TOKEN_BUDGET_ENV).unwrap().value,
+                10_800
+            );
+        });
+    }
+
+    #[test]
+    fn nested_activation_restores_the_outer_connection() {
+        let first = Arc::new(SessionEnvironment::new(
+            PathBuf::from("first"),
+            vec![(OsString::from("MARK"), OsString::from("first"))],
+        ));
+        let second = Arc::new(SessionEnvironment::new(
+            PathBuf::from("second"),
+            vec![(OsString::from("MARK"), OsString::from("second"))],
+        ));
+        first.activate(|| {
+            assert_eq!(super::var("MARK").unwrap(), "first");
+            second.activate(|| assert_eq!(super::var("MARK").unwrap(), "second"));
+            assert_eq!(super::var("MARK").unwrap(), "first");
+        });
+    }
+
+    #[test]
+    fn environment_json_round_trip_preserves_native_values() {
+        let environment = SessionEnvironment::new(
+            PathBuf::from("workspace"),
+            vec![(OsString::from("NAME"), OsString::from("value"))],
+        );
+        let encoded = serde_json::to_vec(&environment).unwrap();
+        let decoded: SessionEnvironment = serde_json::from_slice(&encoded).unwrap();
+        assert_eq!(decoded, environment);
+    }
+}

package/vendor/fastctx/src/shell/apply_patch_hint.rs

@@ -0,0 +1,41 @@
+// Modified by dsh-ops (https://github.com/T-Auto/dsh-ops): the apply_patch misuse note points at the host's own tool instead of Codex's built-in shell.
+//! Recognition of the host's `apply_patch` editing channel being run as a shell program.
+
+const CHANNEL_NAME: &str = "apply_patch";
+const MISUSE_NOTE: &str = "(Note: apply_patch is not a program and no shell can run it. Reach it through your host's own apply_patch tool call, not through this tool.)";
+
+/// Returns the guidance note for a failed command that reads as an attempt to run `apply_patch`.
+///
+/// The host resolves `apply_patch` on its own shell channel before any real bash sees it, so the
+/// word only ever reaches a shell when it is routed through a tool the host does not inspect —
+/// and bash then reports it as a missing command. The note stays tentative and never blocks the
+/// command, because a user may legitimately own an executable by that name: it appears only after
+/// the command has actually failed, so a working script is never interrupted or second-guessed.
+pub(crate) fn misuse_note(
+    command: &str,
+    exit_code: i32,
+    timeout_ms: Option<u64>,
+) -> Option<String> {
+    let failed_on_its_own = timeout_ms.is_none() && exit_code != 0;
+    (failed_on_its_own && invokes_channel(command)).then(|| MISUSE_NOTE.to_string())
+}
+
+/// Reports whether any command position in the line starts the bare `apply_patch` word.
+///
+/// Splitting on shell separators keeps `echo apply_patch` and `/usr/bin/apply_patch` out: the
+/// first is not in command position, the second names a real executable the user does own.
+fn invokes_channel(command: &str) -> bool {
+    command.contains(CHANNEL_NAME)
+        && command
+            .split([';', '&', '|', '\n', '(', '{'])
+            .any(|segment| leading_word(segment) == CHANNEL_NAME)
+}
+
+/// Extracts the first word of a segment, stopping at whitespace or a redirection operator.
+fn leading_word(segment: &str) -> &str {
+    let trimmed = segment.trim_start();
+    let end = trimmed
+        .find(|character: char| character.is_whitespace() || character == '<' || character == '>')
+        .unwrap_or(trimmed.len());
+    &trimmed[..end]
+}