From 669698f6c0d2843e7229e0bf4031c86852144013 Mon Sep 17 00:00:00 2001
From: Jean-Philippe <jpduchesne89@gmail.com>
Date: Sat, 12 Sep 2026 20:06:17 -0400
Subject: [PATCH 1/3] RunnerDiscovery + RunnerRegistry: enrollment state,
 inspected never recorded
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two read seams for runner enrollment state (plans#26): RunnerDiscovery
enumerates this host's actions-runner dirs and parses each .runner record
(scope + name, BOM-aware) — offline by construction, spanning every dir so
an org enrollment living in a repo-named dir (its pre-org history) is
still found. RunnerRegistry is the GitHub-side view over the gh Executor
seam: find a runner by scope+name (custom labels only — read-only ones
are GitHub's), amend its custom labels in place via PUT, loud QueryError
vs nil so callers can tell offline from gone. Refs #161.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 lib/dev/runner_discovery.rb       |  84 +++++++++++++++++++++
 lib/dev/runner_registry.rb        |  91 +++++++++++++++++++++++
 test/dev/runner_discovery_test.rb |  73 ++++++++++++++++++
 test/dev/runner_registry_test.rb  | 118 ++++++++++++++++++++++++++++++
 4 files changed, 366 insertions(+)
 create mode 100644 lib/dev/runner_discovery.rb
 create mode 100644 lib/dev/runner_registry.rb
 create mode 100644 test/dev/runner_discovery_test.rb
 create mode 100644 test/dev/runner_registry_test.rb

diff --git a/lib/dev/runner_discovery.rb b/lib/dev/runner_discovery.rb
new file mode 100644
index 0000000..5719e46
--- /dev/null
+++ b/lib/dev/runner_discovery.rb
@@ -0,0 +1,84 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+module Dev
+  # This machine's runner enrollments, inspected — never recorded
+  # (plans#26): the actions-runner install dirs under $HOME are the only
+  # local state, and each configured dir's .runner file (written by
+  # config.sh) names the enrollment's scope and runner name. Labels are
+  # deliberately NOT here — GitHub is their single home; Dev::RunnerRegistry
+  # reads them. Offline by construction, so register and status can find
+  # this host's enrollments without the network.
+  class RunnerDiscovery
+    extend T::Sig
+
+    # One local enrollment: where it lives and what its .runner records.
+    class Enrollment < T::Struct
+      # Absolute install dir. Its name is history (register defaults it from
+      # the first label at enrollment time) — never identity; the .runner
+      # record inside is what binds it to a scope.
+      const :dir, String
+
+      # "owner/repo" (repo scope) or "owner" (org scope).
+      const :scope, String
+
+      # The runner's GitHub-side name (.runner agentName).
+      const :name, String
+    end
+
+    # @param home [String] the home dir to scan (injectable for tests)
+    sig { params(home: String).void }
+    def initialize(home: Dir.home)
+      @home = home
+    end
+
+    # Every configured enrollment on this host, in dir order. Unconfigured
+    # dirs (downloaded but never registered, or garbage) are silently
+    # skipped — they are not enrollments.
+    #
+    # @return [Array<Enrollment>]
+    sig { returns(T::Array[Enrollment]) }
+    def enrollments
+      Dir.glob(File.join(@home, "actions-runner-*")).sort.filter_map { |dir| self.class.read(dir) }
+    end
+
+    # The enrollment serving a scope, when one exists. The lookup spans
+    # every runner dir because dir names drift from labels over a box's
+    # life (e.g. an org enrollment living in a repo-named dir from its
+    # pre-org history) — matching on the .runner record is what makes
+    # re-registration self-healing instead of a duplicate enrollment.
+    #
+    # @param scope [String] "owner/repo" or "owner"
+    # @return [Enrollment, nil]
+    sig { params(scope: String).returns(T.nilable(Enrollment)) }
+    def for_scope(scope)
+      enrollments.find { |enrollment| enrollment.scope == scope }
+    end
+
+    class << self
+      extend T::Sig
+
+      # Parse a runner dir's .runner record. config.sh writes the file with
+      # a UTF-8 BOM, so read with "bom|utf-8" or JSON.parse chokes on the
+      # first byte. nil when absent or unreadable — an unconfigured dir.
+      #
+      # @param dir [String] a runner install dir
+      # @return [Enrollment, nil]
+      sig { params(dir: String).returns(T.nilable(Enrollment)) }
+      def read(dir)
+        raw = File.read(File.join(dir, ".runner"), encoding: "bom|utf-8")
+        record = JSON.parse(raw)
+        url = record["gitHubUrl"].to_s
+        scope = url.sub(%r{\Ahttps://github\.com/}, "").chomp("/")
+        name = record["agentName"].to_s
+        return nil if scope.empty? || scope == url || name.empty?
+
+        Enrollment.new(dir: dir, scope: scope, name: name)
+      rescue JSON::ParserError, Errno::ENOENT
+        nil
+      end
+    end
+  end
+end
diff --git a/lib/dev/runner_registry.rb b/lib/dev/runner_registry.rb
new file mode 100644
index 0000000..916b4ee
--- /dev/null
+++ b/lib/dev/runner_registry.rb
@@ -0,0 +1,91 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+require "dev/runner_setup"
+
+module Dev
+  # The GitHub-side view of the self-hosted runners enrolled at a scope:
+  # find one by name, amend its custom labels in place. Labels have exactly
+  # one home — GitHub — so this is both how register converges an existing
+  # enrollment's labels without re-enrolling and how status reports them
+  # (plans#26: inspected, never recorded).
+  #
+  # The gh CLI boundary rides the same Executor seam RunnerSetup uses, so
+  # tests exercise the orchestration without the network.
+  class RunnerRegistry
+    extend T::Sig
+
+    # GitHub could not be queried (offline, unauthenticated) — distinct
+    # from a runner genuinely absent at the scope (find returns nil).
+    class QueryError < StandardError; end
+
+    # The label amend was refused (permissions, deleted runner).
+    class AmendError < StandardError; end
+
+    # One enrolled runner, as the amendable subset of GitHub's record:
+    # custom labels only — the read-only ones (self-hosted, OS, arch) are
+    # GitHub's, not ours to converge.
+    class Runner < T::Struct
+      const :id, Integer
+      const :custom_labels, T::Array[String]
+    end
+
+    # @param executor [#capture] CLI boundary (injectable for tests)
+    sig { params(executor: T.untyped).void }
+    def initialize(executor: RunnerSetup::Executor.new)
+      @exec = executor
+    end
+
+    # The runner enrolled under `name` at `scope`, or nil when none is.
+    #
+    # @param scope [String] "owner/repo" or "owner"
+    # @param name [String] the runner's GitHub-side name
+    # @return [Runner, nil]
+    # @raise [QueryError] when GitHub can't be queried — loud, never a
+    #   silent not-found, so callers can tell "gone" from "unknown"
+    sig { params(scope: String, name: String).returns(T.nilable(Runner)) }
+    def find(scope:, name:)
+      out, err, ok = @exec.capture("gh", "api", "--paginate", "#{api_base(scope)}/actions/runners", "--jq", ".runners[]")
+      raise QueryError, "could not list the runners at #{scope}: #{err.strip}" unless ok
+
+      record = out.each_line.map { |line| JSON.parse(line) }.find { |runner| runner["name"] == name }
+      return nil if record.nil?
+
+      custom = Array(record["labels"]).select { |label| label["type"] == "custom" }.map { |label| label["name"].to_s }
+      Runner.new(id: Integer(record.fetch("id")), custom_labels: custom)
+    end
+
+    # Replace the runner's custom labels with `labels` (GitHub's PUT
+    # semantics: the full custom set, read-only labels untouched). This is
+    # the no-re-enrollment amend path: the service, its name, and its dir
+    # all stay put.
+    #
+    # @param scope [String] "owner/repo" or "owner"
+    # @param runner_id [Integer]
+    # @param labels [Array<String>] the desired custom label set
+    # @return [void]
+    # @raise [AmendError] when the PUT is refused
+    sig { params(scope: String, runner_id: Integer, labels: T::Array[String]).void }
+    def amend!(scope:, runner_id:, labels:)
+      argv = ["gh", "api", "-X", "PUT", "#{api_base(scope)}/actions/runners/#{runner_id}/labels"]
+      argv += labels.flat_map { |label| ["-f", "labels[]=#{label}"] }
+      _out, err, ok = @exec.capture(*argv)
+      raise AmendError, "could not amend the labels of runner #{runner_id} at #{scope}: #{err.strip}" unless ok
+    end
+
+    private
+
+    # The API path prefix for a scope, following its shape (repos/... for
+    # "owner/repo", orgs/... for a bare org) — same convention as
+    # RunnerSetup's token minting.
+    #
+    # @param scope [String]
+    # @return [String]
+    sig { params(scope: String).returns(String) }
+    def api_base(scope)
+      scope.include?("/") ? "repos/#{scope}" : "orgs/#{scope}"
+    end
+  end
+end
diff --git a/test/dev/runner_discovery_test.rb b/test/dev/runner_discovery_test.rb
new file mode 100644
index 0000000..763ae60
--- /dev/null
+++ b/test/dev/runner_discovery_test.rb
@@ -0,0 +1,73 @@
+# typed: false
+# frozen_string_literal: true
+
+require "test_helper"
+require "dev/runner_discovery"
+require "tmpdir"
+require "fileutils"
+require "json"
+
+transform!(RSpock::AST::Transformation)
+class Dev::RunnerDiscoveryTest < Minitest::Test
+  test "enrollments reads every configured actions-runner dir under home" do
+    Given "a home with two configured runner dirs and one unconfigured"
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs", name: "JeanPhiippesMBP")
+    write_runner(home, "actions-runner-ue-engine", scope: "d3mlabs/unreal-engine", name: "gaming-box")
+    FileUtils.mkdir_p(File.join(home, "actions-runner-fresh")) # downloaded, never configured
+
+    When "discovering"
+    enrollments = Dev::RunnerDiscovery.new(home: home).enrollments
+
+    Then "each .runner record surfaces as an enrollment, dir-ordered; the unconfigured dir is silent"
+    enrollments.map { |e| [e.dir, e.scope, e.name] } == [
+      [File.join(home, "actions-runner-cellbound3d"), "d3mlabs", "JeanPhiippesMBP"],
+      [File.join(home, "actions-runner-ue-engine"), "d3mlabs/unreal-engine", "gaming-box"],
+    ]
+  end
+
+  test "for_scope finds the enrollment serving a scope regardless of its dir name" do
+    Given "an org enrollment living in a repo-named dir (its pre-org history)"
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs", name: "JeanPhiippesMBP")
+
+    When "looking up the org scope"
+    enrollment = Dev::RunnerDiscovery.new(home: home).for_scope("d3mlabs")
+
+    Then "the dir name does not matter — the .runner record does"
+    enrollment.dir == File.join(home, "actions-runner-cellbound3d")
+    enrollment.name == "JeanPhiippesMBP"
+  end
+
+  test "for_scope is nil when no enrollment serves the scope" do
+    Given "a home with only a repo-scoped enrollment"
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs/cellbound-3d", name: "box")
+
+    Expect
+    Dev::RunnerDiscovery.new(home: home).for_scope("d3mlabs").nil?
+  end
+
+  test "read parses the BOM config.sh writes and nils out garbage" do
+    Given "a dir whose .runner is not JSON"
+    home = Dir.mktmpdir
+    dir = File.join(home, "actions-runner-broken")
+    FileUtils.mkdir_p(dir)
+    File.write(File.join(dir, ".runner"), "not json")
+
+    Expect "garbage reads as unconfigured, never raises"
+    Dev::RunnerDiscovery.read(dir).nil?
+    Dev::RunnerDiscovery.new(home: home).enrollments == []
+  end
+
+  private
+
+  # A .runner record the way config.sh writes it: UTF-8 BOM + JSON with
+  # gitHubUrl/agentName (scope "owner" or "owner/repo").
+  def write_runner(home, dir_name, scope:, name:)
+    dir = File.join(home, dir_name)
+    FileUtils.mkdir_p(dir)
+    record = { "agentName" => name, "gitHubUrl" => "https://github.com/#{scope}", "workFolder" => "_work" }
+    File.write(File.join(dir, ".runner"), "\uFEFF#{JSON.pretty_generate(record)}")
+  end
+end
diff --git a/test/dev/runner_registry_test.rb b/test/dev/runner_registry_test.rb
new file mode 100644
index 0000000..bba2d05
--- /dev/null
+++ b/test/dev/runner_registry_test.rb
@@ -0,0 +1,118 @@
+# typed: false
+# frozen_string_literal: true
+
+require "test_helper"
+require "dev/runner_registry"
+require "json"
+
+transform!(RSpock::AST::Transformation)
+class Dev::RunnerRegistryTest < Minitest::Test
+  # Answers capture calls from a responder and records each argv.
+  class RecordingExecutor
+    attr_reader :captures
+
+    def initialize(&responder)
+      @responder = responder
+      @captures = []
+    end
+
+    def capture(*argv)
+      @captures << argv
+      @responder ? @responder.call(argv) : ["", "", true]
+    end
+  end
+
+  test "find returns the named runner's id and custom labels at an org scope" do
+    Given "a gh answering with two runners, one line each"
+    lines = [
+      runner_json(id: 7, name: "other-box", custom: ["ue-engine"]),
+      runner_json(id: 42, name: "JeanPhiippesMBP", custom: %w[ai-ask ai-build]),
+    ].join("\n")
+    exec = RecordingExecutor.new { [lines, "", true] }
+    registry = Dev::RunnerRegistry.new(executor: exec)
+
+    When "finding by name"
+    runner = registry.find(scope: "d3mlabs", name: "JeanPhiippesMBP")
+
+    Then "the org endpoint is paginated and the read-only labels are excluded"
+    exec.captures == [["gh", "api", "--paginate", "orgs/d3mlabs/actions/runners", "--jq", ".runners[]"]]
+    runner.id == 42
+    runner.custom_labels == %w[ai-ask ai-build]
+  end
+
+  test "find hits the repos endpoint for a repo scope" do
+    Given "a gh answering with one runner"
+    exec = RecordingExecutor.new { [runner_json(id: 1, name: "box", custom: ["cellbound3d"]), "", true] }
+    registry = Dev::RunnerRegistry.new(executor: exec)
+
+    When "finding at a repo scope"
+    registry.find(scope: "d3mlabs/cellbound-3d", name: "box")
+
+    Then
+    exec.captures.fetch(0).fetch(3) == "repos/d3mlabs/cellbound-3d/actions/runners"
+  end
+
+  test "find is nil when no runner of that name is enrolled at the scope" do
+    Given "a gh answering with unrelated runners"
+    exec = RecordingExecutor.new { [runner_json(id: 7, name: "other-box", custom: []), "", true] }
+    registry = Dev::RunnerRegistry.new(executor: exec)
+
+    Expect
+    registry.find(scope: "d3mlabs", name: "JeanPhiippesMBP").nil?
+  end
+
+  test "find raises when GitHub cannot be queried" do
+    Given "a gh that fails (offline, auth)"
+    exec = RecordingExecutor.new { ["", "connect: network is unreachable", false] }
+    registry = Dev::RunnerRegistry.new(executor: exec)
+
+    When "finding"
+    registry.find(scope: "d3mlabs", name: "box")
+
+    Then "the failure is loud, never a silent not-found"
+    error = raises Dev::RunnerRegistry::QueryError
+    error.message.include?("network is unreachable")
+  end
+
+  test "amend! replaces the runner's custom labels in place" do
+    Given "a recording gh"
+    exec = RecordingExecutor.new { ["", "", true] }
+    registry = Dev::RunnerRegistry.new(executor: exec)
+
+    When "amending"
+    registry.amend!(scope: "d3mlabs", runner_id: 42, labels: %w[ai-ask ai-edit ai-build ai-split ai-learn])
+
+    Then "one PUT carries the full custom set"
+    exec.captures == [[
+      "gh", "api", "-X", "PUT", "orgs/d3mlabs/actions/runners/42/labels",
+      "-f", "labels[]=ai-ask", "-f", "labels[]=ai-edit", "-f", "labels[]=ai-build",
+      "-f", "labels[]=ai-split", "-f", "labels[]=ai-learn"
+    ]]
+  end
+
+  test "amend! raises when the PUT fails" do
+    Given "a gh refusing the amend"
+    # A lambda (not a plain block): blocks auto-splat their single array
+    # argument under RSpock's transformation.
+    responder = ->(argv) { argv.include?("PUT") ? ["", "HTTP 403", false] : ["", "", true] }
+    exec = RecordingExecutor.new(&responder)
+    registry = Dev::RunnerRegistry.new(executor: exec)
+
+    When "amending"
+    registry.amend!(scope: "d3mlabs", runner_id: 42, labels: ["ai-ask"])
+
+    Then
+    error = raises Dev::RunnerRegistry::AmendError
+    error.message.include?("HTTP 403")
+  end
+
+  private
+
+  # One `--jq .runners[]` output line: GitHub's runner object with read-only
+  # labels (self-hosted, OS, arch) alongside the custom ones.
+  def runner_json(id:, name:, custom:)
+    labels = [{ "name" => "self-hosted", "type" => "read-only" }] +
+             custom.map { |l| { "name" => l, "type" => "custom" } }
+    JSON.generate({ "id" => id, "name" => name, "labels" => labels })
+  end
+end

From 9aef370a91271db61b8fd8b6a8e409c8fe5ecaa3 Mon Sep 17 00:00:00 2001
From: Jean-Philippe <jpduchesne89@gmail.com>
Date: Sat, 12 Sep 2026 20:50:34 -0400
Subject: [PATCH 2/3] dev runner: scope x labels with derived defaults; retire
 the dev.yml runner block
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enrollment identity is a machine fact, not a repo declaration (plans#26):

- Bare `dev runner register` enrolls repo-scoped with the label derived
  from the manifest name (ProjectManifest#slug — the name is the package
  identity, the org the registry); --org composes with --ai-flow (the
  full ai-flow vocabulary, mirrored as LabelContracts::AI_FLOW_LABELS)
  or --labels. --org needs no checkout; runner is ungated (projectless
  catalog included) and runner-setup stays an alias.
- Idempotent and self-healing: register discovers an existing enrollment
  at the target scope (RunnerDiscovery over every local runner dir) and
  amends its labels in place on GitHub (RunnerRegistry PUT) instead of
  re-enrolling; contracts converge every run; a stale local dir whose
  runner is gone server-side re-enrolls into the same dir.
- status is discovery-based — the machine's view, never a repo's:
  scope/name from .runner records (offline-safe), labels from GitHub
  (unknown when offline, flagged when gone), agent facts per agent-
  labeled enrollment.
- dev.yml `runner:` is retired (warns and is ignored); RUNNER_HOST_KEYS
  and the manifest/context runner fields are gone; RunnerSetupConfig is
  now flag-resolved only. ProjectContext carries the manifest name.

Closes #161.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md                                     |  20 +-
 lib/dev/label_contracts.rb                    |   9 +
 lib/dev/runner_setup.rb                       |  24 +-
 lib/dev/runner_status.rb                      | 110 +++--
 src/dev/builtins/runner_command.rb            | 182 ++++++---
 src/dev/execution_context.rb                  |   5 +-
 src/dev/project_manifest.rb                   |  37 +-
 src/dev/project_manifest_loader.rb            |  55 +--
 src/dev/runner.rb                             |  40 +-
 src/dev/runner_setup_config.rb                |  23 +-
 test/dev/builtin_executor_test.rb             |   2 +-
 test/dev/builtins/cache_command_test.rb       |   1 +
 test/dev/builtins/cd_command_test.rb          |   2 +-
 test/dev/builtins/check_command_test.rb       |   2 +-
 test/dev/builtins/clone_command_test.rb       |   2 +-
 test/dev/builtins/config_command_test.rb      |   2 +-
 test/dev/builtins/cred_command_test.rb        |   2 +-
 test/dev/builtins/deps_command_test.rb        |   2 +-
 test/dev/builtins/help_command_test.rb        |   2 +-
 .../dev/builtins/install_deps_command_test.rb |   2 +-
 test/dev/builtins/learnings_command_test.rb   |   2 +-
 test/dev/builtins/plan_command_test.rb        |   2 +-
 .../builtins/provide_image_command_test.rb    |   1 +
 .../builtins/reset_container_command_test.rb  |   1 +
 test/dev/builtins/runner_command_test.rb      | 377 ++++++++++++------
 test/dev/builtins/up_command_test.rb          |   1 +
 test/dev/builtins/update_deps_command_test.rb |   2 +-
 test/dev/command_executor_test.rb             |   2 +-
 test/dev/command_service_test.rb              |   2 +-
 test/dev/execution_context_test.rb            |   2 +-
 test/dev/overridden_executor_test.rb          |   2 +-
 test/dev/project_manifest_loader_test.rb      | 124 +-----
 test/dev/runner_status_test.rb                | 124 ++++--
 test/dev/runner_test.rb                       |  25 +-
 34 files changed, 715 insertions(+), 476 deletions(-)

diff --git a/README.md b/README.md
index 68fa4b7..59a90ed 100644
--- a/README.md
+++ b/README.md
@@ -178,13 +178,23 @@ Because the wrapper runs `builtin cd` in your interactive shell, shadowenv activ
 
 ## dev runner — enroll a host as a self-hosted runner
 
-Repos opt in by declaring a `runner:` block in `dev.yml` (labels required; `dir`/`name`/`version` optional), so every repo declares only its runner identity instead of vendoring a setup script. The command exists only where that block does. It is a machine-setup verb: rare, admin-flavored, human-run.
+A machine-setup verb: rare, admin-flavored, human-run — and declared nowhere. Enrollment identity is a machine fact, not a repo one, so there is no `runner:` block in dev.yml (the key is retired and warns): scope and labels compose from flags, with derived defaults covering the common enrollments.
 
-**`dev runner register`** converges, then enrolls. First the **label contracts**: a capability label is not just routing metadata — it names an obligation the host must satisfy, and register converges the (possibly empty) requirements of every label being advertised. A bare target-host label (e.g. a gamebox) converges nothing; the agent capability labels (`ai-build`, `ai-learn`) mark the box an **agent host** and carry the **agent host bootstrap** (below). Then the enrollment ceremony, per repo served: actions-runner download, registration-token mint via your `gh` auth, `config.sh --unattended --replace`, service install — idempotent, including across scopes (a repo-scoped runner re-registered `--org` deregisters at its old scope first). Flags: `--org` (one runner serving the whole org), `--repo`, and `--labels`/`--dir`/`--name` overrides for hosts that differ from the block's default; `--agent-user` overrides the `ai-agent` run-as default. `dev runner-setup` survives as an alias for `register`.
+```bash
+dev runner register                     # repo scope; label derived from the project name
+dev runner register --labels ue-engine  # repo scope, custom roles
+dev runner register --org --ai-flow     # org agent host: the full ai-flow label set
+dev runner register --org --labels ai-build   # org custom pool (e.g. a beefy build box)
+dev runner status                       # THIS machine's enrollments + host facts
+```
+
+**Demand and supply.** Workflows demand labels (`runs-on: [self-hosted, <label>]`); enrollments supply them. GitHub routes a job to any online runner visible to the repo (its own repo-scoped runners plus the org's) whose labels cover the demand — first available wins, with **no repo-beats-org priority**. So an org agent host and a repo-scoped `ai-build` box sharing a label is capacity pooling; a strict partition is expressed through label sets, never through scope. Three vocabularies exist today: a repo's own CI label, **derived from its dev.yml `name:`** (normalized: `Cellbound3D` → `cellbound3d` — the manifest name is the package identity, the ecosystem norm, and the org is the registry giving it uniqueness); special fleets' explicit `--labels` (e.g. unreal-engine's `ue-engine` / `macos,ue-editor` boxes); and the **ai-flow vocabulary** (`ai-ask ai-edit ai-split ai-build ai-learn`) — defined by ai-flow's reusable workflow (one label per slash command), mirrored here as `LabelContracts::AI_FLOW_LABELS` behind `--ai-flow`.
+
+**`dev runner register`** converges, then enrolls. First the **label contracts**: a capability label is not just routing metadata — it names an obligation the host must satisfy, and register converges the (possibly empty) requirements of every label being advertised. A bare target-host label (e.g. a gamebox) converges nothing; the agent capability labels (`ai-build`, `ai-learn`) mark the box an **agent host** and carry the **agent host bootstrap** (below). Then the enrollment: register looks for an existing enrollment at the target scope (every `~/actions-runner-*/.runner` on the host — dir names never matter) and **amends its labels in place on GitHub** instead of re-enrolling, so re-running is both the idempotent no-op and the drift repair; only a scope nothing serves gets the full ceremony (actions-runner download, registration-token mint via your `gh` auth, `config.sh --unattended --replace`, service install — itself idempotent, including across scopes: a repo-scoped runner re-registered `--org` deregisters at its old scope first). Enrollment state is **inspected, never recorded**: labels live on GitHub, the scope in the runner dir's own `.runner` record — nothing in dev.yml, Settings, or any inventory file. Flags: `--org`, `--repo`, `--ai-flow`, and `--labels`/`--dir`/`--name` identity overrides; `--agent-user` overrides the `ai-agent` run-as default. `--org` needs no project checkout; bare register does (the derivation source). `dev runner-setup` survives as an alias for `register`.
 
-The **agent host bootstrap** is host-singular, idempotent, and admin-prompting (re-running register re-converges — that is also the drift repair; macOS-only today). Every fact is inspectable and none is recorded — there is no record file. It converges: the hidden non-admin agent user with its own home; the cooperative `ai` group with both identities enrolled; the one-way sudoers edge (runner user → agent, `NOPASSWD:SETENV`, staged and `visudo -c` validated before landing root-owned 0440); the shared data root with the one-off `~/.dev` migration (below); the agent's own container engine when the served repo declares `build.container` (colima via brew, the agent's `container_engine: colima` record, its VM sized from the repo's `resources:` hint); and after enrollment, the `_work` job-checkout tree as a cooperative group space plus the runner service env — `Umask` 002 and `AI_FLOW_AGENT_USER`, the single record of "jobs landing here execute as X".
+The **agent host bootstrap** is host-singular, idempotent, and admin-prompting (macOS-only today). Every fact is inspectable and none is recorded — there is no record file. It converges: the hidden non-admin agent user with its own home; the cooperative `ai` group with both identities enrolled; the one-way sudoers edge (runner user → agent, `NOPASSWD:SETENV`, staged and `visudo -c` validated before landing root-owned 0440); the shared data root with the one-off `~/.dev` migration (below); the agent's own container engine when the enrolling checkout declares `build.container` (colima via brew, the agent's `container_engine: colima` record, its VM sized from the repo's `resources:` hint); and after enrollment, the `_work` job-checkout tree as a cooperative group space plus the runner service env — `Umask` 002 and `AI_FLOW_AGENT_USER`, the single record of "jobs landing here execute as X".
 
-**`dev runner status`** is the inspect-only half: the checkout's `runner:` block vs this host's registration (read from the runner's own `.runner` record — works offline), plus the re-derived reality of each advertised label's contract (agent user, group memberships, sudoers edge, `_work` grant, shared root, agent engine where required) and host tooling (`brew bundle check` against the org Brewfile, self-skipping when none ships).
+**`dev runner status`** is the inspect-only half, and it is the *machine's* view, not any repo's: every discovered enrollment (scope and name from its own `.runner` record — works offline), each one's labels read from GitHub (their single home; unknown when offline, flagged when the runner is gone server-side), the re-derived reality of each agent-labeled enrollment's contract (agent user, group memberships, sudoers edge, `_work` grant, shared root, agent engine where required), and host tooling (`brew bundle check` against the org Brewfile, self-skipping when none ships).
 
 ### The data root (shared on agent hosts)
 
@@ -433,7 +443,7 @@ Custom integrations implement `Dev::Deps::Integration` (with `install_all(pins,
 - **`dev cd <repo>`** — jump to a checkout under `$DEV_CD_ROOT` (default `~/src`) by fuzzy name, with Tab completion (see [dev cd](#dev-cd--jump-between-checkouts)). Global: works without a `dev.yml`.
 - **`dev clone [<org>/]<repo>`** — clone a GitHub repo via your `gh` auth into the canonical `$DEV_CD_ROOT/github.com/<org>/<repo>` path (org defaults to `d3mlabs`) and land there (see [dev clone](#dev-clone--clone-into-the-canonical-layout)). Clone-only — run `dev up` yourself. Global: works without a `dev.yml`.
 - **`dev cache gc [--keep N]`** — reclaim host caches dev owns (see below).
-- **`dev runner register|status`** — enroll this host as the repo's self-hosted GitHub Actions runner (converging the advertised labels' contracts first), or inspect the registration and host facts (see [dev runner](#dev-runner--enroll-a-host-as-a-self-hosted-runner)). Registered only when `dev.yml` declares a `runner:` block; `dev runner-setup` is an alias for `register`.
+- **`dev runner register|status`** — enroll this host as a self-hosted GitHub Actions runner (repo-scoped with a label derived from the project name, or `--org` with `--ai-flow`/`--labels`; contracts converge first, existing enrollments are label-amended in place), or inspect this machine's enrollments and host facts (see [dev runner](#dev-runner--enroll-a-host-as-a-self-hosted-runner)). Ungated — exists everywhere; `dev runner-setup` is an alias for `register`.
 - **`dev reset-container`** — remove the persistent build container (clears its incremental cache); registered only when `build.container.persist` is set.
 - **`dev plan …`** — global (works without a `dev.yml`; the workspace is the nearest dev.yml or git root). Sync Cursor plans with GitHub issues (ai-flow): the issue is the canonical plan, the local `.cursor/plans/gh-<n>-<slug>.plan.md` is a transient working copy carrying an `<!-- ai-flow … -->` header. Subcommands: `new "<title>" [--blank] [--org]` (create issue + linked plan — templated by default with the tech-design document (brief sections + `## Tech design` skeleton), resolved from the target repo's committed `.github/ISSUE_TEMPLATE/plan.md` when present (with a staleness warning when that mirror lags dev's bundle) else dev's bundled `share/plan-templates/tech-design.md`; `--blank` scaffolds just the H1; `--org` scaffolds a `Target repos:` line), `link <n> [<file>]` / `link <file>` (attach a draft to an existing issue / create one from it), `pull <n> [--merge]` (fetch, 3-way merging when both sides changed — the merge base lives at `~/.local/state/ai-flow/`), `push [<file>|<n>]` (guarded body PATCH — refuses to clobber newer remote edits; a number resolves the linked plan like `pull`), `status` (clean / ahead / behind / diverged, per linked plan), and `init` (materialize/update the plan template mirror at `.github/ISSUE_TEMPLATE/plan.md` in the working tree — review with `git diff`, then commit; only mirrors still carrying dev's marker comment are ever overwritten, so a repo customizes its template by editing the file and dropping the marker). `Dev::Plan::Templates` is the canonical owner of the template and mirror layout. `--org` targets the org plans repo (`plans_repo:` in `~/.config/dev/config.yml`, or `DEV_PLANS_REPO`) instead of the current repo's origin. Every invocation also refreshes the user-global links for dev's shipped skills (`share/cursor-skills/*` → `~/.cursor/skills/`, so the Cursor agent knows these verbs) and the org learnings artifacts (see [Agent skills & org learnings](#agent-skills--org-learnings)). For auto-push, a participating repo adds a Cursor `afterFileEdit` hook to `.cursor/hooks.json` running `dev plan hook-after-edit` — it reads the hook payload from stdin and no-ops unless the edited file is a linked plan. What happens to a plan after it's canonical — `/ask`, `/edit`, `/split` (two-phase dry/apply), `/build` — is ai-flow's remote half: see [plan-lifecycle.md](https://github.com/d3mlabs/ai-flow/blob/HEAD/docs/plan-lifecycle.md) and [commands.md](https://github.com/d3mlabs/ai-flow/blob/HEAD/docs/commands.md).
 - **`dev learnings sync|status|invariants|init`** — global (works without a `dev.yml`). `sync` refreshes the whole learnings read path now, blocking, errors bubbling: pull the machine cache of the knowledge repo, relink skills (shipped, org, and the project's gem skills), render the invariants rule and link it into the enclosing project. Outside a project the machine-global parts run and the project-scoped ones are skipped. `status` reports the configured knowledge repo, cache location and age, and what's rendered/linked per tier. `invariants` prints the Tier-0 prompt block (the invariants section extracted from the org index) — the seam prompt-building consumers like ai-flow shell out to instead of parsing the cache themselves. `init` scaffolds the canonical empty learnings layout at the enclosing repo's root: the repo-tier index (`.cursor/rules/learnings-index.mdc` with its `alwaysApply: true` front matter, capture/curation preamble, soft cap, and org-tier trailer — no entries), or with `--org` the knowledge-repo layout (`index.md` with the fixed `## Invariants (always-on)` / `## Knowledge (on-demand)` section structure `dev learnings sync` parses, plus the `skills/` corpus directory) for a new org adopting the loop. The scaffold is **write-once-committed**: an existing index is reported and left untouched (exit 0), so consumers such as ai-flow's `/learn` call `init` unconditionally before capturing into an unseeded repo. `Dev::Learnings::Layout` is the canonical owner of both tiers' paths and templates. See [Agent skills & org learnings](#agent-skills--org-learnings).
diff --git a/lib/dev/label_contracts.rb b/lib/dev/label_contracts.rb
index afdc9b2..ae9ba0b 100644
--- a/lib/dev/label_contracts.rb
+++ b/lib/dev/label_contracts.rb
@@ -20,6 +20,15 @@ class LabelContracts
     # The capability labels whose contract is the agent host bootstrap.
     AGENT_CAPABILITY_LABELS = T.let(%w[ai-build ai-learn].freeze, T::Array[String])
 
+    # The full ai-flow label vocabulary — one label per slash command,
+    # routed by ai-flow's reusable workflow (`runner="ai-${word}"`). ai-flow
+    # defines the vocabulary (its README "Adoption checklist" names this
+    # list as the contract); this is dev's documented mirror — a cross-repo
+    # literal duplicated knowingly, like the agent user/group names —
+    # behind `dev runner register --org --ai-flow` (the agent host enrolls
+    # with the full set; a partitioned topology passes --labels instead).
+    AI_FLOW_LABELS = T.let(%w[ai-ask ai-edit ai-split ai-build ai-learn].freeze, T::Array[String])
+
     # The agent host obligation: the host-singular bootstrap, the agent's
     # own container engine when the served repo builds in one, and the
     # post-enrollment service/workdir setup.
diff --git a/lib/dev/runner_setup.rb b/lib/dev/runner_setup.rb
index b358e25..a62edc4 100644
--- a/lib/dev/runner_setup.rb
+++ b/lib/dev/runner_setup.rb
@@ -149,6 +149,19 @@ def resolve_version
       @config.version || DEFAULT_VERSION
     end
 
+    # The registration scope: "owner/repo" (repo mode) or "owner" (org mode —
+    # the org is the resolved repo's owner, so `--org` needs no extra flag).
+    # Public so register can look for an existing enrollment at the target
+    # scope before deciding between the amend path and a fresh enrollment.
+    #
+    # @return [String]
+    # @raise [Error] when the repo can't be resolved
+    sig { returns(String) }
+    def resolve_scope
+      repo = resolve_repo
+      @org ? repo.split("/").fetch(0) : repo
+    end
+
     # The argv `config.sh` is invoked with (relative to the runner dir). Pure, so
     # the registration contract is testable without touching the system.
     #
@@ -190,17 +203,6 @@ def ensure_gh_authenticated!
       raise Error, "gh is not authenticated — run: gh auth login"
     end
 
-    # The registration scope: "owner/repo" (repo mode) or "owner" (org mode —
-    # the org is the resolved repo's owner, so `--org` needs no extra flag).
-    #
-    # @return [String]
-    # @raise [Error] when the repo can't be resolved
-    sig { returns(String) }
-    def resolve_scope
-      repo = resolve_repo
-      @org ? repo.split("/").fetch(0) : repo
-    end
-
     # @return [String] "owner/repo"
     # @raise [Error] when the repo can't be resolved
     sig { returns(String) }
diff --git a/lib/dev/runner_status.rb b/lib/dev/runner_status.rb
index 6a78fce..a662ff1 100644
--- a/lib/dev/runner_status.rb
+++ b/lib/dev/runner_status.rb
@@ -2,27 +2,29 @@
 # frozen_string_literal: true
 
 require "etc"
-require "json"
 require "stringio"
 
 require "dev/agent_bootstrap"
 require "dev/data_root"
 require "dev/label_contracts"
-require "dev/runner_setup"
-require "dev/runner_setup_config"
+require "dev/runner_discovery"
+require "dev/runner_registry"
 require "dev/settings"
 
 module Dev
-  # `dev runner status` — register's inspect-only counterpart:
-  # the checkout's `runner:` block vs this host's registration, plus the
-  # inspected reality of each advertised label's contract. Nothing here
-  # mutates and nothing is recorded — every fact is re-derived from the
-  # host every time (plans#26: inspected, never recorded).
+  # `dev runner status` — register's inspect-only counterpart: this
+  # machine's discovered enrollments (every ~/actions-runner-*/.runner),
+  # each one's labels read from GitHub (their single home — unknown when
+  # offline), and the inspected reality of every agent-labeled enrollment's
+  # contract. Nothing here mutates and nothing is recorded — every fact is
+  # re-derived from the host or GitHub every time (plans#26: inspected,
+  # never recorded). No dev.yml involved: status is the machine's view,
+  # not any repo's.
   class RunnerStatus
     extend T::Sig
 
-    # @param config [Dev::RunnerSetupConfig] the checkout's runner block
-    # @param runner_dir [String] resolved runner install dir
+    # @param discovery [Dev::RunnerDiscovery] this host's enrollments
+    # @param registry [#find] the GitHub-side label reader (never mutates here)
     # @param out [IO, StringIO] report stream
     # @param executor [#quiet?, #capture] probe seam (never mutates)
     # @param agent_user [String] expected run-as user
@@ -33,8 +35,8 @@ class RunnerStatus
     # @param container_required [Boolean] whether the served repo declares build.container
     sig do
       params(
-        config: Dev::RunnerSetupConfig,
-        runner_dir: String,
+        discovery: Dev::RunnerDiscovery,
+        registry: T.untyped,
         out: T.any(IO, StringIO),
         executor: T.untyped,
         agent_user: String,
@@ -45,7 +47,7 @@ class RunnerStatus
         container_required: T::Boolean,
       ).void
     end
-    def initialize(config:, runner_dir: Dev::RunnerSetup.new(config: config).resolve_dir,
+    def initialize(discovery: Dev::RunnerDiscovery.new, registry: Dev::RunnerRegistry.new,
                    out: $stdout, executor: AgentBootstrap::Executor.new,
                    agent_user: AgentBootstrap::DEFAULT_AGENT_USER,
                    runner_user: T.must(Etc.getpwuid(Process.uid)).name,
@@ -53,8 +55,8 @@ def initialize(config:, runner_dir: Dev::RunnerSetup.new(config: config).resolve
                    sudoers_path: AgentBootstrap::SUDOERS_PATH,
                    brewfile_path: self.class.default_brewfile_path,
                    container_required: false)
-      @config = config
-      @runner_dir = runner_dir
+      @discovery = discovery
+      @registry = registry
       @out = out
       @executor = executor
       @agent_user = agent_user
@@ -78,13 +80,13 @@ def default_brewfile_path
       end
     end
 
-    # Print the report: registration, per-label facts, host tooling.
+    # Print the report: every enrollment, per-label facts, host tooling.
     #
     # @return [void]
     sig { void }
     def report
-      report_registration
-      report_agent_host if LabelContracts.agent_host?(@config.labels)
+      agent_dirs = report_enrollments
+      report_agent_host(agent_dirs) unless agent_dirs.empty?
       report_host_tooling
     end
 
@@ -97,33 +99,54 @@ def line(ok, description)
       @out.puts "  #{ok ? "[ok]" : "[!!]"} #{description}"
     end
 
-    # The checkout's expected identity vs the enrolled reality, read from
-    # the runner's own .runner record (never GitHub — status works offline).
-    sig { void }
-    def report_registration
-      @out.puts "Runner (labels: #{@config.labels}, dir: #{@runner_dir}):"
-      scope = registered_scope
-      if scope
-        line(true, "registered: #{scope}")
-      else
-        line(false, "not registered (run `dev runner register`)")
+    # Each discovered enrollment: scope from its own .runner record (works
+    # offline), labels from GitHub. Returns the dirs of enrollments whose
+    # labels carry the agent contract, so the agent host section can check
+    # each one's work tree.
+    #
+    # @return [Array<String>] agent-labeled enrollment dirs
+    sig { returns(T::Array[String]) }
+    def report_enrollments
+      enrollments = @discovery.enrollments
+      if enrollments.empty?
+        @out.puts "No runners enrolled on this host (run `dev runner register`)."
+        return []
+      end
+
+      enrollments.filter_map do |enrollment|
+        @out.puts "Runner '#{enrollment.name}' (#{enrollment.dir}):"
+        line(true, "registered: #{enrollment.scope}")
+        labels = report_labels(enrollment)
+        enrollment.dir if labels && LabelContracts.agent_host?(labels.join(","))
       end
     end
 
-    # @return [String, nil] "owner/repo" or "owner" when enrolled, else nil
-    sig { returns(T.nilable(String)) }
-    def registered_scope
-      raw = File.read(File.join(@runner_dir, ".runner"), encoding: "bom|utf-8")
-      url = JSON.parse(raw)["gitHubUrl"].to_s
-      scope = url.sub(%r{\Ahttps://github\.com/}, "").chomp("/")
-      scope.empty? || scope == url ? nil : scope
-    rescue JSON::ParserError, Errno::ENOENT
+    # The enrollment's custom labels, read from their single home — GitHub.
+    # nil when they can't be known (offline) or the runner is gone
+    # server-side (a stale local dir).
+    #
+    # @param enrollment [Dev::RunnerDiscovery::Enrollment]
+    # @return [Array<String>, nil]
+    sig { params(enrollment: Dev::RunnerDiscovery::Enrollment).returns(T.nilable(T::Array[String])) }
+    def report_labels(enrollment)
+      runner = @registry.find(scope: enrollment.scope, name: enrollment.name)
+      if runner.nil?
+        line(false, "gone on GitHub — stale enrollment (re-run `dev runner register`)")
+        return nil
+      end
+
+      line(true, "labels: #{runner.custom_labels.join(", ")}")
+      runner.custom_labels
+    rescue RunnerRegistry::QueryError => e
+      line(false, "labels unknown (#{e.message})")
       nil
     end
 
     # Every fact the agent contract obliges, re-derived from the host.
-    sig { void }
-    def report_agent_host
+    #
+    # @param runner_dirs [Array<String>] the agent-labeled enrollment dirs
+    sig { params(runner_dirs: T::Array[String]).void }
+    def report_agent_host(runner_dirs)
       @out.puts "Agent host (#{@agent_user}):"
       line(@executor.quiet?("id", "-u", @agent_user), "agent user #{@agent_user} exists")
       [@runner_user, @agent_user].each do |member|
@@ -133,7 +156,9 @@ def report_agent_host
         line(member_ok, "#{member} in the #{AgentBootstrap::GROUP} group")
       end
       line(File.exist?(@sudoers_path), "sudoers edge present (#{@sudoers_path})")
-      line(work_tree_cooperative?, "_work tree cooperative (group #{AgentBootstrap::GROUP}, setgid)")
+      runner_dirs.each do |dir|
+        line(work_tree_cooperative?(dir), "_work tree cooperative in #{dir} (group #{AgentBootstrap::GROUP}, setgid)")
+      end
       line(File.directory?(@shared_root), "shared root present (#{@shared_root})")
       return unless @container_required
 
@@ -142,10 +167,11 @@ def report_agent_host
 
     # Group + setgid facts via stat, so inspection needs no privileges.
     #
+    # @param runner_dir [String]
     # @return [Boolean]
-    sig { returns(T::Boolean) }
-    def work_tree_cooperative?
-      work = File.join(@runner_dir, "_work")
+    sig { params(runner_dir: String).returns(T::Boolean) }
+    def work_tree_cooperative?(runner_dir)
+      work = File.join(runner_dir, "_work")
       return false unless File.directory?(work)
 
       group, perms = @executor.capture("stat", "-f", "%Sg %Sp", work).strip.split(" ", 2)
diff --git a/src/dev/builtins/runner_command.rb b/src/dev/builtins/runner_command.rb
index e5188e0..3f89895 100644
--- a/src/dev/builtins/runner_command.rb
+++ b/src/dev/builtins/runner_command.rb
@@ -4,6 +4,9 @@
 require "dev/cli/flag_parser"
 require "dev/command"
 require "dev/label_contracts"
+require "dev/project_manifest"
+require "dev/runner_discovery"
+require "dev/runner_registry"
 require "dev/runner_setup"
 require "dev/runner_setup_config"
 require "dev/runner_status"
@@ -11,19 +14,32 @@
 module Dev
   module Builtins
     # `dev runner <register|status>` — layers 3+4 of the machine doctrine
-    # (plans#26): converge, then enroll.
+    # (plans#26): converge, then enroll. Scope and labels compose
+    # orthogonally, with derived defaults so the common enrollments need no
+    # declaration anywhere (the dev.yml `runner:` block is retired):
     #
-    # `register` first converges the label contracts of every advertised
-    # label (agent-capability labels carry the agent host bootstrap; bare
-    # labels converge nothing), then performs the enrollment ceremony —
-    # unchanged from the old `runner-setup`, which survives as an alias —
-    # and finally the post-enrollment steps against the enrolled runner
-    # dir. Repo-scoped by default, org-scoped with `--org`;
-    # `--labels`/`--dir`/`--name`/`--repo` override the dev.yml block;
-    # `--agent-user` overrides the ai-agent default run-as user.
+    #   dev runner register                    # repo scope; label = the project slug
+    #   dev runner register --labels ue-engine # repo scope, custom roles
+    #   dev runner register --org --ai-flow    # org agent host, the full ai-flow set
+    #   dev runner register --org --labels ai-build  # org custom pool
     #
-    # Exists only when a project declares a `runner:` block (the composition
-    # root gates it), so the command surfaces only where it applies.
+    # register is idempotent and self-healing: it converges every advertised
+    # label's contract (agent-capability labels carry the agent host
+    # bootstrap; bare labels converge nothing), then looks for an existing
+    # enrollment at the target scope (RunnerDiscovery — every local runner
+    # dir, so dir names never matter) and amends its labels in place on
+    # GitHub (RunnerRegistry) instead of re-enrolling; only a scope nothing
+    # serves gets the full enrollment ceremony (RunnerSetup, unchanged from
+    # the old `runner-setup`, which survives as an alias).
+    #
+    # Enrollment state is inspected, never recorded: the labels live on
+    # GitHub, the scope in the runner dir's own .runner record — nothing in
+    # dev.yml, Settings, or any inventory file.
+    #
+    # `--org` needs no project; bare register derives its label from the
+    # enclosing checkout's manifest name. `--dir`/`--name`/`--repo` override
+    # the enrollment identity; `--agent-user` the ai-agent default run-as
+    # user.
     class RunnerCommand < BuiltinCommand
       extend T::Sig
 
@@ -47,10 +63,7 @@ class RunnerCommand < BuiltinCommand
 
       # Builds the status inspector; injected for tests.
       StatusFactory = T.type_alias do
-        T.proc.params(
-          config: RunnerSetupConfig,
-          container_required: T::Boolean,
-        ).returns(Dev::RunnerStatus)
+        T.proc.params(container_required: T::Boolean).returns(Dev::RunnerStatus)
       end
 
       sig do
@@ -58,24 +71,32 @@ class RunnerCommand < BuiltinCommand
           runner_setup_factory: RunnerSetupFactory,
           contracts_factory: ContractsFactory,
           runner_status_factory: StatusFactory,
+          discovery: Dev::RunnerDiscovery,
+          registry: T.untyped,
           flag_parser: Cli::FlagParser,
+          out: T.any(IO, StringIO),
           implied_subcommand: T.nilable(String),
         ).void
       end
       def initialize(
         runner_setup_factory: ->(config, repo, org) { Dev::RunnerSetup.new(config:, repo:, org:) },
         contracts_factory: ->(labels, agent_user) { Dev::LabelContracts.for(labels, agent_user: agent_user) },
-        runner_status_factory: ->(config, container_required) {
-          Dev::RunnerStatus.new(config: config, container_required: container_required)
-        },
+        runner_status_factory: ->(container_required) { Dev::RunnerStatus.new(container_required:) },
+        discovery: Dev::RunnerDiscovery.new,
+        # The GitHub boundary (#find/#amend!); T.untyped so tests fake it.
+        registry: Dev::RunnerRegistry.new,
         flag_parser: Cli::FlagParser.new,
+        out: $stdout,
         implied_subcommand: nil
       )
         super()
         @runner_setup_factory = runner_setup_factory
         @contracts_factory = contracts_factory
         @runner_status_factory = runner_status_factory
+        @discovery = discovery
+        @registry = registry
         @flag_parser = flag_parser
+        @out = out
         @implied_subcommand = implied_subcommand
       end
 
@@ -114,19 +135,23 @@ def resolve_subcommand(args)
         [args.first, args.drop(1)]
       end
 
-      # Converge, then enroll, then the steps the enrollment enables.
+      # Converge, then enroll (or amend), then the steps the enrollment
+      # enables.
       #
       # @param args [Array<String>]
       # @param context [Dev::ExecutionContext]
       sig { params(args: T::Array[String], context: ExecutionContext).void }
       def register(args, context)
-        cfg = context.project!.runner
-        raise ArgumentError, "no `runner:` block in dev.yml" if cfg.nil?
-
-        cfg = config_with_flag_overrides(cfg, args)
-        contracts = @contracts_factory.call(cfg.labels, @flag_parser.value(args, "--agent-user"))
+        org = args.include?("--org")
+        labels = resolve_labels(args, context, org)
+        config = RunnerSetupConfig.new(
+          labels: labels,
+          dir: @flag_parser.value(args, "--dir"),
+          name: @flag_parser.value(args, "--name"),
+        )
 
-        container = context.project!.build_container
+        contracts = @contracts_factory.call(labels, @flag_parser.value(args, "--agent-user"))
+        container = context.project&.build_container
         contracts.each do |contract|
           contract.converge!(
             container: !container.nil?,
@@ -135,48 +160,95 @@ def register(args, context)
           )
         end
 
-        setup = @runner_setup_factory.call(
-          cfg,
-          # nil repo lets RunnerSetup fall back to `gh repo view`.
-          @flag_parser.value(args, "--repo"),
-          args.include?("--org"),
-        )
-        setup.run
+        setup = @runner_setup_factory.call(config, @flag_parser.value(args, "--repo"), org)
+        enrollment = config.dir ? nil : @discovery.for_scope(setup.resolve_scope)
+        if enrollment && amend_enrollment(setup.resolve_scope, enrollment, config)
+          contracts.each { |contract| contract.after_enroll!(runner_dir: enrollment.dir) }
+          return
+        end
 
+        if enrollment
+          # GitHub has lost this enrollment (or --name renames it): the
+          # re-enrollment reuses the discovered dir, never a second one.
+          config = RunnerSetupConfig.new(labels: labels, dir: enrollment.dir, name: config.name)
+          setup = @runner_setup_factory.call(config, @flag_parser.value(args, "--repo"), org)
+        end
+        setup.run
         contracts.each { |contract| contract.after_enroll!(runner_dir: setup.resolve_dir) }
       end
 
-      # Inspect-only: the block's expected identity vs the enrolled reality
-      # plus every advertised label's contract facts.
+      # The amend path: when the discovered enrollment still exists on
+      # GitHub, converge its custom labels in place — the service, name,
+      # and dir all stay put. False when GitHub no longer knows the runner
+      # (the caller re-enrolls).
+      #
+      # @param scope [String]
+      # @param enrollment [Dev::RunnerDiscovery::Enrollment]
+      # @param config [Dev::RunnerSetupConfig]
+      # @return [Boolean] whether the enrollment was converged in place
+      sig do
+        params(scope: String, enrollment: Dev::RunnerDiscovery::Enrollment, config: RunnerSetupConfig)
+          .returns(T::Boolean)
+      end
+      def amend_enrollment(scope, enrollment, config)
+        name = config.name || enrollment.name
+        runner = @registry.find(scope: scope, name: name)
+        return false if runner.nil?
+
+        desired = config.labels.split(",")
+        if runner.custom_labels.sort == desired.sort
+          @out.puts ">>> Runner '#{name}' already serves #{scope} with labels #{config.labels} — nothing to amend."
+        else
+          @out.puts ">>> Amending labels of '#{name}' at #{scope}: " \
+                    "#{runner.custom_labels.join(",")} -> #{config.labels} ..."
+          @registry.amend!(scope: scope, runner_id: runner.id, labels: desired)
+        end
+        true
+      end
+
+      # The advertised labels, by precedence: --labels (explicit set),
+      # --ai-flow (the full vocabulary), else the derived repo label — the
+      # enclosing project's slug. Org scope has nothing to derive from, so
+      # bare --org is a usage error, as is bare register outside a project.
       #
       # @param args [Array<String>]
       # @param context [Dev::ExecutionContext]
-      sig { params(args: T::Array[String], context: ExecutionContext).void }
-      def status(args, context)
-        cfg = context.project!.runner
-        raise ArgumentError, "no `runner:` block in dev.yml" if cfg.nil?
+      # @param org [Boolean]
+      # @return [String] comma-separated labels (config.sh shape)
+      sig { params(args: T::Array[String], context: ExecutionContext, org: T::Boolean).returns(String) }
+      def resolve_labels(args, context, org)
+        explicit = @flag_parser.value(args, "--labels")
+        ai_flow = args.include?("--ai-flow")
+        if explicit && ai_flow
+          raise ArgumentError,
+            "--ai-flow enrolls the full ai-flow set (#{LabelContracts::AI_FLOW_LABELS.join(",")}); " \
+              "pass --labels alone for a custom set"
+        end
+        return explicit if explicit
+        return LabelContracts::AI_FLOW_LABELS.join(",") if ai_flow
 
-        cfg = config_with_flag_overrides(cfg, args)
-        @runner_status_factory.call(cfg, !context.project!.build_container.nil?).report
+        if org
+          raise ArgumentError,
+            "an org runner's role is not derivable — pass --ai-flow (the agent host) or --labels"
+        end
+
+        project = context.project
+        if project.nil?
+          raise ArgumentError,
+            "the repo label derives from the enclosing project — run inside a checkout or pass --labels"
+        end
+        ProjectManifest.slug(project.name)
       end
 
-      # A copy of the dev.yml runner block with any `--labels` / `--dir` /
-      # `--name` CLI overrides applied. The block describes the repo's
-      # default runner host; overrides let a different host (e.g. the shared
-      # Mac registering org-wide) reuse the same command without editing
-      # dev.yml.
+      # Inspect-only: this machine's discovered enrollments and their
+      # contract facts (see Dev::RunnerStatus).
       #
-      # @param cfg [Dev::RunnerSetupConfig]
       # @param args [Array<String>]
-      # @return [Dev::RunnerSetupConfig]
-      sig { params(cfg: RunnerSetupConfig, args: T::Array[String]).returns(RunnerSetupConfig) }
-      def config_with_flag_overrides(cfg, args)
-        RunnerSetupConfig.new(
-          labels: @flag_parser.value(args, "--labels") || cfg.labels,
-          dir: @flag_parser.value(args, "--dir") || cfg.dir,
-          name: @flag_parser.value(args, "--name") || cfg.name,
-          version: cfg.version,
-        )
+      # @param context [Dev::ExecutionContext]
+      sig { params(args: T::Array[String], context: ExecutionContext).void }
+      def status(args, context)
+        _ = args
+        @runner_status_factory.call(!context.project&.build_container.nil?).report
       end
     end
   end
diff --git a/src/dev/execution_context.rb b/src/dev/execution_context.rb
index 97c35f4..bd1ab2f 100644
--- a/src/dev/execution_context.rb
+++ b/src/dev/execution_context.rb
@@ -4,7 +4,6 @@
 require "pathname"
 require_relative "build_container_config"
 require_relative "cli/ui"
-require_relative "runner_setup_config"
 
 module Dev
   # The project half of an execution context: everything resolved from the
@@ -13,11 +12,13 @@ module Dev
   # builtins, yaml commands) or handle its absence as their own business
   # logic (hybrids like `up`).
   class ProjectContext < T::Struct
+    # The manifest-declared project name — the package identity (see
+    # ProjectManifest#slug for its normalized form).
+    const :name, String
     const :root, Pathname
     const :ruby_version, String
     const :python_version, T.nilable(String), default: nil
     const :build_container, T.nilable(Dev::BuildContainerConfig), default: nil
-    const :runner, T.nilable(Dev::RunnerSetupConfig), default: nil
   end
 
   # Context passed to a command execution: the host half (always present)
diff --git a/src/dev/project_manifest.rb b/src/dev/project_manifest.rb
index 67a16a1..bf62a94 100644
--- a/src/dev/project_manifest.rb
+++ b/src/dev/project_manifest.rb
@@ -3,26 +3,51 @@
 
 require_relative "build_container_config"
 require_relative "command"
-require_relative "runner_setup_config"
 
 module Dev
   # The whole project declaration, coerced once at the boundary: the dev.yml
-  # side (name, commands, build container, runner identity) and the
-  # dependencies.rb side (declared ruby/python toolchain versions).
-  # Immutable — ProjectManifestLoader is the only writer, and it loads each
-  # source file exactly once.
+  # side (name, commands, build container) and the dependencies.rb side
+  # (declared ruby/python toolchain versions). Immutable —
+  # ProjectManifestLoader is the only writer, and it loads each source file
+  # exactly once.
   class ProjectManifest < T::Struct
     extend T::Sig
 
     const :name, String
     const :commands, T::Hash[String, ProjectCommand]
     const :build_container, T.nilable(Dev::BuildContainerConfig), default: nil
-    const :runner, T.nilable(Dev::RunnerSetupConfig), default: nil
 
     # The `ruby` / `python` directives from dependencies.rb, nil until the
     # loader's toolchain pass runs (or when nothing is declared — resolution
     # then falls back, e.g. to Homebrew Ruby).
     const :declared_ruby_version, T.nilable(String), default: nil
     const :declared_python_version, T.nilable(String), default: nil
+
+    # The canonical machine-readable project id: the manifest name,
+    # normalized. `name` is the project's package identity (the ecosystem
+    # norm — gemspec/package.json/Cargo `name`; the org is the registry
+    # giving it uniqueness), and the slug is its label/dir-safe form —
+    # "Cellbound3D" → "cellbound3d". `dev runner register` derives the
+    # repo runner label from it.
+    #
+    # @return [String]
+    sig { returns(String) }
+    def slug
+      self.class.slug(name)
+    end
+
+    class << self
+      extend T::Sig
+
+      # #slug's derivation, callable on a bare name (e.g. from a
+      # ProjectContext, which carries the name but not the manifest).
+      #
+      # @param name [String]
+      # @return [String]
+      sig { params(name: String).returns(String) }
+      def slug(name)
+        name.downcase.gsub(/[^a-z0-9]/, "")
+      end
+    end
   end
 end
diff --git a/src/dev/project_manifest_loader.rb b/src/dev/project_manifest_loader.rb
index 93f4afd..39517fa 100644
--- a/src/dev/project_manifest_loader.rb
+++ b/src/dev/project_manifest_loader.rb
@@ -7,7 +7,6 @@
 require_relative "build_container_config"
 require_relative "command_parser"
 require_relative "project_manifest"
-require_relative "runner_setup_config"
 
 module Dev
   # The boundary coercion for a project's declaration files. Two passes,
@@ -29,10 +28,6 @@ class ProjectManifestLoader
     # clean `dev:` error.
     class UnsupportedDevYamlRubyError < RuntimeError; end
 
-    # Host OS keys a `runner` block may be keyed by (one runner identity per
-    # host OS — e.g. unreal-engine's linux build box vs mac editor builder).
-    RUNNER_HOST_KEYS = T.let(%w[linux darwin].freeze, T::Array[String])
-
     sig { params(command_parser: CommandParser).void }
     def initialize(command_parser: CommandParser.new)
       @command_parser = command_parser
@@ -49,12 +44,12 @@ def initialize(command_parser: CommandParser.new)
     def load(dev_yml_path)
       yaml = YAML.load_file(dev_yml_path)
       reject_removed_ruby_key(yaml)
+      warn_retired_runner_key(yaml)
       raw_commands = yaml["commands"] || {}
       ProjectManifest.new(
         name: T.cast(yaml["name"], String),
         commands: raw_commands.transform_values { |h| @command_parser.parse(h) },
         build_container: parse_build_container(yaml),
-        runner: parse_runner(yaml),
       )
     end
 
@@ -85,7 +80,6 @@ def with_toolchain(manifest, project_root:)
         name: manifest.name,
         commands: manifest.commands,
         build_container: manifest.build_container,
-        runner: manifest.runner,
         declared_ruby_version: presence(deps_config&.ruby_version_requirement),
         declared_python_version: presence(deps_config&.python_version),
       )
@@ -112,43 +106,20 @@ def reject_removed_ruby_key(yaml)
           'Dev::Deps.define { ruby "x.y.z" }'
     end
 
-    # Parse the top-level `runner` block into a RunnerSetupConfig. Returns nil
-    # when absent or labelless (labels are what make a runner registration
-    # meaningful). labels accept a string or a YAML list, normalized to the
-    # comma-separated form config.sh expects.
+    # `runner:` is a retired dev.yml key — enrollment identity is a machine
+    # fact, not a repo declaration: the repo label derives from `name:` and
+    # everything else is flags (`dev runner register`). A warning, not an
+    # error: the block simply means nothing now, and existing enrollments
+    # keep working untouched.
     #
-    # Two shapes: a flat block (one identity for any host), or a host-keyed
-    # block (`runner: { linux: {...}, darwin: {...} }`) where `dev runner-setup`
-    # registers the identity matching the current host OS — and doesn't exist
-    # on hosts without one.
-    sig { params(yaml: T::Hash[String, T.untyped]).returns(T.nilable(RunnerSetupConfig)) }
-    def parse_runner(yaml)
-      runner = yaml["runner"]
-      return nil unless runner.is_a?(Hash)
-
-      runner = runner[current_host_key] if host_keyed_runner?(runner)
-      return nil unless runner.is_a?(Hash)
-
-      labels = Array(runner["labels"]).map(&:to_s).reject(&:empty?).join(",")
-      return nil if labels.empty?
-
-      RunnerSetupConfig.new(
-        labels: labels,
-        dir: presence(runner["dir"]),
-        name: presence(runner["name"]),
-        version: presence(runner["version"]),
-      )
-    end
-
-    # A runner block is host-keyed when any top-level key is a host OS name.
-    sig { params(runner: T::Hash[String, T.untyped]).returns(T::Boolean) }
-    def host_keyed_runner?(runner)
-      runner.keys.any? { |key| RUNNER_HOST_KEYS.include?(key.to_s) }
-    end
+    # @param yaml [Hash]
+    # @return [void]
+    sig { params(yaml: T::Hash[String, T.untyped]).void }
+    def warn_retired_runner_key(yaml)
+      return unless yaml.key?("runner")
 
-    sig { returns(String) }
-    def current_host_key
-      RUBY_PLATFORM.include?("darwin") ? "darwin" : "linux"
+      $stderr.puts "dev: dev.yml `runner:` is retired and ignored — the repo runner label now derives " \
+                   "from `name:` (`dev runner register`); delete the block."
     end
 
     # Coerce a scalar to a non-empty String, or nil.
diff --git a/src/dev/runner.rb b/src/dev/runner.rb
index dd34b79..f645787 100644
--- a/src/dev/runner.rb
+++ b/src/dev/runner.rb
@@ -108,11 +108,11 @@ def build_context(manifest)
       ExecutionContext.new(
         ui: @ui,
         project: ProjectContext.new(
+          name: manifest.name,
           root: Dev.target_project_root,
           ruby_version: ShadowenvRuby.resolve_ruby_version(manifest.declared_ruby_version),
           python_version: manifest.declared_python_version,
           build_container: manifest.build_container,
-          runner: manifest.runner,
         ),
       )
     end
@@ -164,8 +164,7 @@ def exit_for(error)
     # The composition root: the one place the repository (consumed only by
     # CommandService, the onion rule) and the builtin set are constructed.
     # Which builtins exist is config-gated here — project builtins only with
-    # a manifest, runner (+ its runner-setup alias) only with a `runner:` block,
-    # provide-image/reset-container only with a build container.
+    # a manifest, provide-image/reset-container only with a build container.
     #
     # @param manifest [ProjectManifest, nil]
     # @param context [ExecutionContext]
@@ -199,9 +198,10 @@ def build_command_service(manifest, context)
       service
     end
 
-    # The projectless catalog: `up` is the one command that exists without a
-    # project (its host half is the fresh-box bootstrap — install dev, `dev
-    # up`, ready). The truly global commands (cd, clone, cred, ...) are
+    # The projectless catalog: `up` (its host half is the fresh-box
+    # bootstrap — install dev, `dev up`, ready) and `runner` (enrollment is
+    # a machine concern; `--org` registration and `status` need no
+    # project). The truly global commands (cd, clone, cred, ...) are
     # dispatched before the Runner; everything else requires the project, so
     # it simply isn't registered — a lookup miss maps to the no-dev.yml
     # refusal in exit_for.
@@ -209,9 +209,14 @@ def build_command_service(manifest, context)
     # @return [CommandService]
     sig { returns(CommandService) }
     def build_projectless_command_service
+      builtins = T.let(
+        { "up" => Builtins::UpCommand.new(install_deps_command: Builtins::InstallDepsCommand.new) },
+        T::Hash[String, BuiltinCommand],
+      )
+      builtins.merge!(runner_builtins)
       CommandService.new(
         repository: CommandRepository.new(
-          builtins: { "up" => Builtins::UpCommand.new(install_deps_command: Builtins::InstallDepsCommand.new) },
+          builtins: builtins,
           project_commands: {},
         ),
         executor: CommandExecutor.new(builtin_executor: BuiltinExecutor.new),
@@ -274,12 +279,23 @@ def build_builtins(manifest, dependency_service, help:)
       }, T::Hash[String, BuiltinCommand])
       builtins["provide-image"] = Builtins::ProvideImageCommand.new if manifest.build_container
       builtins["reset-container"] = Builtins::ResetContainerCommand.new if manifest.build_container&.persist
-      if manifest.runner
-        builtins["runner"] = Builtins::RunnerCommand.new
-        # The pre-register name survives as an alias for `runner register`.
-        builtins["runner-setup"] = Builtins::RunnerCommand.new(implied_subcommand: "register")
-      end
+      builtins.merge!(runner_builtins)
       builtins
     end
+
+    # `runner` is ungated: enrollment is a machine concern (register derives
+    # the repo label from the enclosing project; --org needs no project at
+    # all), so the command exists everywhere — including the projectless
+    # catalog.
+    #
+    # @return [Hash{String => BuiltinCommand}]
+    sig { returns(T::Hash[String, BuiltinCommand]) }
+    def runner_builtins
+      {
+        "runner" => Builtins::RunnerCommand.new,
+        # The pre-register name survives as an alias for `runner register`.
+        "runner-setup" => Builtins::RunnerCommand.new(implied_subcommand: "register"),
+      }
+    end
   end
 end
diff --git a/src/dev/runner_setup_config.rb b/src/dev/runner_setup_config.rb
index 450f5f6..9d1ec95 100644
--- a/src/dev/runner_setup_config.rb
+++ b/src/dev/runner_setup_config.rb
@@ -2,23 +2,12 @@
 # frozen_string_literal: true
 
 module Dev
-  # Value object for the `runner` block in dev.yml.
-  #
-  # When present, `dev runner register` registers the current host as the repo's
-  # self-hosted GitHub Actions runner with these labels. dev owns the install
-  # logic (Dev::RunnerSetup), so every repo declares only its runner identity
-  # here instead of vendoring a bespoke setup script.
-  #
-  # dev.yml example:
-  #   runner:
-  #     labels: ue-engine
-  #     dir: "~/actions-runner-ue"   # optional; defaults to ~/actions-runner-<label>
-  #     name: my-box                 # optional; defaults to the hostname
-  #     version: "2.335.1"           # optional; defaults to RunnerSetup::DEFAULT_VERSION
-  #
-  # labels may be a single string ("ue-engine") or a YAML list ([ue-engine, x64]);
-  # both normalize to the comma-separated form `config.sh --labels` expects. dir,
-  # name, and version are optional overrides (see Dev::RunnerSetup for defaults).
+  # Value object for one enrollment's identity, resolved by `dev runner
+  # register` from its flags and derivations (never a file — the dev.yml
+  # `runner:` block is retired): the comma-separated labels config.sh
+  # expects, plus optional dir/name/version overrides (see Dev::RunnerSetup
+  # for their defaults: ~/actions-runner-<first label>, the hostname, and
+  # the pinned runner version).
   class RunnerSetupConfig
     extend T::Sig
 
diff --git a/test/dev/builtin_executor_test.rb b/test/dev/builtin_executor_test.rb
index 41f3474..0d10142 100644
--- a/test/dev/builtin_executor_test.rb
+++ b/test/dev/builtin_executor_test.rb
@@ -33,7 +33,7 @@ def build_context
     ui = typed_mock(Dev::Cli::Ui)
     Dev::ExecutionContext.new(
       ui: ui,
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/builtin-executor"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/builtin-executor"), ruby_version: "4.0.1"),
     )
   end
 
diff --git a/test/dev/builtins/cache_command_test.rb b/test/dev/builtins/cache_command_test.rb
index 6d93586..a8160c9 100644
--- a/test/dev/builtins/cache_command_test.rb
+++ b/test/dev/builtins/cache_command_test.rb
@@ -110,6 +110,7 @@ def build_context(build_container: nil)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
       project: Dev::ProjectContext.new(
+        name: "TestProject",
         root: Pathname.new("/tmp/cache-test"),
         ruby_version: "4.0.1",
         build_container: build_container,
diff --git a/test/dev/builtins/cd_command_test.rb b/test/dev/builtins/cd_command_test.rb
index f2c445f..f79943f 100644
--- a/test/dev/builtins/cd_command_test.rb
+++ b/test/dev/builtins/cd_command_test.rb
@@ -27,7 +27,7 @@ class Dev::Builtins::CdCommandTest < Minitest::Test
   def build_context
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/cd-test"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/cd-test"), ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/check_command_test.rb b/test/dev/builtins/check_command_test.rb
index 1b71c44..4511080 100644
--- a/test/dev/builtins/check_command_test.rb
+++ b/test/dev/builtins/check_command_test.rb
@@ -62,7 +62,7 @@ class Dev::Builtins::CheckCommandTest < Minitest::Test
   def build_context
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/check-test"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/check-test"), ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/clone_command_test.rb b/test/dev/builtins/clone_command_test.rb
index 8b6aff0..b09931c 100644
--- a/test/dev/builtins/clone_command_test.rb
+++ b/test/dev/builtins/clone_command_test.rb
@@ -27,7 +27,7 @@ class Dev::Builtins::CloneCommandTest < Minitest::Test
   def build_context
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/clone-test"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/clone-test"), ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/config_command_test.rb b/test/dev/builtins/config_command_test.rb
index 480483a..ee480c3 100644
--- a/test/dev/builtins/config_command_test.rb
+++ b/test/dev/builtins/config_command_test.rb
@@ -27,7 +27,7 @@ class Dev::Builtins::ConfigCommandTest < Minitest::Test
   def build_context
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/config-test"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/config-test"), ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/cred_command_test.rb b/test/dev/builtins/cred_command_test.rb
index cc7f86e..41c8b45 100644
--- a/test/dev/builtins/cred_command_test.rb
+++ b/test/dev/builtins/cred_command_test.rb
@@ -27,7 +27,7 @@ class Dev::Builtins::CredCommandTest < Minitest::Test
   def build_context
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/cred-test"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/cred-test"), ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/deps_command_test.rb b/test/dev/builtins/deps_command_test.rb
index db27cc2..eb39c75 100644
--- a/test/dev/builtins/deps_command_test.rb
+++ b/test/dev/builtins/deps_command_test.rb
@@ -60,7 +60,7 @@ class Dev::Builtins::DepsCommandTest < Minitest::Test
   def build_context(project_root)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: project_root, ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: project_root, ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/help_command_test.rb b/test/dev/builtins/help_command_test.rb
index 3ab328e..16307a2 100644
--- a/test/dev/builtins/help_command_test.rb
+++ b/test/dev/builtins/help_command_test.rb
@@ -66,7 +66,7 @@ def build_help(project_name: "testproject", usage_printer: typed_mock(Dev::Cli::
   def build_context
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/help-test"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/help-test"), ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/install_deps_command_test.rb b/test/dev/builtins/install_deps_command_test.rb
index dea4e05..557ffdd 100644
--- a/test/dev/builtins/install_deps_command_test.rb
+++ b/test/dev/builtins/install_deps_command_test.rb
@@ -126,7 +126,7 @@ def quiet_host_service
   def build_context(project_root)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: project_root, ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: project_root, ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/learnings_command_test.rb b/test/dev/builtins/learnings_command_test.rb
index eb530bc..dfbad7e 100644
--- a/test/dev/builtins/learnings_command_test.rb
+++ b/test/dev/builtins/learnings_command_test.rb
@@ -43,7 +43,7 @@ class Dev::Builtins::LearningsCommandTest < Minitest::Test
   def build_context(project_root)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: project_root, ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: project_root, ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/plan_command_test.rb b/test/dev/builtins/plan_command_test.rb
index b2d7db5..7a11521 100644
--- a/test/dev/builtins/plan_command_test.rb
+++ b/test/dev/builtins/plan_command_test.rb
@@ -43,7 +43,7 @@ class Dev::Builtins::PlanCommandTest < Minitest::Test
   def build_context(project_root)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: project_root, ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: project_root, ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/builtins/provide_image_command_test.rb b/test/dev/builtins/provide_image_command_test.rb
index cbfb923..9334e60 100644
--- a/test/dev/builtins/provide_image_command_test.rb
+++ b/test/dev/builtins/provide_image_command_test.rb
@@ -82,6 +82,7 @@ def build_context(build_container)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
       project: Dev::ProjectContext.new(
+        name: "TestProject",
         root: Pathname.new("/tmp/provide-image-test"),
         ruby_version: "4.0.1",
         build_container: build_container,
diff --git a/test/dev/builtins/reset_container_command_test.rb b/test/dev/builtins/reset_container_command_test.rb
index a8f204b..df5cd61 100644
--- a/test/dev/builtins/reset_container_command_test.rb
+++ b/test/dev/builtins/reset_container_command_test.rb
@@ -60,6 +60,7 @@ def build_context(build_container)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
       project: Dev::ProjectContext.new(
+        name: "TestProject",
         root: Pathname.new("/tmp/reset-container-test"),
         ruby_version: "4.0.1",
         build_container: build_container,
diff --git a/test/dev/builtins/runner_command_test.rb b/test/dev/builtins/runner_command_test.rb
index b2dc168..a30e081 100644
--- a/test/dev/builtins/runner_command_test.rb
+++ b/test/dev/builtins/runner_command_test.rb
@@ -3,8 +3,15 @@
 
 require "test_helper"
 require "dev/builtins/runner_command"
+require "dev/label_contracts"
+require "dev/runner_discovery"
+require "dev/runner_registry"
 require "dev/runner_setup_config"
+require "fileutils"
+require "json"
 require "pathname"
+require "stringio"
+require "tmpdir"
 
 # Records the contract lifecycle a register run drives.
 class RecordedContract
@@ -23,227 +30,361 @@ def after_enroll!(runner_dir:)
   end
 end unless defined?(RecordedContract)
 
+# The GitHub-side registry seam: answers find from a canned map and
+# records amends.
+class FakeRegistry
+  attr_reader :amends
+
+  def initialize(runners: {})
+    @runners = runners
+    @amends = []
+  end
+
+  def find(scope:, name:)
+    @runners[[scope, name]]
+  end
+
+  def amend!(scope:, runner_id:, labels:)
+    @amends << [scope, runner_id, labels]
+  end
+end unless defined?(FakeRegistry)
+
 transform!(RSpock::AST::Transformation)
 class Dev::Builtins::RunnerCommandTest < Minitest::Test
   include SorbetHelper
 
-  test "register enrolls with the dev.yml runner block, repo-scoped by default" do
-    Given "a runner command over a recording factory"
-    wirings, _events, command = build_recording_command
-    context = build_context(runner_config)
+  # --- label + scope resolution ---------------------------------------
+
+  test "bare register derives the repo label from the project name" do
+    Given "a checkout of a project named Cellbound3D"
+    harness = build_harness
+    context = build_context(name: "Cellbound3D")
 
     When "running register with no flags"
-    command.call(args: ["register"], context: context)
+    harness.command.call(args: ["register"], context: context)
 
-    Then "the block passes through untouched; repo resolution stays with gh"
-    config, repo, org = wirings.fetch(0)
-    config == runner_config
+    Then "the label is the project slug, repo-scoped, dir/name defaulted"
+    config, repo, org = harness.wirings.fetch(0)
+    config == Dev::RunnerSetupConfig.new(labels: "cellbound3d")
     repo.nil?
     org == false
   end
 
-  test "register applies --labels/--dir/--name overrides onto the block" do
-    Given "a runner command over a recording factory"
-    wirings, _events, command = build_recording_command
-    context = build_context(runner_config)
+  test "--org --ai-flow enrolls the full ai-flow label vocabulary" do
+    Given "a harness"
+    harness = build_harness
 
-    When "running with identity overrides"
-    command.call(
-      args: ["register", "--labels", "macos,ue-editor", "--dir", "~/actions-runner-mac", "--name", "mac-box"],
-      context: context,
-    )
+    When "registering the org agent host"
+    harness.command.call(args: ["register", "--org", "--ai-flow"], context: projectless_context)
 
-    Then "the overrides replace the block's identity, version rides along"
-    config, = wirings.fetch(0)
-    config == Dev::RunnerSetupConfig.new(
-      labels: "macos,ue-editor", dir: "~/actions-runner-mac", name: "mac-box", version: "2.335.1",
-    )
+    Then "the labels are dev's documented mirror of ai-flow's vocabulary"
+    config, _repo, org = harness.wirings.fetch(0)
+    config.labels == Dev::LabelContracts::AI_FLOW_LABELS.join(",")
+    org == true
+  end
+
+  test "--labels overrides any derivation" do
+    Given "a checkout whose derived label would differ"
+    harness = build_harness
+    context = build_context(name: "UnrealEngine")
+
+    When "registering with an explicit custom set"
+    harness.command.call(args: ["register", "--labels", "macos,ue-editor"], context: context)
+
+    Then
+    harness.wirings.fetch(0).fetch(0).labels == "macos,ue-editor"
+  end
+
+  test "--ai-flow with --labels is a contradiction and raises" do
+    Given "a harness"
+    harness = build_harness
+
+    When "passing both"
+    harness.command.call(args: ["register", "--org", "--ai-flow", "--labels", "ai-ask"], context: projectless_context)
+
+    Then
+    raises ArgumentError
+  end
+
+  test "--org without a role raises: an org runner's labels are not derivable" do
+    Given "a harness"
+    harness = build_harness
+
+    When "registering org-scoped with no label source"
+    harness.command.call(args: ["register", "--org"], context: build_context(name: "Cellbound3D"))
+
+    Then
+    raises ArgumentError
   end
 
-  test "register passes --repo and --org through to the setup" do
-    Given "a runner command over a recording factory"
-    wirings, _events, command = build_recording_command
-    context = build_context(runner_config)
+  test "bare register outside a project raises: nothing to derive from" do
+    Given "a harness"
+    harness = build_harness
+
+    When "registering with no checkout and no labels"
+    harness.command.call(args: ["register"], context: projectless_context)
 
-    When "running org-wide for an explicit repo"
-    command.call(args: ["register", "--repo", "d3mlabs/dev", "--org"], context: context)
+    Then
+    raises ArgumentError
+  end
 
-    Then "the scope flags reach the setup"
-    _, repo, org = wirings.fetch(0)
-    repo == "d3mlabs/dev"
+  test "register applies --dir/--name/--repo/--org flags" do
+    Given "a harness"
+    harness = build_harness
+
+    When "running with identity overrides"
+    harness.command.call(
+      args: ["register", "--labels", "ue-engine", "--dir", "~/actions-runner-ue",
+             "--name", "gaming-box", "--repo", "d3mlabs/unreal-engine", "--org"],
+      context: projectless_context,
+    )
+
+    Then
+    config, repo, org = harness.wirings.fetch(0)
+    config == Dev::RunnerSetupConfig.new(labels: "ue-engine", dir: "~/actions-runner-ue", name: "gaming-box")
+    repo == "d3mlabs/unreal-engine"
     org == true
   end
 
-  test "register converges contracts before the ceremony and finishes the post-enrollment steps after it" do
-    Given "an agent-labeled block over a recording contract"
-    _wirings, events, command = build_recording_command(contracts: 1)
-    context = build_context(runner_config)
+  # --- the idempotent converge ----------------------------------------
+
+  test "a fresh scope runs the full enrollment: converge -> enroll -> after_enroll" do
+    Given "no local enrollment serves the scope"
+    harness = build_harness(contracts: 1)
+    context = build_context(name: "Cellbound3D")
 
     When "registering"
-    command.call(args: ["register"], context: context)
+    harness.command.call(args: ["register"], context: context)
 
-    Then "converge -> enroll -> after_enroll, with the enrolled dir"
-    events == [
+    Then "the ceremony runs end to end with the enrolled dir"
+    harness.events == [
       [:converge, false, nil, nil],
       [:run],
       [:after_enroll, "/tmp/runner-dir"],
     ]
   end
 
+  test "an enrolled scope with drifted labels is amended in place, never re-enrolled" do
+    Given "this host already serves the org, with a stale label set, in a repo-named dir"
+    home = Dir.mktmpdir
+    dir = write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs", name: "mac-box")
+    registry = FakeRegistry.new(
+      runners: { ["d3mlabs", "mac-box"] => Dev::RunnerRegistry::Runner.new(id: 42, custom_labels: ["cellbound3d"]) },
+    )
+    harness = build_harness(contracts: 1, home: home, registry: registry, scope: "d3mlabs")
+
+    When "registering the agent host"
+    harness.command.call(args: ["register", "--org", "--ai-flow"], context: projectless_context)
+
+    Then "one label amend; the service and dir stay put; contracts still converge"
+    registry.amends == [["d3mlabs", 42, Dev::LabelContracts::AI_FLOW_LABELS]]
+    harness.events == [
+      [:converge, false, nil, nil],
+      [:after_enroll, dir],
+    ]
+  end
+
+  test "an enrolled scope with current labels is a no-op amend" do
+    Given "the enrollment already advertises the desired set"
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs/cellbound-3d", name: "box")
+    registry = FakeRegistry.new(
+      runners: { ["d3mlabs/cellbound-3d", "box"] => Dev::RunnerRegistry::Runner.new(id: 7, custom_labels: ["cellbound3d"]) },
+    )
+    harness = build_harness(home: home, registry: registry, scope: "d3mlabs/cellbound-3d")
+
+    When "re-running register"
+    harness.command.call(args: ["register"], context: build_context(name: "Cellbound3D"))
+
+    Then "nothing is amended and nothing re-enrolls"
+    registry.amends == []
+    harness.events == []
+    harness.out.string.include?("nothing to amend")
+  end
+
+  test "a local enrollment GitHub has lost re-enrolls into the same dir" do
+    Given "a .runner record whose runner is gone server-side"
+    home = Dir.mktmpdir
+    dir = write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs", name: "mac-box")
+    harness = build_harness(home: home, registry: FakeRegistry.new, scope: "d3mlabs")
+
+    When "registering"
+    harness.command.call(args: ["register", "--org", "--labels", "ai-build"], context: projectless_context)
+
+    Then "the re-enrollment reuses the discovered dir, not a label-derived one"
+    harness.events == [[:run]]
+    harness.wirings.fetch(1).fetch(0).dir == dir
+  end
+
+  test "--dir skips discovery: the dir is the operator's to pick" do
+    Given "an enrollment discovery would have found"
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs", name: "mac-box")
+    registry = FakeRegistry.new(
+      runners: { ["d3mlabs", "mac-box"] => Dev::RunnerRegistry::Runner.new(id: 42, custom_labels: ["x"]) },
+    )
+    harness = build_harness(home: home, registry: registry, scope: "d3mlabs")
+
+    When "registering with an explicit dir"
+    harness.command.call(
+      args: ["register", "--org", "--labels", "ai-build", "--dir", "~/actions-runner-heavy"],
+      context: projectless_context,
+    )
+
+    Then "the full enrollment runs there; no amend"
+    harness.events == [[:run]]
+    registry.amends == []
+  end
+
+  # --- contracts --------------------------------------------------------
+
   test "register hands the contract the container fact and sizing hint" do
     Given "a container repo with a resources block"
-    _wirings, events, command = build_recording_command(contracts: 1)
+    harness = build_harness(contracts: 1)
     container = Dev::BuildContainerConfig.new(
       image: "img", registry: "reg",
       resources: Dev::BuildContainerConfig::Resources.new(cpus: 8, memory_gib: 24),
     )
-    context = build_context(runner_config, build_container: container)
+    context = build_context(name: "Cellbound3D", build_container: container)
 
     When "registering"
-    command.call(args: ["register"], context: context)
+    harness.command.call(args: ["register"], context: context)
+
+    Then
+    harness.events.fetch(0) == [:converge, true, 8, 24]
+  end
+
+  test "the --agent-user flag reaches the contracts factory" do
+    Given "a factory recording its agent_user argument"
+    seen = []
+    recorder = ->(labels, agent_user) {
+      seen << [labels, agent_user]
+      []
+    }
+    harness = build_harness(contracts_factory: recorder)
+
+    When "registering with the override"
+    harness.command.call(
+      args: ["register", "--org", "--ai-flow", "--agent-user", "ci"],
+      context: projectless_context,
+    )
 
     Then
-    events.fetch(0) == [:converge, true, 8, 24]
+    seen == [[Dev::LabelContracts::AI_FLOW_LABELS.join(","), "ci"]]
   end
 
+  # --- plumbing ---------------------------------------------------------
+
   test "the runner-setup alias implies register" do
     Given "the alias wiring (implied subcommand)"
-    wirings, _events, command = build_recording_command(implied_subcommand: "register")
-    context = build_context(runner_config)
+    harness = build_harness(implied_subcommand: "register")
 
     When "running with bare flags, no subcommand"
-    command.call(args: ["--org"], context: context)
+    harness.command.call(args: ["--org", "--ai-flow"], context: projectless_context)
 
     Then
-    wirings.fetch(0).fetch(2) == true
+    harness.wirings.fetch(0).fetch(2) == true
   end
 
-  test "status inspects with the resolved config and the container fact" do
+  test "status wires the inspector with the container fact" do
     Given "a status factory recording its wiring"
     seen = []
     status = typed_mock(Dev::RunnerStatus)
     status.expects(:report).once
     command = Dev::Builtins::RunnerCommand.new(
-      runner_status_factory: ->(config, container_required) {
-        seen << [config, container_required]
+      runner_status_factory: ->(container_required) {
+        seen << container_required
         status
       },
     )
     container = Dev::BuildContainerConfig.new(image: "img", registry: "reg")
 
-    When "running status"
-    command.call(args: ["status"], context: build_context(runner_config, build_container: container))
+    When "running status inside a container repo and outside any project"
+    command.call(args: ["status"], context: build_context(name: "Cellbound3D", build_container: container))
 
-    Then "the block and the container fact reach the inspector"
-    seen == [[runner_config, true]]
+    Then "the container fact reaches the inspector"
+    seen == [true]
   end
 
-  test "the default factories build the real collaborators" do
-    Given "a command with its default wiring"
-    # RunnerSetup#run registers the host and RunnerStatus#report inspects it,
-    # so the test intercepts both construction boundaries and asserts the
-    # default factories' wiring (the bare ue-engine label makes the default
-    # contracts factory resolve to no contracts).
-    setup = typed_mock(Dev::RunnerSetup)
-    setup.expects(:run).once
-    setup.stubs(:resolve_dir).returns("/tmp/runner-dir")
-    Dev::RunnerSetup.expects(:new).with(config: runner_config, repo: nil, org: false).returns(setup)
+  test "status works projectless (the machine view needs no checkout)" do
+    Given "a status factory"
     status = typed_mock(Dev::RunnerStatus)
     status.expects(:report).once
-    Dev::RunnerStatus.expects(:new)
-      .with(config: runner_config, container_required: false).returns(status)
-    command = Dev::Builtins::RunnerCommand.new
+    command = Dev::Builtins::RunnerCommand.new(runner_status_factory: ->(_container) { status })
 
-    When "running register, then status"
-    command.call(args: ["register"], context: build_context(runner_config))
-    command.call(args: ["status"], context: build_context(runner_config))
+    When "running status with no project"
+    command.call(args: ["status"], context: projectless_context)
 
-    Then "the expectations on both construction boundaries hold"
+    Then
     true
   end
 
   test "an unknown subcommand raises the usage error" do
-    Given "a runner command"
-    _wirings, _events, command = build_recording_command
-    context = build_context(runner_config)
+    Given "a harness"
+    harness = build_harness
 
     When "running an unknown subcommand"
-    command.call(args: ["bogus"], context: context)
+    harness.command.call(args: ["bogus"], context: projectless_context)
 
     Then
     raises ArgumentError
   end
 
-  test "register without a runner block raises the usage error" do
-    Given "a context whose dev.yml has no runner block"
-    _wirings, _events, command = build_recording_command
-    context = build_context(nil)
-
-    When "registering"
-    command.call(args: ["register"], context: context)
-
-    Then
-    raises ArgumentError
-  end
-
-  test "the --agent-user flag reaches the contracts factory" do
-    Given "a factory recording its agent_user argument"
-    seen = []
-    setup = typed_mock(Dev::RunnerSetup)
-    setup.stubs(:run)
-    setup.stubs(:resolve_dir).returns("/tmp/runner-dir")
-    command = Dev::Builtins::RunnerCommand.new(
-      runner_setup_factory: ->(_c, _r, _o) { setup },
-      contracts_factory: ->(labels, agent_user) {
-        seen << [labels, agent_user]
-        []
-      },
-    )
-
-    When "registering with the override"
-    command.call(args: ["register", "--agent-user", "ci"], context: build_context(runner_config))
-
-    Then
-    seen == [["ue-engine", "ci"]]
-  end
-
   private
 
-  def runner_config
-    Dev::RunnerSetupConfig.new(labels: "ue-engine", dir: "~/actions-runner-ue", name: "gaming-box", version: "2.335.1")
-  end
+  Harness = Struct.new(:command, :wirings, :events, :out, keyword_init: true)
 
-  # A command whose setup factory records each (config, repo, org) wiring
-  # and whose contracts record their lifecycle into a shared event log the
-  # no-op setup also appends to.
-  def build_recording_command(contracts: 0, implied_subcommand: nil)
+  # A command over recording seams: the setup factory records each
+  # (config, repo, org) wiring and answers with a no-op setup; contracts
+  # record their lifecycle; discovery reads a real (tmp) home; the registry
+  # is the injected fake.
+  def build_harness(contracts: 0, home: Dir.mktmpdir, registry: FakeRegistry.new,
+                    scope: "d3mlabs/cellbound-3d", implied_subcommand: nil, contracts_factory: nil)
     wirings = []
     events = []
+    out = StringIO.new
     setup = typed_mock(Dev::RunnerSetup)
     setup.stubs(:run).with { events << [:run] || true }
     setup.stubs(:resolve_dir).returns("/tmp/runner-dir")
+    setup.stubs(:resolve_scope).returns(scope)
     command = Dev::Builtins::RunnerCommand.new(
       runner_setup_factory: ->(config, repo, org) {
         wirings << [config, repo, org]
         setup
       },
-      contracts_factory: ->(_labels, _agent_user) {
+      contracts_factory: contracts_factory || ->(_labels, _agent_user) {
         Array.new(contracts) { RecordedContract.new(events) }
       },
+      discovery: Dev::RunnerDiscovery.new(home: home),
+      registry: registry,
+      out: out,
       implied_subcommand: implied_subcommand,
     )
-    [wirings, events, command]
+    Harness.new(command: command, wirings: wirings, events: events, out: out)
+  end
+
+  # A .runner record the way config.sh writes it (UTF-8 BOM + JSON).
+  def write_runner(home, dir_name, scope:, name:)
+    dir = File.join(home, dir_name)
+    FileUtils.mkdir_p(dir)
+    record = { "agentName" => name, "gitHubUrl" => "https://github.com/#{scope}" }
+    File.write(File.join(dir, ".runner"), "\uFEFF#{JSON.generate(record)}")
+    dir
   end
 
-  def build_context(runner, build_container: nil)
+  def build_context(name:, build_container: nil)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
       project: Dev::ProjectContext.new(
+        name: name,
         root: Pathname.new("/tmp/runner-test"),
         ruby_version: "4.0.1",
-        runner: runner,
         build_container: build_container,
       ),
     )
   end
+
+  def projectless_context
+    Dev::ExecutionContext.new(ui: typed_mock(Dev::Cli::Ui))
+  end
 end
diff --git a/test/dev/builtins/up_command_test.rb b/test/dev/builtins/up_command_test.rb
index f5e695e..2c17ca0 100644
--- a/test/dev/builtins/up_command_test.rb
+++ b/test/dev/builtins/up_command_test.rb
@@ -144,6 +144,7 @@ def build_context(build_container: nil)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
       project: Dev::ProjectContext.new(
+        name: "TestProject",
         root: Pathname.new("/tmp/up-test"),
         ruby_version: "4.0.1",
         build_container: build_container,
diff --git a/test/dev/builtins/update_deps_command_test.rb b/test/dev/builtins/update_deps_command_test.rb
index dcdd129..9fcc4a7 100644
--- a/test/dev/builtins/update_deps_command_test.rb
+++ b/test/dev/builtins/update_deps_command_test.rb
@@ -92,7 +92,7 @@ class Dev::Builtins::UpdateDepsCommandTest < Minitest::Test
   def build_context(project_root)
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: project_root, ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: project_root, ruby_version: "4.0.1"),
     )
   end
 end
diff --git a/test/dev/command_executor_test.rb b/test/dev/command_executor_test.rb
index 561399a..d1add8a 100644
--- a/test/dev/command_executor_test.rb
+++ b/test/dev/command_executor_test.rb
@@ -25,7 +25,7 @@ def build_context
     ui = typed_mock(Dev::Cli::Ui)
     Dev::ExecutionContext.new(
       ui: ui,
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/executor-test"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/executor-test"), ruby_version: "4.0.1"),
     )
   end
 
diff --git a/test/dev/command_service_test.rb b/test/dev/command_service_test.rb
index 37ddb8c..57dd860 100644
--- a/test/dev/command_service_test.rb
+++ b/test/dev/command_service_test.rb
@@ -60,7 +60,7 @@ def build_executor
   def fake_context
     Dev::ExecutionContext.new(
       ui: typed_mock(Dev::Cli::Ui),
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/service-test"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/service-test"), ruby_version: "4.0.1"),
     )
   end
 
diff --git a/test/dev/execution_context_test.rb b/test/dev/execution_context_test.rb
index d1882d7..4cfd4f4 100644
--- a/test/dev/execution_context_test.rb
+++ b/test/dev/execution_context_test.rb
@@ -10,7 +10,7 @@ class Dev::ExecutionContextTest < Minitest::Test
 
   test "project! unwraps the project half when one exists" do
     Given "a context with a project half"
-    project = Dev::ProjectContext.new(root: Pathname.new("/tmp/ctx-test"), ruby_version: "4.0.1")
+    project = Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/ctx-test"), ruby_version: "4.0.1")
     context = Dev::ExecutionContext.new(ui: typed_mock(Dev::Cli::Ui), project: project)
 
     Expect "the non-nil project"
diff --git a/test/dev/overridden_executor_test.rb b/test/dev/overridden_executor_test.rb
index a4010fe..3525d66 100644
--- a/test/dev/overridden_executor_test.rb
+++ b/test/dev/overridden_executor_test.rb
@@ -31,7 +31,7 @@ def build_context
     ui = typed_mock(Dev::Cli::Ui)
     Dev::ExecutionContext.new(
       ui: ui,
-      project: Dev::ProjectContext.new(root: Pathname.new("/tmp/overridden-executor"), ruby_version: "4.0.1"),
+      project: Dev::ProjectContext.new(name: "TestProject", root: Pathname.new("/tmp/overridden-executor"), ruby_version: "4.0.1"),
     )
   end
 
diff --git a/test/dev/project_manifest_loader_test.rb b/test/dev/project_manifest_loader_test.rb
index 0d90ef5..f983357 100644
--- a/test/dev/project_manifest_loader_test.rb
+++ b/test/dev/project_manifest_loader_test.rb
@@ -503,129 +503,37 @@ class ProjectManifestLoaderTest < Minitest::Test
     tmp.close!
   end
 
-  test "#load extracts a runner block with string labels" do
-    Given "a dev.yml file with a runner block"
+  test "#load warns and ignores the retired runner block" do
+    Given "a dev.yml still carrying the retired key"
     tmp = write_dev_yml(<<~YAML)
       name: unreal-engine
       runner:
         labels: ue-engine
-        dir: "~/actions-runner-ue"
-        name: gaming-box
-        version: "2.335.1"
-    YAML
-
-    When "the manifest is loaded"
-    manifest = build_loader.load(Pathname.new(tmp.path))
-
-    Then
-    manifest.runner == Dev::RunnerSetupConfig.new(
-      labels: "ue-engine", dir: "~/actions-runner-ue", name: "gaming-box", version: "2.335.1",
-    )
-
-    Cleanup
-    tmp.close!
-  end
-
-  test "#load normalizes a runner labels list to comma-separated" do
-    Given "a dev.yml file with a runner labels list"
-    tmp = write_dev_yml(<<~YAML)
-      name: snappy
-      runner:
-        labels:
-          - snappy
-          - x64
-    YAML
-
-    When "the manifest is loaded"
-    manifest = build_loader.load(Pathname.new(tmp.path))
-
-    Then
-    manifest.runner.labels == "snappy,x64"
-    manifest.runner.dir.nil?
-
-    Cleanup
-    tmp.close!
-  end
-
-  test "#load selects the current host's identity from a host-keyed runner block" do
-    Given "a dev.yml with one runner identity per host OS"
-    tmp = write_dev_yml(<<~YAML)
-      name: unreal-engine
-      runner:
-        linux:
-          labels: ue-engine
-        darwin:
-          labels:
-            - macos
-            - ue-editor
-    YAML
-
-    When "the manifest is loaded"
-    manifest = build_loader.load(Pathname.new(tmp.path))
-
-    Then "the identity matches the OS the test is running on"
-    expected_labels = RUBY_PLATFORM.include?("darwin") ? "macos,ue-editor" : "ue-engine"
-    manifest.runner.labels == expected_labels
-
-    Cleanup
-    tmp.close!
-  end
-
-  test "#load returns nil runner when a host-keyed block has no entry for this host" do
-    Given "a dev.yml keyed only for the other host OS"
-    other_host = RUBY_PLATFORM.include?("darwin") ? "linux" : "darwin"
-    tmp = write_dev_yml(<<~YAML)
-      name: unreal-engine
-      runner:
-        #{other_host}:
-          labels: ue-engine
-    YAML
-
-    When "the manifest is loaded"
-    manifest = build_loader.load(Pathname.new(tmp.path))
-
-    Then "this host has no runner identity"
-    manifest.runner.nil?
-
-    Cleanup
-    tmp.close!
-  end
-
-  test "#load returns nil runner when not declared" do
-    Given "a dev.yml without a runner block"
-    tmp = write_dev_yml(<<~YAML)
-      name: myproject
-      commands:
-        up:
-          run: ./bin/setup.rb
     YAML
+    old_stderr = $stderr
+    $stderr = StringIO.new
 
     When "the manifest is loaded"
     manifest = build_loader.load(Pathname.new(tmp.path))
 
-    Then
-    manifest.runner.nil?
+    Then "the manifest loads without it, with a retirement warning"
+    manifest.name == "unreal-engine"
+    $stderr.string.include?("`runner:` is retired")
 
     Cleanup
+    $stderr = old_stderr
     tmp.close!
   end
 
-  test "#load returns nil runner when labels are absent" do
-    Given "a dev.yml with a labelless runner block"
-    tmp = write_dev_yml(<<~YAML)
-      name: myproject
-      runner:
-        dir: "~/actions-runner"
-    YAML
-
-    When "the manifest is loaded"
-    manifest = build_loader.load(Pathname.new(tmp.path))
+  test "#slug normalizes the manifest name into the canonical project id" do
+    Given "manifests whose names carry case and separators"
+    cellbound = Dev::ProjectManifest.new(name: "Cellbound3D", commands: {})
+    unreal = Dev::ProjectManifest.new(name: "unreal-engine", commands: {})
 
-    Then
-    manifest.runner.nil?
-
-    Cleanup
-    tmp.close!
+    Expect "downcased, non-alphanumerics stripped — the repo runner label"
+    cellbound.slug == "cellbound3d"
+    unreal.slug == "unrealengine"
+    Dev::ProjectManifest.slug("Cellbound3D") == "cellbound3d"
   end
 
   test "#load handles container: false on individual commands" do
diff --git a/test/dev/runner_status_test.rb b/test/dev/runner_status_test.rb
index cc1e14c..dc1ff6d 100644
--- a/test/dev/runner_status_test.rb
+++ b/test/dev/runner_status_test.rb
@@ -2,8 +2,10 @@
 # frozen_string_literal: true
 
 require "test_helper"
+require "dev/runner_discovery"
+require "dev/runner_registry"
 require "dev/runner_status"
-require "dev/runner_setup_config"
+require "fileutils"
 require "json"
 require "stringio"
 require "tmpdir"
@@ -25,6 +27,18 @@ def capture(*cmd)
   end
 end unless defined?(CannedStatusExecutor)
 
+# The GitHub-side seam for status: answers find from a responder, so tests
+# canned-answer labels, absence, or a QueryError (offline).
+class CannedRegistry
+  def initialize(&responder)
+    @responder = responder
+  end
+
+  def find(scope:, name:)
+    @responder ? @responder.call(scope, name) : nil
+  end
+end unless defined?(CannedRegistry)
+
 transform!(RSpock::AST::Transformation)
 class Dev::RunnerStatusTest < Minitest::Test
   ALL_GREEN_PROBES = {
@@ -34,53 +48,82 @@ class Dev::RunnerStatusTest < Minitest::Test
     ["brew", "list", "--formula", "colima"] => true,
   }.freeze
 
-  test "reports an unregistered runner" do
-    Given "a bare-label config with no registration on disk"
+  test "reports a host with no enrollments" do
+    Given "an empty home"
     out = StringIO.new
-    status = build_status(labels: "gamebox", out: out)
+    status = build_status(out: out)
 
     When "reporting"
     status.report
 
-    Then "the registration line says so and no agent host section appears"
-    out.string.include?("not registered")
+    Then "the report says so and no agent host section appears"
+    out.string.include?("No runners enrolled on this host")
     !out.string.include?("Agent host")
   end
 
-  test "reports the registered scope read from the runner's own record" do
-    Given "a registered runner dir"
+  test "reports each discovered enrollment's scope and its GitHub labels" do
+    Given "an org enrollment whose labels GitHub answers"
     out = StringIO.new
-    runner_dir = Dir.mktmpdir
-    File.write(
-      File.join(runner_dir, ".runner"),
-      JSON.dump({ "gitHubUrl" => "https://github.com/d3mlabs/cellbound-3d" }),
-    )
-    status = build_status(labels: "gamebox", out: out, runner_dir: runner_dir)
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs", name: "mac-box")
+    responder = ->(_scope, _name) { Dev::RunnerRegistry::Runner.new(id: 42, custom_labels: %w[ai-ask ai-edit]) }
+    status = build_status(out: out, home: home, registry: CannedRegistry.new(&responder))
+
+    When "reporting"
+    status.report
+
+    Then "scope from the .runner record, labels from GitHub — nothing local"
+    out.string.include?("Runner 'mac-box'")
+    out.string.include?("registered: d3mlabs")
+    out.string.include?("labels: ai-ask, ai-edit")
+  end
+
+  test "flags an enrollment GitHub has lost" do
+    Given "a .runner record whose runner is gone server-side"
+    out = StringIO.new
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs", name: "mac-box")
+    status = build_status(out: out, home: home, registry: CannedRegistry.new)
 
     When "reporting"
     status.report
 
     Then
-    out.string.include?("registered: d3mlabs/cellbound-3d")
+    out.string.include?("[!!] gone on GitHub")
   end
 
-  test "inspects the full agent host for agent-capability labels" do
-    Given "an agent-labeled config over an all-green host"
+  test "degrades to labels-unknown when GitHub is unreachable" do
+    Given "a registry that cannot be queried (offline)"
     out = StringIO.new
-    runner_dir = Dir.mktmpdir
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs", name: "mac-box")
+    responder = ->(_scope, _name) { raise Dev::RunnerRegistry::QueryError, "network is unreachable" }
+    status = build_status(out: out, home: home, registry: CannedRegistry.new(&responder))
+
+    When "reporting"
+    status.report
+
+    Then "the rest of the report still lands"
+    out.string.include?("registered: d3mlabs")
+    out.string.include?("labels unknown")
+    out.string.include?("Host tooling")
+  end
+
+  test "inspects the full agent host when a discovered enrollment carries agent labels" do
+    Given "an agent-labeled enrollment over an all-green host"
+    out = StringIO.new
+    home = Dir.mktmpdir
+    runner_dir = write_runner(home, "actions-runner-cellbound3d", scope: "d3mlabs", name: "mac-box")
     work = File.join(runner_dir, "_work")
+    FileUtils.mkdir_p(work)
     shared_root = Dir.mktmpdir
     executor = CannedStatusExecutor.new(
       probe_results: ALL_GREEN_PROBES,
       capture_results: { ["stat", "-f", "%Sg %Sp", work] => "ai drwxrwsr-x\n" },
     )
-    FileUtils.mkdir_p(work)
-    File.write(
-      File.join(runner_dir, ".runner"),
-      JSON.dump({ "gitHubUrl" => "https://github.com/d3mlabs/cellbound-3d" }),
-    )
+    responder = ->(_scope, _name) { Dev::RunnerRegistry::Runner.new(id: 42, custom_labels: ["ai-build"]) }
     status = build_status(
-      labels: "ai-build", out: out, runner_dir: runner_dir,
+      out: out, home: home, registry: CannedRegistry.new(&responder),
       executor: executor, shared_root: shared_root,
       sudoers_path: existing_file, container_required: true,
     )
@@ -99,10 +142,13 @@ class Dev::RunnerStatusTest < Minitest::Test
   end
 
   test "flags every missing agent host fact" do
-    Given "an agent-labeled config over a cold host"
+    Given "an agent-labeled enrollment over a cold host"
     out = StringIO.new
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-x", scope: "d3mlabs", name: "box")
+    responder = ->(_scope, _name) { Dev::RunnerRegistry::Runner.new(id: 1, custom_labels: ["ai-learn"]) }
     status = build_status(
-      labels: "ai-learn", out: out,
+      out: out, home: home, registry: CannedRegistry.new(&responder),
       sudoers_path: File.join(Dir.mktmpdir, "absent"),
       shared_root: File.join(Dir.mktmpdir, "absent"),
       container_required: true,
@@ -116,9 +162,12 @@ class Dev::RunnerStatusTest < Minitest::Test
   end
 
   test "the engine line appears only when the served repo builds in a container" do
-    Given "an agent-labeled config without a container"
+    Given "an agent-labeled enrollment without a container"
     out = StringIO.new
-    status = build_status(labels: "ai-build", out: out, container_required: false)
+    home = Dir.mktmpdir
+    write_runner(home, "actions-runner-x", scope: "d3mlabs", name: "box")
+    responder = ->(_scope, _name) { Dev::RunnerRegistry::Runner.new(id: 1, custom_labels: ["ai-build"]) }
+    status = build_status(out: out, home: home, registry: CannedRegistry.new(&responder), container_required: false)
 
     When "reporting"
     status.report
@@ -134,11 +183,11 @@ class Dev::RunnerStatusTest < Minitest::Test
     executor = CannedStatusExecutor.new(
       probe_results: { ["brew", "bundle", "check", "--file=#{brewfile}"] => true },
     )
-    status = build_status(labels: "gamebox", out: out, executor: executor, brewfile_path: brewfile)
+    status = build_status(out: out, executor: executor, brewfile_path: brewfile)
 
     # and a status with no Brewfile shipped
     out_none = StringIO.new
-    status_none = build_status(labels: "gamebox", out: out_none, brewfile_path: nil)
+    status_none = build_status(out: out_none, brewfile_path: nil)
 
     When "reporting both"
     status.report
@@ -165,13 +214,22 @@ def existing_file
     path
   end
 
-  def build_status(labels:, out:, runner_dir: File.join(Dir.mktmpdir, "absent-runner"),
+  # A .runner record the way config.sh writes it (UTF-8 BOM + JSON).
+  def write_runner(home, dir_name, scope:, name:)
+    dir = File.join(home, dir_name)
+    FileUtils.mkdir_p(dir)
+    record = { "agentName" => name, "gitHubUrl" => "https://github.com/#{scope}" }
+    File.write(File.join(dir, ".runner"), "\uFEFF#{JSON.generate(record)}")
+    dir
+  end
+
+  def build_status(out:, home: Dir.mktmpdir, registry: CannedRegistry.new,
                    executor: CannedStatusExecutor.new, shared_root: Dir.mktmpdir,
                    sudoers_path: File.join(Dir.mktmpdir, "absent"), brewfile_path: nil,
                    container_required: false)
     Dev::RunnerStatus.new(
-      config: Dev::RunnerSetupConfig.new(labels: labels),
-      runner_dir: runner_dir,
+      discovery: Dev::RunnerDiscovery.new(home: home),
+      registry: registry,
       out: out,
       executor: executor,
       runner_user: "human",
diff --git a/test/dev/runner_test.rb b/test/dev/runner_test.rb
index b2b5207..956fa90 100644
--- a/test/dev/runner_test.rb
+++ b/test/dev/runner_test.rb
@@ -259,28 +259,35 @@ class RunnerTest < Minitest::Test
     $stderr = old_stderr
   end
 
-  test "usage includes runner-setup when a runner block is declared" do
-    Given "a Runner whose dev.yml declares a runner block"
+  test "runner is ungated: every project catalog lists it" do
+    Given "a Runner with a plain dev.yml (no runner block — the key is retired)"
     out = StringIO.new
-    runner = build_runner(commands: {}, runner: { "labels" => "ue-engine" }, out: out)
+    runner = build_runner(commands: {}, out: out)
 
     When "we print usage"
     runner.run([])
 
-    Then "the runner-setup command is listed"
+    Then "the runner command (and its runner-setup alias) is listed"
+    out.string.include?("runner")
     out.string.include?("runner-setup")
   end
 
-  test "runner-setup is not registered without a runner block" do
-    Given "a Runner with no runner block"
+  test "a leftover dev.yml runner block warns and is ignored" do
+    Given "a dev.yml still carrying the retired key"
     out = StringIO.new
-    runner = build_runner(commands: {}, out: out)
+    old_stderr = $stderr
+    $stderr = StringIO.new
+    runner = build_runner(commands: {}, runner: { "labels" => "ue-engine" }, out: out)
 
     When "we print usage"
     runner.run([])
 
-    Then "no runner-setup command is listed"
-    !out.string.include?("runner-setup")
+    Then "the run proceeds with a retirement warning"
+    $stderr.string.include?("`runner:` is retired")
+    out.string.include?("runner-setup")
+
+    Cleanup
+    $stderr = old_stderr
   end
 
   test "run assembles the execution context and hands the command to the service" do

From b64a78e6b232e5d4ae9aae61e3f82d69191dc625 Mon Sep 17 00:00:00 2001
From: Jean-Philippe <jpduchesne89@gmail.com>
Date: Sat, 12 Sep 2026 21:29:02 -0400
Subject: [PATCH 3/3] Cover the default factory wiring (codecov patch)

The rewrite dropped the default-factories test, leaving the three
default lambdas (setup/contracts/status) uncovered. Restored for the
new wiring: construction boundaries intercepted, discovery redirected
at an empty home so the run never reads this machine's enrollments.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 test/dev/builtins/runner_command_test.rb | 28 ++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/test/dev/builtins/runner_command_test.rb b/test/dev/builtins/runner_command_test.rb
index a30e081..d35f109 100644
--- a/test/dev/builtins/runner_command_test.rb
+++ b/test/dev/builtins/runner_command_test.rb
@@ -319,6 +319,34 @@ class Dev::Builtins::RunnerCommandTest < Minitest::Test
     true
   end
 
+  test "the default factories build the real collaborators" do
+    Given "a command with its default wiring, every construction boundary intercepted"
+    # RunnerSetup#run registers the host and RunnerStatus#report inspects it,
+    # so the test intercepts both construction boundaries and asserts the
+    # default factories' wiring (the bare ue-engine label makes the default
+    # contracts factory resolve to no contracts). Discovery is redirected at
+    # an empty home so the run never depends on this machine's enrollments.
+    empty_discovery = Dev::RunnerDiscovery.new(home: Dir.mktmpdir)
+    Dev::RunnerDiscovery.expects(:new).returns(empty_discovery)
+    setup = typed_mock(Dev::RunnerSetup)
+    setup.expects(:run).once
+    setup.stubs(:resolve_dir).returns("/tmp/runner-dir")
+    setup.stubs(:resolve_scope).returns("owner/repo")
+    Dev::RunnerSetup.expects(:new)
+      .with(config: Dev::RunnerSetupConfig.new(labels: "ue-engine"), repo: nil, org: false).returns(setup)
+    status = typed_mock(Dev::RunnerStatus)
+    status.expects(:report).once
+    Dev::RunnerStatus.expects(:new).with(container_required: false).returns(status)
+    command = Dev::Builtins::RunnerCommand.new
+
+    When "running register, then status"
+    command.call(args: ["register", "--labels", "ue-engine"], context: projectless_context)
+    command.call(args: ["status"], context: projectless_context)
+
+    Then "the expectations on the construction boundaries hold"
+    true
+  end
+
   test "an unknown subcommand raises the usage error" do
     Given "a harness"
     harness = build_harness