Operational stdio shutdown

guildctl serve starts one five-second shutdown deadline when its input ends, either protocol pipe fails or closes, or it receives SIGINT or SIGTERM. Repeated triggers share the first shutdown and do not extend its deadline. The runner stops admitting tool work and starts Gateway, native Interaction, and MCP cleanup concurrently. Admitted tool handlers may finish within the same deadline. Final telemetry waits for those handlers and native Interaction and MCP cleanup, so their completion evidence is included; a stalled Gateway does not prevent that flush.

The runner writes one content-free JSON stdio-shutdown record to stderr, including when optional JSON operation logging is disabled. It contains schemaVersion, a random shutdownId, the fixed trigger reason, overall status, deadlineMs, durationMs, activeTools, and fixed component names with statuses and elapsed durations. Overall status is complete, failed, or timeout; component status is waiting, running, complete, or failed. A waiting or running component at the deadline has not demonstrated completion. The record excludes tool arguments, raw errors, tokens, Discord identifiers, content, and local paths. Stdout remains reserved for MCP frames.

The executable exits with status 0 after complete cleanup, or 1 after a pipe error, startup failure, failed cleanup, or deadline expiry. A timeout does not establish whether an interrupted Discord write succeeded. Shutdown does not delete or finalize pending durable receipts, release uncertain coordination claims, retry mutations, or roll back Discord effects. Preserve the original request and use the affected workflow's receipt verification and coordination recovery procedures before considering further writes. Ephemeral native Interaction requests and continuations retain the broker's existing expiry and disposal rules.

Programmatic runGuildControlServer() callers receive an idempotent close() promise and a closed promise containing the terminal report. close() rejects with StdioShutdownError after failure or timeout; closed always resolves. Embedded use leaves process signals and process exit to the caller. exitOnShutdown: true explicitly transfers that ownership to the runner. The optional programmatic shutdownTimeoutMs can shorten the deadline for controlled integrations; it cannot disable or lengthen it. A timed-out embedded cleanup can still be running, and late settlement does not revise its terminal report. The deadline requires a responsive event loop and cannot preempt synchronous blocking or an operating-system force kill.

Canonical source: docs/reference.md