the running Agent timed out before semantic capture could…

Error message

the running Agent timed out before semantic capture could begin

What it means

After connecting, `capture_connected_profile` asks the agent to register the CLI as a client via `declare_client`, wrapped in a `DECLARE_TIMEOUT`. If the future does not resolve before the timeout (the outer `Err` of `tokio::time::timeout`), this error fires; the inner `Err` (agent-side rejection/disconnect) produces the sibling 'disconnected' error instead.

Solutions

Retry the command — transient stalls often clear
Restart the agent to free its blocked event loop
Increase headroom by closing other CLI clients doing hardware diagnostics against the same agent
If reproducible, investigate the agent's event loop for blocking calls in HID write paths

Defensive patterns

Strategy: retry

Validate before calling

// only attempt capture when the agent is responsive
match tokio::time::timeout(Duration::from_secs(2), connect_probe()).await {
    Ok(_) => println!("agent responsive"),
    Err(_) => eprintln!("agent unresponsive; restart before capture"),
}

Try / catch

for attempt in 0..2 {
    match capture_connected_profile(&conn, ...).await {
        Err(e) if e.to_string().contains("timed out before semantic capture") && attempt == 0 => continue,
        other => break other,
    }
}

Prevention

Avoid running heavy hardware diagnostics against the agent during capture
Check for system sleep/resume issues in long sessions
Investigate blocking HID writes in the agent if timeouts reproduce

When it happens

Trigger: The agent's tarpc response to `declare_client` never arrives within `DECLARE_TIMEOUT` — agent event loop blocked (busy doing HID I/O or a hook stall), hung tarpc channel, or a very slow/loaded machine.

Common situations: Agent wedged by a blocking HID write, system sleep/resume leaving the IPC channel half-dead, heavy CPU load at capture start, or an agent that accepted the connection but stopped servicing requests.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of AprilNEA/OpenLogi@e846e6f4b4 (2026-09-13). Data as JSON: /api/errors/f48ace2a090e64be. Report an issue: GitHub.

Appendix: source

Thrown at crates/openlogi-cli/src/cmd/fixture/record_profile.rs:142

    id: String,
    name: String,
) -> Result<CapturedProfile> {
    if connection.version != PROTOCOL_VERSION {
        bail!(
            "the running Agent speaks protocol v{}, but this CLI requires v{PROTOCOL_VERSION}; \
             update or restart OpenLogi so both processes match (no profile was written)",
            connection.version
        );
    }

    tokio::time::timeout(
        DECLARE_TIMEOUT,
        connection
            .client
            .declare_client(context::current(), ClientKind::Cli),
    )
    .await
    .map_err(|_| anyhow!("the running Agent timed out before semantic capture could begin"))?
    .map_err(|_| anyhow!("the running Agent disconnected before semantic capture could begin"))?;

    let snapshot = tokio::time::timeout(
        SNAPSHOT_TIMEOUT,
        connection.client.snapshot(context::current()),
    )
    .await
    .map_err(|_| anyhow!("the running Agent timed out while providing its device snapshot"))?
    .map_err(|_| anyhow!("the running Agent disconnected while providing its device snapshot"))?;

    let captured = capture_profile(&connection.client, snapshot, selector, id, name).await?;
    captured
        .profile
        .validate()
        .context("captured semantic profile failed version-1 validation; no profile was written")?;
    Ok(captured)
}

View on GitHub (pinned to e846e6f4b4)