Process Lifecycle

Braide runs each agent and each terminal as a child process. This page describes what happens when those processes start, when they exit, and what guarantees you can rely on — particularly if you're running Braide headless on Linux or scripting around it.

Agent startup

When you enable an agent (or when Braide restarts and restores agents from your saved settings), the agent goes through a short startup sequence:

1. Download — If the agent ships as a binary, Braide downloads it the first time you enable it and caches it for subsequent runs. Agents that run through npx or uvx skip this step.
2. Spawn — The agent binary is launched as a child process with its own process group, so any sub-processes it spawns (such as language servers, or the JVM for agents like Junie) can be cleaned up together later. The child inherits Braide's captured login-shell environment (minus a few host-internal variables), so credentials and tooling you set in your shell profile are available to the agent even when Braide was launched from the Dock.
3. Handshake — Braide negotiates the ACP protocol with the agent. Once the handshake succeeds the agent is ready, and the Process Manager in Settings shows it as running.

Auto-restart on unexpected exit

If a running agent exits unexpectedly — crash, killed by the OS, network drop on a remote — Braide tries to restart it automatically with exponential backoff:

Attempt	Delay before retry
1st	1 second
2nd	2 seconds
3rd	4 seconds

After three failed attempts the agent moves to error state and stays there until you manually restart it from the Process Manager. A successful handshake at any point resets the counter.

If you stop the agent yourself (toggle it off, or click Stop), Braide does not auto-restart it.

Agent shutdown

When you quit Braide, disable an agent, or stop one from the Process Manager, the agent goes through a layered shutdown so it has a chance to flush state but cannot block you forever:

1. Graceful session close — Sessions the agent is hosting are closed cleanly if the agent supports it. This gives the agent a chance to persist conversation state. Bounded to 3 seconds.
2. SIGTERM to the process group — The whole process group is signalled, not just the top-level process. Any sub-processes the agent spawned (language servers, sandboxes, JVMs) receive the signal too, so nothing is orphaned.
3. 5-second grace period — Braide waits up to 5 seconds for the process to exit cleanly.
4. SIGKILL to the process group — If the process hasn't exited within the grace period, it is force-killed along with its entire process group.

When the whole Braide server is shutting down, an overall 10-second cap applies: if every agent hasn't shut down within 10 seconds, Braide exits anyway. This prevents a single unresponsive agent from blocking quit indefinitely.

Terminal shutdown

Terminal processes (PTY shells, both interactive and agent-spawned) follow the same process-group shutdown pattern: SIGHUP first (or SIGTERM for non-PTY terminals), a 5-second grace period, then SIGKILL. Anything you started inside the terminal — long-running commands, background jobs — receives the signal too, so closing a terminal cleans up its children.

Signals (Linux / headless)

If you're running the Braide server directly rather than the desktop app, you can shut it down with any of these signals. All trigger the same graceful sequence and exit with code 0:

Signal	When you'd send it
SIGTERM	Standard "please stop" — what systemctl stop and kill send.
SIGINT	Ctrl+C in the foreground terminal.
SIGUSR2	Used by nodemon and similar tools for graceful restarts.

If Braide itself crashes (an uncaught exception or unhandled promise rejection), it logs a fatal error and exits with code 1 after running shutdown. The FATAL line is also written synchronously to ~/.braide/logs/braide-crash.log (or electron-main-crash.log for crashes in the desktop app's main process) so the record survives even an abrupt exit — see Crash Logs. Signal handlers are idempotent — sending SIGTERM twice doesn't double the shutdown, it just confirms you really meant it.

What you can rely on

• No orphaned children. Killing an agent or terminal also kills everything it spawned, on macOS and Linux alike, because Braide signals the process group.
• Bounded shutdown. Nothing in the shutdown path can hang Braide for more than 10 seconds; an unresponsive agent is force-killed rather than blocking quit.
• Crash recovery. A crashed agent is restarted up to three times with backoff before Braide gives up; you don't need to babysit short-lived process failures.

If you're seeing different behaviour — orphaned node or java processes after quitting Braide, agents that never restart, or shutdown that hangs — that's a bug. Capture the logs and file an issue.