Daemon State

Background Agent execution relies on a set of daemon state files.

Those files tell the CLI:

• whether the target agent is running
• which pid is associated with it
• what startup metadata exists

Why stale happens

Stale usually means:

• the state files still exist
• but the underlying daemon process does not

Common causes:

• abnormal process exit
• machine restart
• incomplete cleanup from a previous launch

This is usually a state-consistency issue, not a broken project configuration issue.

Recommended recovery sequence

city agent status
city agent doctor --fix
city agent start

That order is useful because it first restores state consistency, then restores execution.

When you should not touch daemon state

If the state is already running or stopped, daemon files are usually not the first thing to touch.

If behavior is wrong but daemon state is healthy, the better next suspects are:

• model binding
• prompts
• channel binding
• session history

Continue with:

• city agent doctor
• Agent won't start