Skip to content

STD-AMUX-001: amux Session Control & Human UX Substrate Integration Standard

Status: Canonical & Binding
Standard ID: STD-AMUX-001
Owner: Durable Work Gov (DURABLE_WORK_GOVERNANCE)
Scope: All autonomous agents, session runtimes, human operators, and Gas City providers across the Bluefly estate.

1. Prime Directive & Purpose

Gas City is the sole Orchestrator. Beads in Dolt is the sole Work Authority. amux is strictly an ephemeral session/process execution substrate and human mobile/web UX layer.

This standard establishes the binding governance law for integrating amux (mixpeek/amux) into the Bluefly Factory. It enables remote, always-on operator visibility and session steering from mobile and desktop devices without allowing amux to create a competing control plane, second task board, or alternative work authority.

AMUX_SESSION_CONTROL=YES
AMUX_WORK_AUTHORITY=NO

2. Core Authority Invariants

To maintain factory integrity, the functional responsibilities between Gas City and amux are strictly separated:

Concern Authoritative System amux Permitted Role Explicit Negative Rule
Work Authority (WHAT) Beads / Dolt (127.0.0.1:3308/hq) None AMUX_BOARD_AS_WORK_AUTHORITY=NO
AMUX_BOARD_CLAIMS=NO
AMUX_TODO_STATE=NO
Orchestration & Dispatch (WHO/HOW/WHERE) Gas City (/opt/bluefly/blucity) None AMUX_ORCHESTRATOR=NO
AMUX_AUTONOMOUS_LOOPS=NO
Agent Identity & Provenance Gas City (BEADS_ACTOR, gt whoami) Display label only AMUX_SESSION_NAME_AS_IDENTITY=NO
Worktree Lifecycle Gas City managed (.gc/worktrees/) None AMUX_WORKTREES=NO
Agent-to-Agent Coordination Gas City Mail (gc mail) None AMUX_MESSAGES_AS_AGENT_BUS=NO
Shared Knowledge & Standards BluCity-Docs / GitLab None AMUX_NOTES_AS_AUTHORITY=NO
Capabilities & Skills Gas City Formulas / Bluefly Packs Thin UI aliases only AMUX_SKILLS_AS_AUTHORITY=NO
Session Execution Substrate amux / tmux Process multiplexing, start/stop/attach, live output capture PROCESS_LIFECYCLE_OVER_WORK=NO
Operator Remote UX amux Web Dashboard / PWA Mobile terminal viewing, interactive steering, session health OPERATOR_ROUTING_BURDEN=NO

3. Negative Architecture Law (Strict Prohibitions)

The following capabilities of upstream amux are strictly forbidden from Factory governance:

  1. Zero SQLite Board Usage: The amux SQLite Kanban board (~/.amux/board/) MUST NOT be used for tracking Bluefly tasks. No synchronizers, mirrors, or export bridges may be constructed between Beads and amux SQLite.
  2. Zero Worktree Creation: Neither amux nor worker CLI runtimes may invoke git worktree add or manage private worktree paths. All execution occurs inside Gas City-provisioned bead-scoped worktrees.
  3. Zero Competing Message Bus: Agents must never use amux inter-session channels for durable coordination. All inter-agent requests and completions use Gas City Mail (gc mail).
  4. Zero Knowledge Duplication: amux Notes and Global Memory must not duplicate BluCity-Docs or Beads execution context.

4. Host Placement & Network Topology

4.1 Deployment Host: Oracle (bluefly-platform)

  • amux serve runs directly on Oracle (bluefly-platform, 100.74.177.6), the authoritative Gas City execution host where Dolt hq, Rigs, and canonical checkouts reside.
  • Why Oracle: Upstream amux manages sessions via local tmux multiplexing. Running on Oracle allows direct session attachment without requiring custom SSH proxies, network relays, or repository cloning onto NAS.
  • NAS Role: Synology DS224+ remains dedicated to backups, file storage, and platform monitoring. It is not an LLM inference host or secondary City.

4.2 Network & Access Control: Private Tailscale Only

  • The amux dashboard binds strictly to local interfaces and the Tailscale IP (100.74.177.6:8822).
  • Public internet exposure, Cloudflare tunnels, and router port-forwards are strictly prohibited (PUBLIC_INTERNET_EXPOSURE=NO).
  • Operators access the dashboard securely via Tailscale HTTPS (https://bluefly-platform.tailcf98b3.ts.net:8822) using native Tailscale TLS certificates.

5. Economic Policy & Zero-Cost Model Gate

MODEL_COST_USD=0
PAID_PROVIDER_CONFIGURED=NO
  1. Free Inference Tier Only: Worker agents execute using Antigravity / Gemini CLI (gemini) configured with free-tier Gemini models (gemini-2.5-flash, gemini-2.5-pro via Google AI Studio).
  2. Fail-Closed on Quota: If free-tier API quotas (15 RPM / 1M TPM / 1500 RPD) are exhausted, the agent MUST transition to BLOCKED / WAIT. Silent or automatic failover to paid API keys, OpenRouter credits, Claude API, or OpenAI API is strictly prohibited.
  3. Budget Configuration: amux server budget caps MUST be pinned to $0.

6. Initial Fleet Sizing (Phase 1)

To prevent resource contention and runaway token consumption, Phase 1 is strictly capped at two active agent roles:

ACTIVE_IMPLEMENTATION_AGENTS=1
ACTIVE_WITNESS_AGENTS=1
  1. Implementation Worker (organization.drupal / general.worker):
  2. Claims assigned Bead from Gas City / Beads.
  3. Executes inside Gas City-managed worktree.
  4. Runs tests, generates diff, commits, and opens GitLab MR.
  5. Notifies Coordinator via Gas City Mail.
  6. Independent Witness (organization.witness):
  7. Does NOT implement code.
  8. Validates MR diff, executes verification recipes, checks pipeline green, and records acceptance evidence in Bead notes.

7. Session Resilience & Recovery Contract

  1. Sessions are Ephemeral; Work is Durable: A crash, termination, or restart of an amux session or tmux pane MUST NOT drop the Bead claim or mutate Dolt work state.
  2. No Duplicate Execution on Restart: amux watchdog / auto-restart must reconnect to existing Gas City agent session state rather than spawning duplicate execution threads against the same claimed Bead.
  3. Always-On Autonomous Delivery: Operator closing laptop or disconnecting mobile client does not disrupt active background agent execution.