yatfa 1.0.97 → 1.0.99

package/README.md

@@ -79,9 +79,9 @@ Example `yatfa.env.rb`:
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `AGENT_TYPE` | ✅ | `worker`, `planner`, `reviewer`, or `researcher` |
-| `YATFA_URL` | ✅ | YATFA platform URL (WebSocket and API URLs are derived from this) |
-| `YATFA_API_KEY` | | MCP API key (get from YATFA dashboard) |
-| `GH_TOKEN` | | GitHub token for git operations |
+| `YATFA_API_KEY` | ✅ | MCP API key (get from YATFA dashboard) |
+| `YATFA_URL` | | Yatfa platform URL (defaults to `https://yatfa.com`; `YATFA_API_URL` & `YATFA_WS_URL` are derived from this) |
+| `GH_TOKEN` | | GitHub token for git operations (fallback; backend token auth is preferred) |
 
 ## Agent Types
 
@@ -199,7 +199,7 @@ YATFA_API_KEY=your_api_key_here
 AGENT_TYPE=worker
 ```
 
-Note: `YATFA_API_URL` and `YATFA_WS_URL` are derived from `YATFA_URL` by `setup-agent.rb`. Project is automatically determined by the API key authentication.
+Note: `YATFA_URL` is optional and defaults to `https://yatfa.com` (the hosted deployment works with zero URL configuration; self-hosted installs set it to their server). `YATFA_API_URL` (`/api/v1`) and `YATFA_WS_URL` (`/cable`, scheme-adjusted) are always derived from it — you never need to set them. The git credential helper derives `YATFA_API_URL` itself, so even a bare `docker exec` shell with no other env can authenticate. Project is automatically determined by the API key.
 
 ### Agent Self-Update
 

package/bin/run-yatfa-agent.rb

@@ -154,12 +154,12 @@ if command == "attach"
   puts ""
   agent_type = ARGV[1]&.downcase
   abort "Usage: npx yatfa attach [agent-type]" unless agent_type
-  config = YatfaAgent::Config.load
+  config = YatfaAgent::Config.load(allow_remote_fetch: true)
   YatfaAgent::Config.fetch_repositories!(config)
   YatfaAgent::Agent.attach(agent_type, config, AGENT_CONFIGS)
 else
   # Handle run commands (worker, planner, reviewer, researcher, claw)
-  config = YatfaAgent::Config.load
+  config = YatfaAgent::Config.load(allow_remote_fetch: true)
   # Fetch repositories from Rails API before building
   YatfaAgent::Config.fetch_repositories!(config)
   # Note: Docker.build_image is called inside Agent.run() only when a new

package/lib/yatfa_agent/bootstrap.rb

@@ -0,0 +1,389 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "http"
+
+module YatfaAgent
+  # Single-purpose runner bootstrap (YATFA-3203 / Creation→FULL WORK phase 7b —
+  # runner half).
+  #
+  # Lets a runner in a fresh checkout with no local +yatfa.env.rb+ obtain one
+  # by pasting a single bootstrap string (+<host>#<yrt_token>+), generated by
+  # the server (phase 7a, YATFA-3194). The token authorizes EXACTLY one read —
+  # +GET <host>/api/v1/bootstrap/env_file+ — and is:
+  #   - NOT written into the served +yatfa.env.rb+,
+  #   - NOT exported into runtime env,
+  #   - NOT sent anywhere except the bootstrap endpoint.
+  # (spec YATFA-3019 §2.3 single-purpose invariant — see the comment at
+  # +fetch_remote_env_file+.)
+  #
+  # The {host, token} pair is cached under +~/.yatfa/runner_bootstrap.json+
+  # (0600) so subsequent fresh checkouts auto-fetch without re-prompting — the
+  # credential is single-purpose and read-only, equivalent to +~/.npmrc+. The
+  # cache stores the bootstrap CREDENTIAL, never the env-file CONTENT (each
+  # checkout fetches fresh so rotated keys / new agents propagate).
+  module Bootstrap
+    # Raw token shape: +yrt_+ prefix + 64 hex chars (256 bits). Mirrors the
+    # server's +ProjectRunnerToken.well_formed?+ regex so a malformed paste is
+    # rejected client-side with a friendly error before any network call.
+    TOKEN_PATTERN = /\Ayrt_[0-9a-f]{64}\z/.freeze
+
+    # The single endpoint this credential authorizes a read against.
+    ENV_FILE_PATH = "/api/v1/bootstrap/env_file".freeze
+
+    # Reuses the installer's +~/.yatfa/+ directory convention (installer.rb).
+    # Resolved at call time (methods, not load-time constants) so the path
+    # tracks the current +HOME+ — keeps the cache location correct under
+    # env changes and lets specs isolate it via +ENV["HOME"]+.
+    def self.cache_dir
+      File.expand_path("~/.yatfa")
+    end
+
+    def self.cache_file
+      File.join(cache_dir, "runner_bootstrap.json")
+    end
+    private_class_method :cache_dir, :cache_file
+
+    # Parsed paste string: either a valid {host, token} pair or an {error}
+    # message. Never echoes the token in +error+. Use +ok?+ to branch.
+    PasteString = Struct.new(:host, :token, :error, keyword_init: true) do
+      def ok?
+        error.nil?
+      end
+    end
+    private_constant :PasteString
+
+    # Result of +fetch_remote_env_file+: a successful +body+ (the env-file
+    # Ruby source) or a classified +error+ message. Use +ok?+ to branch.
+    FetchResult = Struct.new(:body, :error, keyword_init: true) do
+      def ok?
+        error.nil?
+      end
+    end
+    private_constant :FetchResult
+
+    # Split +<host>#<token>+ on the FIRST +#+ and validate the token shape and
+    # host scheme. The token is a URL fragment per the server contract (phase
+    # 7a), so everything after the first +#+ is the token regardless of any +#+
+    # it may contain (it never does for a +yrt_+ token, but splitting on the
+    # first delimiter is the robust choice). Returns a PasteString; never
+    # raises. Never echoes the token in the returned error.
+    #
+    # The host MUST use +https://+ — an +http://+ host would send the bootstrap
+    # Bearer token in cleartext over the wire. +http://+ is allowed only for
+    # loopback (local dev servers).
+    #
+    # @param input [String] the pasted bootstrap string
+    # @return [PasteString] parsed +host+/+token+ or a friendly +error+
+    def self.parse_paste_string(input)
+      input = input.to_s.strip
+
+      unless input.include?("#")
+        return malformed
+      end
+
+      host, token = input.split("#", 2)
+      host = host.to_s.strip
+      token = token.to_s.strip
+
+      return malformed if host.empty? || !token.match?(TOKEN_PATTERN)
+      return insecure_host unless secure_host?(host)
+
+      PasteString.new(host: host, token: token)
+    end
+
+    # Fetch the env file from the bootstrap endpoint, returning a FetchResult.
+    # On 200 the +body+ is the env-file Ruby source (served as +text/x-ruby+);
+    # non-2xx, network, and invalid-body responses are classified into friendly
+    # +error+ messages. Never echoes the token.
+    #
+    # Single-purpose invariant (spec §2.3): the token is sent ONLY to
+    # +<host>/api/v1/bootstrap/env_file+ as a Bearer credential. It is not
+    # written anywhere, not exported into the runtime environment, and not
+    # reused for any other API call. The served env file carries the EXISTING
+    # per-agent +mcp_api_key+s unchanged — those remain the runtime +X-API-Key+
+    # credential. This method is the ONLY site that handles the raw token.
+    #
+    # The fetched body is validated to be non-empty Ruby that evaluates to a
+    # Hash BEFORE it is treated as a success, so a transient empty/HTML/malformed
+    # response is reported cleanly instead of crashing +Config.load+'s
+    # downstream +eval+ (same trust boundary: the token-authenticated yatfa
+    # server, which +Config.load+ evals anyway).
+    #
+    # @param host [String] yatfa base URL (e.g. +https://app.yatfa.com+)
+    # @param token [String] raw +yrt_++64-hex bootstrap token
+    # @return [FetchResult] +body+ on success, classified +error+ otherwise
+    def self.fetch_remote_env_file(host:, token:)
+      url = "#{normalize_host(host)}#{ENV_FILE_PATH}"
+      body = YatfaAgent::HTTP.get_raw(url, headers: { "Authorization" => "Bearer #{token}" })
+      unless valid_env_file_body?(body)
+        return FetchResult.new(error: invalid_body_error)
+      end
+      FetchResult.new(body: body)
+    rescue YatfaAgent::HTTP::Error => e
+      FetchResult.new(error: classify_http_error(e.status_code, host))
+    rescue StandardError => e
+      # Network/DNS/timeout/socket — the server was unreachable. Do not echo
+      # the token; surface only the host and the generic failure cause.
+      FetchResult.new(error: "❌ Could not reach #{normalize_host(host)}: #{e.message}")
+    end
+
+    # Read the cached {host, token} pair, or nil if no cache exists / is
+    # unreadable. Returns a +[host, token]+ Array for ergonomic destructuring.
+    # @return [Array(String, String), nil]
+    def self.read_cached_credentials
+      return nil unless File.exist?(cache_file)
+
+      parsed =
+        begin
+          JSON.parse(File.read(cache_file))
+        rescue StandardError
+          nil
+        end
+
+      return nil unless parsed.is_a?(Hash)
+
+      host = parsed["host"].to_s
+      token = parsed["token"].to_s
+      return nil if host.empty? || !token.match?(TOKEN_PATTERN)
+
+      [host, token]
+    end
+
+    # Persist the {host, token} pair under +~/.yatfa/runner_bootstrap.json+
+    # with 0600 perms — created restrictive in ONE call (File.open + chmod
+    # would leave a world-readable window under umask 022; this cache holds the
+    # raw bootstrap token). Best effort — a cache write failure must not abort
+    # an otherwise-successful bootstrap, so it is logged and swallowed.
+    # @param host [String]
+    # @param token [String]
+    # @return [Boolean] true if written, false on failure
+    def self.write_cached_credentials(host:, token:)
+      FileUtils.mkdir_p(cache_dir)
+      File.open(cache_file, "w", 0o600) { |f| f.write(JSON.generate("host" => host, "token" => token)) }
+      true
+    rescue StandardError => e
+      puts "⚠️  Could not cache bootstrap token (#{e.message}); you'll need to paste again next time."
+      false
+    end
+
+    # Remove a stale/dead cache (e.g. after a cached fetch returns 401/404 so
+    # the next run re-prompts instead of looping on a revoked token). Logs a
+    # warning if the delete fails — a stuck cache means every subsequent run
+    # repeats a doomed fetch, which is worth surfacing (unlike a read failure,
+    # which is benignly treated as "no cache").
+    # @return [void]
+    def self.clear_cached_credentials
+      File.delete(cache_file) if File.exist?(cache_file)
+    rescue StandardError => e
+      puts "⚠️  Could not remove stale bootstrap cache (#{e.message}); it will be retried next run."
+    end
+
+    # Orchestrator: obtain +yatfa.env.rb+ for a fresh checkout via the
+    # bootstrap token path. Writes the file to +Dir.pwd+ on success (so the
+    # caller's subsequent +File.read+ finds it) and caches the credential for
+    # future checkouts. Exits 1 with guidance on any failure, or when no
+    # credential is obtainable non-interactively (CI/scripts).
+    #
+    # Precedence: a local +yatfa.env.rb+ ALWAYS wins — this method is only
+    # reached from +Config.load+ when that file is absent and the caller opted
+    # into the remote-fetch path via +allow_remote_fetch:+.
+    #
+    # @return [true] on success (file written)
+    # @raise [SystemExit] (+exit 1+) on failure or non-interactive-no-cache
+    def self.bootstrap_env_file!
+      # 1. Try a cached credential first (prior paste in another checkout).
+      if (creds = read_cached_credentials)
+        host, token = creds
+        result = fetch_remote_env_file(host: host, token: token)
+        if result.ok?
+          return true if write_env_file(result.body)
+
+          exit 1 # write_env_file already printed the cause
+        end
+
+        # Cached credential no longer works (revoked / server rotated keys).
+        # Clear it so we don't keep retrying a dead token, then fall through.
+        puts result.error
+        clear_cached_credentials
+      end
+
+      # 2. Non-interactive + no working cache → cannot prompt a tty that
+      # isn't there. Mirror the existing --no-prompt contract: exit, don't
+      # hang. Show the manual-setup template too, so a CI box with no token
+      # still has the actionable copy-paste fallback it had before this path.
+      if non_interactive?
+        puts ""
+        puts "❌ yatfa.env.rb not found and no bootstrap token cached."
+        puts "   Run 'npx yatfa setup' interactively once, paste a runner"
+        puts "   bootstrap token on a tty, OR create yatfa.env.rb manually:"
+        puts ""
+        puts YatfaAgent::Bootstrap.manual_setup_instructions
+        exit 1
+      end
+
+      # 3. Interactive: prompt ONCE for the paste string.
+      puts ""
+      puts "🔧 No yatfa.env.rb found in this checkout."
+      puts "   Paste a runner bootstrap string to fetch it"
+      puts "   (Project Settings → Runner token):"
+      print "> "
+      input = $stdin.gets&.strip.to_s
+
+      parsed = parse_paste_string(input)
+      unless parsed.ok?
+        puts parsed.error
+        exit 1
+      end
+
+      result = fetch_remote_env_file(host: parsed.host, token: parsed.token)
+      unless result.ok?
+        puts result.error
+        exit 1
+      end
+
+      exit 1 unless write_env_file(result.body)
+      write_cached_credentials(host: parsed.host, token: parsed.token)
+      true
+    end
+
+    # Write the fetched env-file content to +Dir.pwd/yatfa.env.rb+ — the same
+    # location the setup wizard writes to, so the downstream +Config.load+
+    # eval path (config.rb) is unchanged. Created 0600 (the file embeds agent
+    # +mcp_api_key+s and +dot_env+ secrets). Returns the path on success, nil
+    # (after printing a clean message) if the write itself fails — a rare but
+    # fatal condition (read-only cwd, ENOSPC) the caller cannot recover from.
+    # @param content [String] env-file Ruby source
+    # @return [String, nil] the path written, or nil on write failure
+    def self.write_env_file(content)
+      config_file = File.join(Dir.pwd, "yatfa.env.rb")
+      File.open(config_file, "w", 0o600) { |f| f.write(content) }
+      puts "✅ Wrote yatfa.env.rb from bootstrap token (#{config_file})"
+      puts "   Reminder: ensure it's gitignored  →  echo 'yatfa.env.rb' >> .gitignore"
+      config_file
+    rescue StandardError => e
+      puts "❌ Could not write #{config_file}: #{e.message}"
+      puts "   Fix the directory permissions/disk and re-run."
+      nil
+    end
+
+    # The manual-setup guidance shown when +yatfa.env.rb+ is missing and the
+    # bootstrap path can't produce one (no tty, no cached token — e.g. CI).
+    # Returned as a string so both this module's non-interactive branch and
+    # +Config.load+'s local-only missing-file branch can +puts+ the SAME
+    # actionable template (Config delegates here). Lives in Bootstrap rather
+    # than Config because +config.rb+ requires +bootstrap.rb+ (one-way), so the
+    # shared helper belongs in the lower layer to avoid a back-reference.
+    # @return [String]
+    def self.manual_setup_instructions
+      <<~MSG
+        ❌ Error: yatfa.env.rb not found in current directory
+
+        Create yatfa.env.rb:
+          {
+            yatfa_url: 'https://yatfa.example.com',  # Required
+            # ...
+            # Paste your stripped .env content here:
+            dot_env: <<~ENV
+              STRIPE_KEY=sk_test_...
+              OPENAI_KEY=sk-...
+            ENV
+          }
+          echo 'yatfa.env.rb' >> .gitignore
+      MSG
+    end
+
+    # Whether prompting is impossible/forbidden. Mirrors Interaction#non_interactive?
+    # (interaction.rb) — duplicated here so the Bootstrap module stays
+    # self-contained (no load-order/coupling dependency on Agent extending
+    # Interaction). Kept in sync with that definition by contract.
+    # @return [Boolean]
+    def self.non_interactive?
+      !$stdin.tty? || ENV["YATFA_NO_PROMPT"] == "1" || ARGV.include?("--no-prompt") || ARGV.include?("-d")
+    end
+
+    # True if +host+ may safely carry the bootstrap token: +https://+ always,
+    # or +http://+ only for loopback (local dev servers where TLS is unusual).
+    def self.secure_host?(host)
+      h = host.to_s.strip.downcase
+      return true if h.start_with?("https://")
+      return true if h.start_with?("http://localhost") ||
+                     h.start_with?("http://127.0.0.1") ||
+                     h.start_with?("http://0.0.0.0") ||
+                     h.start_with?("http://[::1]")
+
+      false
+    end
+    private_class_method :secure_host?
+
+    # A fetched env file is valid only if it is non-empty Ruby that evaluates
+    # to a Hash (the shape +Config.load+ expects). Guards against an empty /
+    # HTML / truncated server response being written to disk and then crashing
+    # the downstream +eval+.
+    def self.valid_env_file_body?(content)
+      return false if content.nil? || content.to_s.strip.empty?
+
+      eval(content).is_a?(Hash)
+    rescue StandardError, ScriptError
+      # ScriptError covers SyntaxError (malformed Ruby / HTML page); this is a
+      # validation predicate and must NEVER raise — any eval failure means the
+      # body is not a valid Hash literal, so report it as invalid.
+      false
+    end
+    private_class_method :valid_env_file_body?
+
+    # Classify a non-2xx status code into friendly, token-free guidance.
+    # Status semantics mirror the server contract (bootstrap_controller.rb):
+    # 401 = missing/malformed/revoked, 404 = well-formed but unknown.
+    def self.classify_http_error(status_code, host)
+      case status_code
+      when 401
+        "❌ Token invalid or revoked — generate a new bootstrap string in Project Settings → Runner token."
+      when 404
+        "❌ Token not recognized by this server — generate a new bootstrap string."
+      else
+        "❌ Server at #{normalize_host(host)} returned HTTP #{status_code} — try again or generate a new bootstrap string."
+      end
+    end
+    private_class_method :classify_http_error
+
+    # Strip trailing slashes from the host so +<host>+/api/v1/... is well-formed
+    # regardless of whether the pasted host ended in +/+. NOTE: the bootstrap
+    # host comes from the operator's paste string (the server that ISSUED the
+    # token), so it is intentionally NOT routed through YatfaAgent::UrlHelper —
+    # an explicit +YATFA_API_URL+ override must NOT redirect the token to a
+    # different server than the one that minted it (that would both fail auth
+    # and leak the credential).
+    def self.normalize_host(host)
+      host.to_s.sub(%r{/+\z}, "")
+    end
+    private_class_method :normalize_host
+
+    # The friendly "doesn't look like a bootstrap string" error. Centralized so
+    # the wording is identical for every malformed-input path. Never echoes input.
+    def self.malformed
+      PasteString.new(
+        error: "❌ That doesn't look like a runner bootstrap string — " \
+               "generate one from Project Settings → Runner token."
+      )
+    end
+    private_class_method :malformed
+
+    # The "host must use https" error (cleartext http would leak the token).
+    def self.insecure_host
+      PasteString.new(
+        error: "❌ Bootstrap host must use https:// (an http:// host would " \
+               "send the token in cleartext). Re-copy the full bootstrap " \
+               "string from Project Settings → Runner token."
+      )
+    end
+    private_class_method :insecure_host
+
+    def self.invalid_body_error
+      "❌ Server returned an invalid or empty env file. " \
+        "Try again, or generate a new bootstrap string."
+    end
+    private_class_method :invalid_body_error
+  end
+end

package/lib/yatfa_agent/command_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../../setup/url_helper"
 
 module YatfaAgent
   # Docker command assembly.
@@ -68,10 +69,12 @@ module YatfaAgent
           docker_cmd += ["-e", "OPENCLAW_TELEGRAM_BOT_TOKEN=#{agent_config['telegram_bot_token']}"]
         end
 
-        # Pass YATFA_URL if configured (optional for claw)
+        # Pass YATFA_URL if configured (optional for claw). The API URL is
+        # derived via the shared UrlHelper so an explicit override is honored
+        # and the /api/v1 suffix rule stays in one place (YATFA-3018).
         if config["yatfa_url"]
           docker_cmd += ["-e", "YATFA_URL=#{config['yatfa_url']}"]
-          docker_cmd += ["-e", "YATFA_API_URL=#{config['yatfa_url']}/api/v1"]
+          docker_cmd += ["-e", "YATFA_API_URL=#{YatfaAgent::UrlHelper.api_url(config)}"]
         end
 
         # Pass MCP API key if configured (for future MCP integration)
@@ -80,14 +83,29 @@ module YatfaAgent
         end
 
       else
-        # Standard agent setup (worker, planner, reviewer, researcher)
+        # Standard agent setup (worker, planner, reviewer, researcher).
+        # Inject all three URLs as container-wide -e env (matching the claw
+        # branch) so any shell in the container — including `docker exec` shells
+        # that are not children of the setup process — sees a consistent
+        # YATFA_API_URL. YATFA_URL defaults to https://yatfa.com; API/WS URLs are
+        # derived from it via the shared UrlHelper (YATFA-3018). Previously only
+        # YATFA_URL + YATFA_API_KEY were injected here, leaving YATFA_API_URL
+        # empty outside the setup process and breaking git auth.
+        #
+        # An operator may override any URL via the env block; those overrides
+        # are already injected above as -e flags, so skip them here to avoid
+        # clobbering (the last -e flag for a key wins in docker). Derivation
+        # uses the effective source so env-block YATFA_URL flows into API/WS.
+        url_source = config.merge(merged_env)
         docker_cmd += [
           "-e", "YATFA_VERSION=main",
           "-e", "SKILLS=#{agent_def[:skills]&.join(',')}",
           "-e", "AGENT_TYPE=#{agent_type}",
-          "-e", "YATFA_URL=#{YatfaAgent::Config.yatfa_url(config)}",
           "-e", "YATFA_API_KEY=#{agent_config['mcp_api_key']}"
         ]
+        docker_cmd += ["-e", "YATFA_URL=#{YatfaAgent::UrlHelper.base_url(url_source)}"]     unless merged_env["YATFA_URL"]
+        docker_cmd += ["-e", "YATFA_API_URL=#{YatfaAgent::UrlHelper.api_url(url_source)}"] unless merged_env["YATFA_API_URL"]
+        docker_cmd += ["-e", "YATFA_WS_URL=#{YatfaAgent::UrlHelper.ws_url(url_source)}"]   unless merged_env["YATFA_WS_URL"]
 
         add_github_auth!(docker_cmd, config)
         add_git_config!(docker_cmd, config)

package/lib/yatfa_agent/config.rb

@@ -3,6 +3,12 @@
 require "json"
 require "digest"
 require_relative "http"
+require_relative "bootstrap"
+# Single source of truth for URL→{api,ws} derivation + the hosted default.
+# Loaded here (not duplicated) so the host-side launcher routes ALL URL
+# derivation through YatfaAgent::UrlHelper — the same module the in-container
+# setup scripts use. See YATFA-3018.
+require_relative "../../setup/url_helper"
 
 module YatfaAgent
   module Config
@@ -26,24 +32,38 @@ module YatfaAgent
       nil
     end
 
-    def self.load
+    # Load +yatfa.env.rb+ from the current directory and normalize it.
+    #
+    # When the file is absent and +allow_remote_fetch+ is true (the runner
+    # entry point opts in), the bootstrap token path runs first: it fetches the
+    # env file from the server via a single-purpose runner token (see
+    # YatfaAgent::Bootstrap) and writes it to +Dir.pwd+, then this method
+    # loads it as if it had been there all along. A LOCAL +yatfa.env.rb+
+    # always wins — the remote-fetch path only runs when one is missing.
+    #
+    # When +allow_remote_fetch+ is false (the default — tests, CI, library
+    # callers), +Config.load+ stays a pure local-file reader: a missing file
+    # prints the manual-setup guidance and exits 1, exactly as before.
+    #
+    # @param allow_remote_fetch [Boolean] enable the bootstrap token path on a
+    #   missing file (default: false, keeps callers deterministic)
+    def self.load(allow_remote_fetch: false)
       config_file = File.join(Dir.pwd, "yatfa.env.rb")
 
       unless File.exist?(config_file)
-        puts "❌ Error: yatfa.env.rb not found in current directory"
-        puts ""
-        puts "Create yatfa.env.rb:"
-        puts "  {"
-        puts "    yatfa_url: 'https://yatfa.example.com',  # Required"
-        puts "    # ..."
-        puts "    # Paste your stripped .env content here:"
-        puts "    dot_env: <<~ENV"
-        puts "      STRIPE_KEY=sk_test_..."
-        puts "      OPENAI_KEY=sk-..."
-        puts "    ENV"
-        puts "  }"
-        puts "  echo 'yatfa.env.rb' >> .gitignore"
-        exit 1
+        if allow_remote_fetch
+          # Fetches +yatfa.env.rb+ via a single-purpose bootstrap token and
+          # writes it to Dir.pwd, or exits 1 with guidance. On success the
+          # file now exists and the eval path below loads it unchanged.
+          # Local>token>error precedence holds: we only reach here when no
+          # local file is present.
+          YatfaAgent::Bootstrap.bootstrap_env_file!
+        else
+          # Shared with the bootstrap non-interactive path so both surfaces
+          # print the same actionable template.
+          puts YatfaAgent::Bootstrap.manual_setup_instructions
+          exit 1
+        end
       end
 
       puts "⚙️  Loading configuration from yatfa.env.rb"
@@ -88,27 +108,6 @@ module YatfaAgent
       JSON.parse(JSON.generate(config))
     end
 
-    def self.yatfa_url(config)
-      config["yatfa_url"] || config["rails_api_url"]
-    end
-
-    def self.api_url(config)
-      # Derive API URL from yatfa_url
-      yatfa_base = yatfa_url(config)
-
-      # If yatfa_url already includes /api/v1, return as-is
-      return yatfa_base if yatfa_base.end_with?("/api/v1") || yatfa_base.end_with?("/api/")
-
-      # Otherwise, assume it's the base URL and append /api/v1
-      "#{yatfa_base}/api/v1"
-    end
-
-    def self.ws_url(config)
-      # Derive WebSocket URL from yatfa_url by replacing protocol and adding /cable endpoint
-      api_base = yatfa_url(config)
-      "#{api_base.sub(/^https:\/\//, "wss://").sub(/^http:\/\//, "ws://")}/cable"
-    end
-
     # Extract the first available agent MCP API key from the config.
     # Returns nil when no key is configured.
     def self.agent_api_key(config)
@@ -123,8 +122,11 @@ module YatfaAgent
     end
 
     def self.fetch_repositories!(config)
-      # Support both old and new config keys
-      api_base = api_url(config)
+      # Derive the API URL through the shared single source of truth
+      # (YatfaAgent::UrlHelper) so this host-side path honors an explicit
+      # YATFA_API_URL override and the hosted default exactly like the
+      # launcher and in-container setup scripts. See YATFA-3018.
+      api_base = YatfaAgent::UrlHelper.api_url(config)
 
       return unless api_base
 

package/lib/yatfa_agent/docker.rb

@@ -49,7 +49,12 @@ module YatfaAgent
     # be identified, the API is unreachable, or no such config is stored.
     # Never raises — a missing remote config is a normal "fall back to error" case.
     def self.fetch_remote_dockerfile(config)
-      api_base = Config.api_url(config)
+      # Derive the API URL through the shared single source of truth
+      # (YatfaAgent::UrlHelper) rather than the legacy Config.api_url, which
+      # neither honored an explicit YATFA_API_URL override nor applied the
+      # hosted default and could raise NoMethodError on an unconfigured URL.
+      # YatfaAgent::UrlHelper is loaded transitively via config.rb. See YATFA-3018.
+      api_base = YatfaAgent::UrlHelper.api_url(config)
       project_id = config["project_id"]
       api_key = Config.agent_api_key(config)
 

package/lib/yatfa_agent/http.rb

@@ -43,6 +43,30 @@ module YatfaAgent
       handle_response(response)
     end
 
+    # Perform a GET request returning the RAW response body as a String on
+    # success (NO JSON parsing). Use this for endpoints that serve non-JSON
+    # bodies — e.g. the bootstrap env-file endpoint serves +text/x-ruby+
+    # (Ruby source), which would raise JSON::ParserError under +.get+.
+    #
+    # Raises YatfaAgent::HTTP::Error (with +status_code+) for non-2xx exactly
+    # like +.get+, so callers can reuse the +rescue HTTP::Error => e;
+    # case e.status_code+ classification pattern unchanged.
+    #
+    # @param url [String] full URL to request
+    # @param headers [Hash] HTTP headers (e.g. { "Authorization" => "Bearer x" })
+    # @param open_timeout [Integer] connection timeout in seconds (default: 5)
+    # @param read_timeout [Integer] response timeout in seconds (default: 10)
+    # @return [String] raw response body
+    # @raise [Error] for non-2xx HTTP responses
+    def self.get_raw(url, headers: {}, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+      uri = URI(url)
+      http = build_http(uri, open_timeout: open_timeout, read_timeout: read_timeout)
+      request = Net::HTTP::Get.new(uri)
+      headers.each { |k, v| request[k] = v }
+      response = http.request(request)
+      handle_response(response, raw: true)
+    end
+
     # Perform a POST request. Returns parsed JSON body on success.
     # Raises YatfaAgent::HTTP::Error for non-2xx responses.
     # Raises exceptions on network/timeout errors.
@@ -81,9 +105,14 @@ module YatfaAgent
         JSON.parse(body)
       end
 
-      def handle_response(response)
+      # Parse a 2xx success body. By default the body is parsed as JSON (the
+      # contract every existing caller relies on); pass +raw: true+ to return
+      # the body verbatim — for non-JSON endpoints (e.g. the bootstrap env-file
+      # endpoint serves +text/x-ruby+). The non-2xx error path is shared so the
+      # +Error+ shape (with +status_code+) is identical either way.
+      def handle_response(response, raw: false)
         if response.is_a?(Net::HTTPSuccess)
-          parse_json(response.body)
+          raw ? response.body : parse_json(response.body)
         else
           raise Error.new(
             "HTTP #{response.code} #{response.message}",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yatfa",
-  "version": "1.0.97",
+  "version": "1.0.99",
   "description": "YATFA - Yet Another Tool For Agents",
   "bin": "./bin/run-yatfa-agent.rb",
   "files": [

package/setup/git_credential_helper.rb

@@ -36,6 +36,41 @@ require "uri"
 require "time"
 require "fileutils"
 
+# Self-healing URL derivation (YATFA-3018). This helper runs in isolation as
+# /usr/local/bin/git-auth-helper (copied there by setup-github.rb alongside
+# url_helper.rb), so it derives YATFA_API_URL from YATFA_URL itself — defaulting
+# to https://yatfa.com — rather than bailing when YATFA_API_URL is empty (the
+# exact failure operators hit in `docker exec` shells outside the setup
+# process). Load the shared module: in-tree via require_relative (tests / setup/),
+# or from the absolute install path when running as the copied binary. A
+# last-resort inline mirror keeps auth working even if the sibling file is
+# missing (version skew / half install) — a credential helper must never break
+# on a missing file. Keep the mirror in sync with setup/url_helper.rb.
+begin
+  require_relative "url_helper"
+rescue LoadError
+  begin
+    require "/usr/local/bin/url_helper"
+  rescue LoadError
+    module YatfaAgent
+      module UrlHelper
+        DEFAULT_YATFA_URL = "https://yatfa.com"
+
+        module_function
+
+        def api_url(source = ENV)
+          explicit = source["YATFA_API_URL"].to_s.strip
+          return explicit unless explicit.empty?
+
+          base = source["YATFA_URL"].to_s.strip
+          base = DEFAULT_YATFA_URL if base.empty?
+          base.end_with?("/api/v1") || base.end_with?("/api/") ? base : "#{base}/api/v1"
+        end
+      end
+    end
+  end
+end
+
 module YatfaAgent
   module GitCredentialHelper
     DEFAULT_CACHE_DIR = "/tmp/github-token-cache"
@@ -116,9 +151,11 @@ module YatfaAgent
     # using the per-installation cache and falling back to the default token
     # when a repo-scoped fetch fails (older backend, unregistered repo, etc.).
     def resolve_token(repo, cache_dir:, env:, http_fetch:)
-      api_url = env["YATFA_API_URL"]
+      # Self-heal: derive YATFA_API_URL from YATFA_URL (default https://yatfa.com)
+      # when not explicitly set, so a bare `docker exec` shell with no manual
+      # export can still auth. An explicit YATFA_API_URL override is honored.
+      api_url = YatfaAgent::UrlHelper.api_url(env)
       api_key = env["YATFA_API_KEY"]
-      return nil if api_url.nil? || api_url.to_s.empty?
       return nil if api_key.nil? || api_key.to_s.empty?
 
       cached = read_cached_token(repo, cache_dir)
@@ -134,6 +171,19 @@ module YatfaAgent
       data["token"]
     end
 
+    # When required config is missing, return a specific diagnostic naming the
+    # offending variable; otherwise nil. The API URL is self-healed (derived
+    # from YATFA_URL, default https://yatfa.com), so the only hard requirement
+    # is the YATFA_API_KEY secret — previously this surfaced as the opaque
+    # "failed to obtain GitHub token" (YATFA-3018).
+    def missing_config_message(env_hash, repo: nil)
+      api_key = env_hash["YATFA_API_KEY"]
+      return nil unless api_key.nil? || api_key.to_s.empty?
+
+      repo_suffix = repo ? " for #{repo}" : ""
+      "git-auth-helper: YATFA_API_KEY is not set — cannot mint a GitHub token#{repo_suffix}"
+    end
+
     # Dispatch entry point. Returns a process exit code (0 success, 1 failure).
     def run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr,
             cache_dir: DEFAULT_CACHE_DIR, env: nil, http_fetch: nil)
@@ -145,6 +195,10 @@ module YatfaAgent
         if action == "get"
           attrs = parse_input(read_stdin(stdin))
           repo = normalize_path(attrs["path"])
+          if (msg = missing_config_message(env_hash, repo: repo))
+            stderr.puts(msg)
+            return 1
+          end
           token = resolve_token(repo, cache_dir: cache_dir, env: env_hash, http_fetch: fetch)
           if token.nil?
             stderr.puts("git-auth-helper: failed to obtain GitHub token" + (repo ? " for #{repo}" : ""))
@@ -160,6 +214,10 @@ module YatfaAgent
       end
 
       # Token-only mode (e.g. the `gh` wrapper): print just the default token.
+      if (msg = missing_config_message(env_hash))
+        stderr.puts(msg)
+        return 1
+      end
       token = resolve_token(nil, cache_dir: cache_dir, env: env_hash, http_fetch: fetch)
       if token.nil?
         stderr.puts("git-auth-helper: failed to obtain GitHub token")

package/setup/http_client.rb

@@ -43,6 +43,30 @@ module YatfaAgent
       handle_response(response)
     end
 
+    # Perform a GET request returning the RAW response body as a String on
+    # success (NO JSON parsing). Use this for endpoints that serve non-JSON
+    # bodies — e.g. the bootstrap env-file endpoint serves +text/x-ruby+
+    # (Ruby source), which would raise JSON::ParserError under +.get+.
+    #
+    # Raises YatfaAgent::HTTP::Error (with +status_code+) for non-2xx exactly
+    # like +.get+, so callers can reuse the +rescue HTTP::Error => e;
+    # case e.status_code+ classification pattern unchanged.
+    #
+    # @param url [String] full URL to request
+    # @param headers [Hash] HTTP headers (e.g. { "Authorization" => "Bearer x" })
+    # @param open_timeout [Integer] connection timeout in seconds (default: 5)
+    # @param read_timeout [Integer] response timeout in seconds (default: 10)
+    # @return [String] raw response body
+    # @raise [Error] for non-2xx HTTP responses
+    def self.get_raw(url, headers: {}, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+      uri = URI(url)
+      http = build_http(uri, open_timeout: open_timeout, read_timeout: read_timeout)
+      request = Net::HTTP::Get.new(uri)
+      headers.each { |k, v| request[k] = v }
+      response = http.request(request)
+      handle_response(response, raw: true)
+    end
+
     # Perform a POST request. Returns parsed JSON body on success.
     # Raises YatfaAgent::HTTP::Error for non-2xx responses.
     # Raises exceptions on network/timeout errors.
@@ -81,9 +105,14 @@ module YatfaAgent
         JSON.parse(body)
       end
 
-      def handle_response(response)
+      # Parse a 2xx success body. By default the body is parsed as JSON (the
+      # contract every existing caller relies on); pass +raw: true+ to return
+      # the body verbatim — for non-JSON endpoints (e.g. the bootstrap env-file
+      # endpoint serves +text/x-ruby+). The non-2xx error path is shared so the
+      # +Error+ shape (with +status_code+) is identical either way.
+      def handle_response(response, raw: false)
         if response.is_a?(Net::HTTPSuccess)
-          parse_json(response.body)
+          raw ? response.body : parse_json(response.body)
         else
           raise Error.new(
             "HTTP #{response.code} #{response.message}",

package/setup/setup-agent.rb

@@ -36,6 +36,7 @@ require "time"
 require "socket"
 require "timeout"
 require_relative "http_client"
+require_relative "url_helper"
 require_relative "setup-github"
 require_relative "repositories"
 require_relative "agent_bridge"
@@ -52,47 +53,32 @@ YATFA_RAW_URL = "#{YATFA_SCRIPTS_BASE_URL}/#{YATFA_VERSION}"
 VALID_AGENT_TYPES = %w[planner worker reviewer researcher claw]
 
 def check_env!
-  agent_type = ENV["AGENT_TYPE"]
-
   # Note: claw agents have a separate entry point in setup-claw-agent.rb
   # which calls check_env_claw! directly. This method only handles standard agent types.
 
-  required = %w[YATFA_URL]
-  missing = required.select { |var| ENV[var].to_s.empty? }
-  unless missing.empty?
-    puts "❌ Missing environment variables: #{missing.join(', ')}"
-    puts ""
-    puts "Required:"
-    puts "  YATFA_URL   - Yatfa platform URL (https://yatfa.example.com)"
+  # YATFA_API_KEY is the single required secret — the agent cannot authenticate
+  # to the backend or mint GitHub tokens without it. Fail fast with a specific
+  # message rather than starting a half-working agent (YATFA-3018).
+  if ENV["YATFA_API_KEY"].to_s.empty?
+    puts "❌ Missing required environment variable: YATFA_API_KEY"
+    puts "   YATFA_API_KEY is the MCP API key for this agent (from the Yatfa dashboard)."
+    puts "   The agent needs it to authenticate to the backend and to mint GitHub tokens."
     puts ""
-    puts "Optional:"
-    puts "  YATFA_API_URL  - API URL for MCP tools (derived from YATFA_URL)"
-    puts "  YATFA_API_KEY  - MCP API key"
-    puts "  GH_TOKEN       - GitHub token"
+    puts "YATFA_URL is optional (defaults to https://yatfa.com);"
+    puts "  YATFA_API_URL / YATFA_WS_URL are derived from it."
     exit 1
   end
 
-  # Derive YATFA_API_URL and YATFA_WS_URL from YATFA_URL if not set
-  # IMPORTANT: Always use original YATFA_URL for derivations, not modified values
-  yatfa_url = ENV["YATFA_URL"]
-
-  # Derive YATFA_API_URL: append /api/v1 if not already present
-  unless ENV["YATFA_API_URL"]
-    if yatfa_url.end_with?("/api/v1") || yatfa_url.end_with?("/api/")
-      ENV["YATFA_API_URL"] = yatfa_url
-    else
-      ENV["YATFA_API_URL"] = "#{yatfa_url}/api/v1"
-    end
-    puts "📡 Derived YATFA_API_URL: #{ENV['YATFA_API_URL']}"
-  end
-
-  # Derive YATFA_WS_URL: replace protocol with ws/wss and add /cable endpoint
-  # IMPORTANT: Use original yatfa_url before any modifications
-  original_yatfa_url = ENV["YATFA_URL"]
-  unless ENV["YATFA_WS_URL"]
-    ENV["YATFA_WS_URL"] = "#{original_yatfa_url.sub(/^https:\/\//, 'wss://').sub(/^http:\/\//, 'ws://')}/cable"
-    puts "📡 Derived YATFA_WS_URL: #{ENV['YATFA_WS_URL']}"
-  end
+  # Derive the three URLs via the shared UrlHelper (YATFA-3018). YATFA_URL
+  # defaults to https://yatfa.com when unset; YATFA_API_URL (/api/v1) and
+  # YATFA_WS_URL (scheme-swapped /cable) are derived from it. Explicit
+  # overrides for any of the three are honored (backwards compatible).
+  ENV["YATFA_URL"]     = YatfaAgent::UrlHelper.base_url
+  ENV["YATFA_API_URL"] = YatfaAgent::UrlHelper.api_url
+  ENV["YATFA_WS_URL"]  = YatfaAgent::UrlHelper.ws_url
+  puts "📡 YATFA_URL:     #{ENV['YATFA_URL']}"
+  puts "📡 YATFA_API_URL: #{ENV['YATFA_API_URL']}"
+  puts "📡 YATFA_WS_URL:  #{ENV['YATFA_WS_URL']}"
 
   agent_type = ENV["AGENT_TYPE"]
   if agent_type && !VALID_AGENT_TYPES.include?(agent_type)

package/setup/setup-claw-agent.rb

@@ -14,6 +14,9 @@
 #   - fetch_llm_credentials! is defined by the parent setup-agent.rb
 #   - Standard library requires (json, fileutils, pathname, etc.) are loaded
 #     by setup-agent.rb before this file is required
+#   - YatfaAgent::UrlHelper is provided by setup/url_helper.rb
+
+require_relative "url_helper" unless defined?(YatfaAgent::UrlHelper)
 
 def check_env_claw!
   required = %w[OPENCLAW_TELEGRAM_BOT_TOKEN]
@@ -37,9 +40,11 @@ def check_env_claw!
     exit 1
   end
 
-  # Derive YATFA_API_URL from YATFA_URL if set (optional for claw)
+  # Derive YATFA_API_URL from YATFA_URL via the shared helper (optional for
+  # claw — yatfa integration is opt-in, so only when YATFA_URL is set). The
+  # /api/v1 suffix rule lives in one place (YATFA-3018).
   if ENV["YATFA_URL"] && !ENV["YATFA_API_URL"]
-    ENV["YATFA_API_URL"] = "#{ENV['YATFA_URL']}/api/v1"
+    ENV["YATFA_API_URL"] = YatfaAgent::UrlHelper.with_api_suffix(ENV["YATFA_URL"])
   end
 
   puts "✅ Claw environment validated"

package/setup/setup-github.rb

@@ -4,26 +4,14 @@
 # Extracted from setup-agent.rb for modularity
 
 def setup_github_auth!
-  rails_api_url = ENV["YATFA_API_URL"]
   rails_api_key = ENV["YATFA_API_KEY"]
 
-  # Derive YATFA_API_URL from YATFA_URL if not set
-  unless rails_api_url && !rails_api_url.empty?
-    yatfa_url = ENV["YATFA_URL"]
-    if yatfa_url && !yatfa_url.empty?
-      rails_api_url = "#{yatfa_url}/api/v1"
-      ENV["YATFA_API_URL"] = rails_api_url
-    end
-  end
-
-  # Validate YATFA_API_URL format before proceeding
-  if rails_api_url && !rails_api_url.empty? && !rails_api_url.include?('/api/v1')
-    puts "⚠️  Warning: YATFA_API_URL must include /api/v1 path"
-    puts "   Current: #{rails_api_url}"
-    puts "   Expected: https://example.com/api/v1"
-    puts "   Falling back to alternative authentication..."
-    rails_api_url = nil  # Clear it to fall through to other methods
-  end
+  # Derive YATFA_API_URL via the shared UrlHelper (YATFA-3018): honors an
+  # explicit override, else derives /api/v1 from YATFA_URL (default
+  # https://yatfa.com). check_env! already set this for standard agents, but
+  # re-derive defensively so a re-run / partial flow is consistent.
+  ENV["YATFA_API_URL"] = YatfaAgent::UrlHelper.api_url
+  rails_api_url = ENV["YATFA_API_URL"]
 
   # New method: Get token from Rails backend (preferred)
   if rails_api_url && !rails_api_url.empty? && rails_api_key && !rails_api_key.empty?
@@ -38,6 +26,16 @@ def setup_github_auth!
     system("sudo", "mv", "/tmp/git-auth-helper", helper_path)
     system("sudo", "chmod", "+x", helper_path)
 
+    # Install the shared URL helper alongside the credential helper. The helper
+    # runs in isolation as /usr/local/bin/git-auth-helper and loads it via
+    # `require_relative "url_helper"` to self-heal YATFA_API_URL from YATFA_URL
+    # (default https://yatfa.com) in bare `docker exec` shells (YATFA-3018).
+    url_helper_src = File.join(__dir__, "url_helper.rb")
+    if File.exist?(url_helper_src)
+      File.write("/tmp/url_helper", File.read(url_helper_src))
+      system("sudo", "mv", "/tmp/url_helper", "/usr/local/bin/url_helper.rb")
+    end
+
     # Wire the helper into git. useHttpPath=true makes git send the repo path on
     # stdin so the helper can request a repo-scoped token (?repo=owner/repo).
     # Array form avoids shell interpolation of the helper path.

package/setup/url_helper.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# YATFA URL derivation — the single source of truth.
+#
+# `YATFA_URL` is the only URL variable an operator ever configures. The API URL
+# (`<base>/api/v1`) and the WebSocket URL (`<scheme-adjusted base>/cable`) are
+# ALWAYS derived from it. Both the host-side launcher (lib/yatfa_agent/) and the
+# in-container setup scripts (setup/*) load this module so the derivation lives
+# in exactly one place.
+#
+# Rules (see YATFA-3018):
+#   1. `YATFA_URL` defaults to `https://yatfa.com` when unset/blank, so the
+#      hosted deployment works with zero URL configuration.
+#   2. `YATFA_API_URL` / `YATFA_WS_URL`, when explicitly set, are honored as
+#      overrides (backwards compatible) — never re-derived.
+#   3. The API URL appends `/api/v1` unless the base already carries an `/api`
+#      path; the WS URL swaps the scheme (http→ws, https→wss) and appends
+#      `/cable`.
+#
+# Every method takes an optional +source+ — any hash-like object (ENV, or a
+# string-keyed config hash) — so the same logic serves the launcher (config
+# hash) and the container scripts (ENV).
+
+module YatfaAgent
+  module UrlHelper
+    DEFAULT_YATFA_URL = "https://yatfa.com"
+    API_SUFFIX = "/api/v1"
+    WS_SUFFIX = "/cable"
+
+    module_function
+
+    # Resolve the base platform URL, applying the hosted default when unset.
+    # Reads +YATFA_URL+ (ENV convention) then +yatfa_url+ / +rails_api_url+
+    # (config-hash convention).
+    def base_url(source = ENV)
+      value = source_value(source, "YATFA_URL") ||
+              source_value(source, "yatfa_url") ||
+              source_value(source, "rails_api_url")
+      value = value.to_s.strip
+      value.empty? ? DEFAULT_YATFA_URL : value
+    end
+
+    # Derive the API URL. An explicit +YATFA_API_URL+ override wins; otherwise
+    # the suffix is appended to the resolved base URL.
+    def api_url(source = ENV)
+      explicit = source_value(source, "YATFA_API_URL").to_s.strip
+      return explicit unless explicit.empty?
+
+      with_api_suffix(base_url(source))
+    end
+
+    # Derive the WebSocket URL. An explicit +YATFA_WS_URL+ override wins;
+    # otherwise the base scheme is swapped (http→ws, https→wss) and +/cable+
+    # is appended.
+    def ws_url(source = ENV)
+      explicit = source_value(source, "YATFA_WS_URL").to_s.strip
+      return explicit unless explicit.empty?
+
+      "#{to_ws_scheme(base_url(source))}#{WS_SUFFIX}"
+    end
+
+    # Append +/api/v1+ to +base+ unless it already ends with +/api/v1+ or
+    # +/api/+. Shared with YatfaAgent::Config so the suffix rule is defined once.
+    def with_api_suffix(base)
+      base = base.to_s
+      return base if base.end_with?("/api/v1") || base.end_with?("/api/")
+
+      "#{base}#{API_SUFFIX}"
+    end
+
+    # Swap the scheme of +base+ to its WebSocket equivalent. Already-ws schemes
+    # are left untouched.
+    def to_ws_scheme(base)
+      base.to_s.sub(/\Ahttps:\/\//, "wss://").sub(/\Ahttp:\/\//, "ws://")
+    end
+
+    # Safely read +key+ from a hash-like +source+ (ENV or a config Hash).
+    def source_value(source, key)
+      return nil unless source.respond_to?(:[])
+
+      source[key]
+    rescue StandardError
+      nil
+    end
+  end
+end