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.

Renderer crash recovery

If the desktop app's renderer crashes, Braide shows recovery actions while keeping the backend running where possible. Show Crash Report opens the preserved native crash report, and Show Logs opens the logs directory; after either action, the recovery dialog appears again so you can still choose Reload Braide without losing the background processes. Choose Quit only when you want to stop the application instead.

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 40-second cap applies: if shutdown hasn't completed within that budget, Braide exits anyway. This prevents a single unresponsive agent — or a stuck background task — from blocking quit indefinitely.

Finishing background work before exit

Some work must not be interrupted mid-way. Archiving a session, for example, stashes uncommitted changes, removes the worktree directory, renames the branch, and only then flips the session to its archived state — and worktree removal on a large tree can take 10+ seconds. If that work were cut off by shutdown, the session would be left half-archived and would surface an "archive interrupted before completion" error on the next launch.

To prevent this, Braide drains in-flight background work first when it shuts down:

1. Any tracked background task (archive teardown, deletion cleanup, GitHub label updates) is allowed up to 30 seconds to reach a safe commit point before the runtime is torn down.
2. Only after the drain completes (or its 30-second budget elapses) are the agent processes stopped and the runtime disposed.

While this is happening, the desktop app shows a shutdown overlay that lists what is still finishing (for example, Archiving session "my-feature"), so quit never looks frozen — you can see it is waiting on real work rather than hung. The overall 40-second cap still bounds the whole sequence.

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 40 seconds; in-flight background work (such as archiving) is given up to 30 seconds to finish cleanly, after which an unresponsive agent or task is force-killed rather than blocking quit.
• No half-done archives. Archive and deletion work is drained before the runtime is torn down, so quitting mid-archive doesn't leave a session stuck in a transitional state.
• 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.