Skip to content

Gas City Command Execution Trust Boundaries

Scope: Every Gas City execution surface Bluefly runs against — city config, imported Packs, exec provider scripts, agent startup commands, hooks, order checks/exec, and gc sling//sling. Upstream authority: docs.gascity.com/reference/trust-boundaries. This document does not define Gas City's execution or trust model — Gas City owns that contract. The body below is Gas City's own published doctrine, reproduced here verbatim because Bluefly agents author providers, hooks, order exec, and sling commands against these surfaces and need the rules inline, not one click away. Attribution: Gas City upstream doctrine, not Bluefly-authored. Do not edit the reproduced body to change its substance — only update this file's own frontmatter/cross-link scaffolding. If upstream revises the doctrine, replace the body wholesale and note the source revision, do not hand-patch it out of sync with upstream.

Bluefly's own related, Bluefly-authored constitutions build on top of this doctrine rather than restating it: Authentication & Secrets Constitution (1Password authority, secret reference rules) and Tools Standard (op run vs op read, proving secret state without revealing it). Where those documents and this one overlap on secret hygiene, this document is the Gas City-side execution-surface authority; the Bluefly constitutions are the 1Password/operator-side authority. Also see the Bluefly-side execution-diagnostics rule (SECRET-SAFE HTTP AND SHELL RULE: curl -v/--trace/--include/set -x/bash -x banned for credential-bearing commands) enforced locally in agent tooling — same principle, applied to HTTP/shell diagnostics rather than Gas City exec surfaces.

Cross-referenced from: BluCity Operator Contract §11 Order, §14 Agent, §16 Provider, §17 Hook, §18 Sling; and Gas City Adoption.

Gas City Upstream Doctrine (verbatim)

Gas City intentionally runs operator-configured commands. Those commands are a feature, not a sandbox. Treat city config, imported packs, exec provider scripts, and agent startup commands as trusted code with the same review expectations as shell scripts committed to the repository.

Trust model

  • Maintainer-authored city config and local site config: Trusted operator code. May define shell commands and explicit env. Review before use.
  • Imported packs and rig configs: Trusted dependency code. Pin/review packs before importing into a privileged city.
  • Bead titles, descriptions, mail, formula vars, PR text, and API request fields: Untrusted data. Do not concatenate into shell commands. Pass as env, JSON, stdin, or argv.
  • GitHub Actions pull_request_target payloads: Untrusted data in a privileged workflow. Do not checkout or execute contributor code. Use metadata-only operations.
  • Ambient process environment: Untrusted for secret propagation. Orchestrator-side shell helpers strip inherited secret-looking env keys by default.

Execution surfaces

Surface Command source Actor Working directory Env behavior Log behavior
work_query via gc hook and orchestrator probes Agent config Trusted operator or pack Agent's canonical city or rig repo Inherited secrets stripped, Gas City projects explicit store/session env Errors diagnostic only, avoid secrets in command literals
scale_check Agent config Trusted operator or pack Agent's canonical city or rig repo Inherited secrets stripped, explicit store env Parse failures include command context, command literals must not contain secrets
on_boot and on_death Agent pool config Trusted operator or pack City or rig repo Inherited secrets stripped, explicit store env may be provided Hook failures logged, output should not include secrets
Order check triggers Order config Trusted operator or pack Order target scope Inherited secrets stripped, explicit condition env may be provided Failure reason records exit status not command output
Order exec Order config Trusted operator or pack Order target scope Inherited secrets stripped, explicit order env may be provided Failure errors and output redacted before logs/events
gc sling and /sling command runner Sling target config Trusted operator or pack City or rig repo Inherited secrets stripped, explicit routing/store env may be provided Returned command output is caller-visible, do not route untrusted text into shell
Agent command Agent config Trusted operator or pack Session work directory Session env is explicit runtime env plus configured env, secrets may be passed only by intentional config Agent stdout/stderr is session output, may be visible to operators
pre_start Agent config Trusted operator or pack Session work directory Provider-specific runtime env, intended for setup before session start Provider warnings should avoid secrets
session_setup, session_setup_script, session_live Agent config Trusted operator or pack Running session environment Provider-specific runtime env, remote providers run inside target container or pod Provider warnings should avoid secrets
exec: session provider User-supplied provider script Trusted operator code Provider-defined Direct exec not sh -c, start config is JSON on stdin Provider stderr may be surfaced in errors, do not print secrets
exec: beads, mail, and events providers User-supplied provider script Trusted operator code Provider-defined Direct exec not sh -c, request data is stdin/argv Provider stderr may be surfaced in errors, do not print secrets
Pack fetch/include, Git probes, Docker, Dolt, tmux, kubectl, bd helpers Gas City code plus configured paths/URLs Maintainer-reviewed code paths Command-specific Direct exec with argv except provider setup scripts where documented Errors surfaced for diagnosis, avoid embedding credentials in URLs

Secret propagation

Orchestrator-side shell helpers remove inherited environment variables whose keys look secret-bearing, including names containing TOKEN, PASSWORD, SECRET, PRIVATE_KEY, API_KEY, ACCESS_KEY, CREDENTIAL, OAUTH, or AUTH_JSON. This prevents ambient CI or maintainer shell secrets from reaching work_query, scale_check, hooks, order checks, order exec commands, and sling helpers by accident. If a command truly needs a secret, pass it explicitly through the relevant city, rig, provider, or workflow configuration. Explicit values are preserved because they represent an operator decision, and failure logs redact known secret values before writing order exec errors or events.

Rules for authors

  • Do not put secrets directly in command strings. Use env variables or provider credential files.
  • Do not interpolate bead content, PR text, mail, formula vars, branch names, or other user-controlled values into sh -c commands.
  • When showing a command for a human to copy, build it from argv and quote each argument with Gas City's shell quoting helper.
  • Keep pull_request_target workflows metadata-only. They may label or comment but must not checkout or run contributor code with privileged tokens.
  • Prefer direct exec.Command(..., args...) style boundaries for new provider contracts. Use sh -c only for explicitly operator-authored shell snippets.

ADR-0008 and Gas City Adoption establish "one authority, many projections — link, do not rewrite" for Gas City product behavior (CLI, config schema, formulas, troubleshooting), because that behavior changes and a local paraphrase drifts. This document is different in kind: it is a fixed security contract governing how any author — Gas City core, a Pack, or a Bluefly agent — must write exec surfaces. Bluefly agents write provider scripts, order exec, hooks, and sling handlers against these exact surfaces today, so the full rule set is reproduced here rather than left as an external link only. If upstream revises the trust model, this file must be re-synced from source, not hand-patched independently.