# summary

Launch an allow-listed long-running command in a durable background lane.

# description

Delegates a long-running, side-effecting command (Salesforce metadata retrieve/deploy, package operations, or a project build) to the running setup-agents bridge server, which executes it as a detached process that OUTLIVES the current chat turn.

This exists so work the agent starts inside a chat turn — `sf project retrieve start`, `sf project deploy start`, `npm run build` — is not killed when the turn ends, when the user hits Stop, when the idle session is reaped, or when the session respawns on the next message.

The command after `--` must match the background allow-list: `sf project ...`, `sf package ...`, `npm run build`, or `yarn build`. Anything else is rejected. Lifecycle (started/completed/failed) is reported to the web console via the bridge's spawn event stream.

Requires a running bridge (`sf setup-agents serve`). The bridge port is discovered from the `SETUP_AGENTS_BRIDGE_PORT` environment variable, or supplied with `--port`.

# flags.label.summary

Human-friendly label shown in the chat UI for this background task.

# flags.port.summary

Bridge server port. Defaults to SETUP_AGENTS_BRIDGE_PORT, then 4195.

# flags.chat-session.summary

Originating chat session id, used to correlate the background task to the chat panel.

# examples

- Run a metadata retrieve in the background:

  <%= config.bin %> <%= command.id %> --label "Retrieve Apex" -- sf project retrieve start -m ApexClass

- Run a project build in the background:

  <%= config.bin %> <%= command.id %> -- npm run build

# error.noCommand

No command provided. Pass the command after `--`, e.g. `background run -- sf project retrieve start`.

# error.noBridge

Could not reach the bridge server on port %s. Start it with `sf setup-agents serve`, or pass --port.

# error.rejected

Background command rejected: %s

# info.launched

Background task %s launched: %s