space-architect 8.0.0 → 9.1.0

data/lib/space_architect/architect_project.rb

@@ -127,38 +127,47 @@ module Space::Architect
     end
 
     # Allocate the next ordinal and scaffold architecture/I<NN>-<iteration>.md.
+    # Serialized across processes: ordinal allocation is a read-modify-write of
+    # space.yaml's project block, and two concurrent `architect new` processes
+    # would duplicate the ordinal and silently drop the loser's iterations
+    # entry (last writer wins). The metadata is saved by atomic replace, so the
+    # lock is a sibling file under tmp/ (gitignored, space-standard) — never
+    # space.yaml itself — and the metadata is re-loaded inside the lock because
+    # every process booted with its own pre-scaffold snapshot.
     def new_iteration!(name, message: nil)
-      block = space.data["project"] || {}
-      iterations = block["iterations"] || []
-      if iterations.any? { |s| s["name"] == name }
-        raise Space::Core::Error, "iteration '#{name}' already exists in space.yaml"
-      end
+      with_scaffold_lock do
+        block = space.data["project"] || {}
+        iterations = block["iterations"] || []
+        if iterations.any? { |s| s["name"] == name }
+          raise Space::Core::Error, "iteration '#{name}' already exists in space.yaml"
+        end
 
-      ordinal = (iterations.map { |s| s["ordinal"] || 0 }.max || 0) + 1
-      nn = format("%02d", ordinal)
-      rel = "architecture/I#{nn}-#{name}.md"
-      path = space.path.join(rel)
-      raise Space::Core::Error, "#{rel} already exists" if path.exist?
+        ordinal = (iterations.map { |s| s["ordinal"] || 0 }.max || 0) + 1
+        nn = format("%02d", ordinal)
+        rel = "architecture/I#{nn}-#{name}.md"
+        path = space.path.join(rel)
+        raise Space::Core::Error, "#{rel} already exists" if path.exist?
 
-      FileUtils.mkdir_p(path.dirname)
-      path.write(render_iteration(nn, name))
+        FileUtils.mkdir_p(path.dirname)
+        path.write(render_iteration(nn, name))
 
-      update_architect_block do |b|
-        b["current_iteration"] = name
-        list = b["iterations"] || []
-        list << {
-          "name" => name, "ordinal" => ordinal, "file" => rel,
-          "freeze_sha" => nil, "verdict" => "pending", "lanes" => []
-        }
-        b["iterations"] = list
-        b
-      end
+        update_architect_block do |b|
+          b["current_iteration"] = name
+          list = b["iterations"] || []
+          list << {
+            "name" => name, "ordinal" => ordinal, "file" => rel,
+            "freeze_sha" => nil, "verdict" => "pending", "lanes" => []
+          }
+          b["iterations"] = list
+          b
+        end
 
-      git_run("-C", space.path.to_s, "add", rel, Space::Core::Space::METADATA_FILE)
-      git_run("-C", space.path.to_s, "commit", "-m",
-        compose_message("I#{nn} scaffold:", "I#{nn}: scaffold #{name}", message))
+        git_run("-C", space.path.to_s, "add", rel, Space::Core::Space::METADATA_FILE)
+        git_run("-C", space.path.to_s, "commit", "-m",
+          compose_message("I#{nn} scaffold:", "I#{nn}: scaffold #{name}", message))
 
-      path
+        path
+      end
     end
 
     def status
@@ -701,8 +710,12 @@ module Space::Architect
     def worktree_add(repo, iteration, lane, base: nil, base_explicit: !base.nil?, harness: nil, model: nil,
                      variant: false, effort: nil, touch: nil, force: false, err: $stderr)
       model, suffix_level = Harness.parse_model_suffix(model)
-      harness, model = resolve_harness_model(harness, model)
-      resolved_level = effort || suffix_level || project_defaults["effort"]
+      harness, model, inform = resolve_harness_model(harness, model)
+      err.puts inform if inform
+      # The config layer sits above project.effort — architect.yaml is the
+      # dedicated routing layer; unconfigured spaces fall through unchanged.
+      resolved_level = effort || suffix_level ||
+        Routing.for_space(space.path)&.dig("builder", "thinking") || project_defaults["effort"]
       Harness.validate_thinking_level!(resolved_level)
       if effort.nil? && suffix_level
         err.puts "thinking: model suffix ':#{suffix_level}' parsed from lane model → level=#{suffix_level} (model stripped)"
@@ -1033,6 +1046,25 @@ module Space::Architect
 
     attr_reader :space
 
+    # Exclusive cross-process lock around one whole critical section (used by
+    # new_iteration!): flock on .git/architect.lock — the metadata file itself
+    # cannot be the lock because save() replaces it by atomic rename (a new
+    # inode would not contend), and .git is the one directory every scaffoldable
+    # space guarantees (new_iteration! commits) that git never reports as
+    # untracked noise (git's own index.lock lives by the same convention).
+    # Inside the lock the metadata is adopted in place (data.replace, keeping
+    # object identity for every holder of this space) — each process booted
+    # with its own pre-scaffold snapshot, so the ordinal must be read from
+    # disk truth.
+    def with_scaffold_lock
+      lock_path = space.path.join(".git", "architect.lock")
+      File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
+        lock.flock(File::LOCK_EX)
+        space.data.replace(Space::Core::Space.load(space.path).data)
+        yield
+      end
+    end
+
     # The vendored builder-guard extension shipped in the gem (lib/space_architect/pi/).
     def vendored_guard_path
       Pathname.new(__dir__).join("pi/builder-guard.ts")
@@ -1605,19 +1637,35 @@ module Space::Architect
     end
 
     # Resolve harness + model by precedence: explicit value > (dispatch only) the
-    # lane's stored value > space.yaml project.harness/project.model > the pi
-    # default model. Shared by worktree_add and dispatch so both read the same
-    # defaults. A stored model is only honored when its stored harness still matches
-    # the resolved harness — a dispatch-time harness override drops the old harness's
-    # stored model instead of leaking it into the new harness's run. A stored
-    # legacy harness name survives resolution (so a stale space.yaml
-    # surfaces as Harness.for's actionable pi-only error, not a silent default).
+    # lane's stored value > architect.yaml builder-role model > space.yaml
+    # project.harness/project.model > the pi default model. Shared by worktree_add
+    # and dispatch so both read the same defaults. A stored model is only honored
+    # when its stored harness still matches the resolved harness — a dispatch-time
+    # harness override drops the old harness's stored model instead of leaking it
+    # into the new harness's run. A stored legacy harness name survives resolution
+    # (so a stale space.yaml surfaces as Harness.for's actionable pi-only error,
+    # not a silent default).
+    #
+    # Returns [harness, model, inform] — inform is the loud last-resort line (nil
+    # otherwise) for the caller to print once to its err stream when the model
+    # fell all the way through to Harness::DEFAULT_MODEL (no flag, no stored
+    # value, no architect.yaml builder role, no project.model).
     def resolve_harness_model(harness, model, stored_harness: nil, stored_model: nil)
       defaults = project_defaults
       resolved_harness = (harness || stored_harness || defaults["harness"] || "pi").to_s
       stored_model = nil unless stored_harness.nil? || stored_harness.to_s == resolved_harness
-      resolved_model = model || stored_model || defaults["model"] || Harness::DEFAULT_MODEL
-      [resolved_harness, resolved_model]
+      config_model = Routing.for_space(space.path)&.dig("builder", "model")
+      resolved_model = model || stored_model || config_model || defaults["model"] || Harness::DEFAULT_MODEL
+      inform = default_model_inform if model.nil? && stored_model.nil? && config_model.nil? && defaults["model"].nil?
+      [resolved_harness, resolved_model, inform]
+    end
+
+    # The loud last-resort inform — the bare DEFAULT_MODEL constant is a last
+    # resort, not a silent fallback: name that no architect.yaml was found, the
+    # two paths looked at, and the default in use.
+    def default_model_inform
+      "model: no architect.yaml found (looked at #{Routing.space_path(space.path)} + #{Routing.global_path}) — " \
+        "using default '#{Harness::DEFAULT_MODEL}'"
     end
 
     # --prompt: the caller authors the lane prompt anywhere (a fresh scratch file) and
@@ -1640,8 +1688,9 @@ module Space::Architect
     # precedence and thinking-level translation from one place.
     def resolve_dispatch_harness(lane_entry, model:, harness:, effort:, force:, err:)
       model, suffix_level = Harness.parse_model_suffix(model)
-      resolved_harness, resolved_model = resolve_harness_model(harness, model,
+      resolved_harness, resolved_model, inform = resolve_harness_model(harness, model,
         stored_harness: lane_entry["harness"], stored_model: lane_entry["model"])
+      err.puts inform if inform
 
       resolved_effort =
         if effort
@@ -1651,7 +1700,9 @@ module Space::Architect
           err.puts "thinking: model suffix ':#{suffix_level}' parsed from --model → level=#{suffix_level} (model stripped to '#{model}')"
           suffix_level
         else
-          lane_entry["effort"]
+          # Dispatch's tail is the lane's stored effort (project.effort was never
+          # in the dispatch chain); architect.yaml builder thinking slots in above it.
+          lane_entry["effort"] || Routing.for_space(space.path)&.dig("builder", "thinking")
         end
 
       [resolved_harness, resolved_model, resolved_effort]

data/lib/space_architect/bug_report.rb

@@ -79,7 +79,8 @@ module Space
           <<~MD
             ## Diagnostics
 
-            - space-architect: #{Space::Core::VERSION}
+            - space-architect: #{Space::Architect::VERSION}
+            - space-cadet: #{Space::Core::VERSION}
             - ruby: #{RUBY_VERSION} (#{RUBY_PLATFORM})
           MD
         end

data/lib/space_architect/cli/architect.rb

@@ -2,9 +2,9 @@
 
 require "json"
 require "fileutils"
-require "space_src/launchd/agent"
 require_relative "../jobs_client"
 require_relative "../conversations_client"
+require_relative "../loop_cost"
 require_relative "../session_sync"
 
 module Space::Architect
@@ -12,8 +12,8 @@ module Space::Architect
     # Optional loop-phase DSL on the shared command base, read by
     # Space::Core::CLI::Help to group the help listing. A command may declare
     # `phase <order>, "<Label>"`; groups, and members within a group, sort by
-    # <order>. Only architect commands declare one — space commands leave it nil
-    # and render as the single ungrouped default listing (unchanged).
+    # <order>. Only architect commands declare one — commands without a phase
+    # render as the single ungrouped default listing (unchanged).
     class BaseCommand
       def self.phase(order = nil, label = nil)
         return @phase if order.nil?
@@ -166,6 +166,10 @@ module Space::Architect
               project = ArchitectProject.new(space: sp)
               info = project.status
               block = info[:block]
+              # Legacy lanes store no model — resolve the config layer once so the
+              # display shows what they would actually route, and mark the bare
+              # constant as the last resort it is, not ordinary behavior.
+              config_model = Routing.for_space(sp.path)&.dig("builder", "model")
 
               terminal.say "Project status:     #{block['status'] || '(none)'}"
               terminal.say "Current iteration:  #{block['current_iteration'] || '(none)'}"
@@ -179,7 +183,7 @@ module Space::Architect
                   lane_list = s["lanes"] || []
                   lanes_str = lane_list.map do |l|
                     h = l["harness"] || "pi"
-                    m = l["model"]   || Harness::DEFAULT_MODEL
+                    m = l["model"] || config_model || "#{Harness::DEFAULT_MODEL} (last resort)"
                     eff = l["effort"] ? "·#{l['effort']}" : ""
                     "#{l['name']}(#{l['repo']}·#{h}·#{m}#{eff})"
                   end.join(", ")
@@ -485,7 +489,7 @@ module Space::Architect
         argument :lane,      required: true,  desc: "Lane name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
         option   :prompt,    default: nil,    desc: "Read the lane prompt from this file (copied byte-for-byte to build/<id>-<lane>/prompt.md)"
-        option   :model,     default: nil,    desc: "Builder model to pin (default: the lane's stored model, else space.yaml project.model, else the pi default #{Harness::DEFAULT_MODEL}). Any provider/tier; pin a full id, not a floating alias"
+        option   :model,     default: nil,    desc: "Builder model to pin (default: the lane's stored model, else architect.yaml builder role, else space.yaml project.model, else the pi default #{Harness::DEFAULT_MODEL} — a loudly-informed last resort). Any provider/tier; pin a full id, not a floating alias"
         option   :max_turns, default: "200",  desc: "Max turns for the builder"
         option   :harness,   default: nil,    desc: "Harness (pi)"
         option   :effort,    default: nil,    desc: "Thinking/reasoning effort level — alias for --thinking/--reasoning (off, minimal, low, medium, high, xhigh, max)"
@@ -800,7 +804,8 @@ module Space::Architect
             terminal.say result[:command]
             terminal.say ""
             terminal.say "Diagnostics:"
-            terminal.say "  space-architect #{Space::Core::VERSION}"
+            terminal.say "  space-architect #{Space::Architect::VERSION}"
+            terminal.say "  space-cadet #{Space::Core::VERSION}"
             terminal.say "  ruby #{RUBY_VERSION} (#{RUBY_PLATFORM})"
             terminal.say "  space: #{space.id} — #{space.title}" if space
             CLI.record_outcome(Outcome.new(exit_code: 0))
@@ -808,6 +813,165 @@ module Space::Architect
         end
       end
 
+      # Read-only loop accounting: spend and speed from the pi session
+      # artifacts already on disk (run metas + interactive/runner session
+      # files), stdout only. All view math lives in LoopCost; this class only
+      # resolves the space and renders — text tables and --json come from the
+      # same report hash so the two surfaces can never disagree.
+      class Cost < BaseCommand
+        desc "Account loop cost and latency from pi session artifacts (read-only)"
+        phase 54, "Project"
+        # The three view flags declare dry-cli's :flag type, not :boolean —
+        # the frozen cost-flags gate pins the literal `--json`-style tokens in
+        # --help, which :boolean would render as `--[no-]json`.
+        option :json,          type: :flag, default: false, desc: "Emit the frozen JSON contract instead of tables"
+        option :space,         desc: "Space identifier or path (default: nearest ancestor with space.yaml)"
+        option :sessions_root, desc: "pi sessions root (default: ~/.pi/agent/sessions via SessionSync)"
+        option :since,         desc: "Only artifacts starting at/after this ISO-8601 timestamp or YYYY-MM-DD date"
+        option :by_iteration,  type: :flag, default: false, desc: "Split the cost table into per-iteration windows"
+        option :latency,       type: :flag, default: false, desc: "Per-model latency: round wall, turn vs generation tok/s, tool wait share"
+        option :precise,       type: :flag, default: false, desc: "Exact token counts with thousands separators (default: 3 significant figures)"
+
+        def call(json: false, space: nil, sessions_root: nil, since: nil,
+                 by_iteration: false, latency: false, precise: false, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            if by_iteration && latency
+              raise Space::Core::Error, "--by-iteration and --latency are mutually exclusive — one view per invocation"
+            end
+            render(store.find(space)) do |sp|
+              report = LoopCost.report(
+                space: sp,
+                sessions_root: sessions_root || SessionSync.default_pi_root,
+                since: since,
+                by_iteration: by_iteration,
+                latency: latency
+              )
+              terminal.say(json ? JSON.pretty_generate(report) : render_cost_text(report, by_iteration, latency, precise))
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+
+        private
+
+        def render_cost_text(report, by_iteration, latency, precise)
+          if latency
+            latency_table(report["latency"], precise)
+          elsif by_iteration
+            by_iteration_text(report, precise)
+          else
+            cost_table(report["rows"], report["totals"], precise)
+          end
+        end
+
+        def cost_table(rows, totals, precise)
+          headers = %w[Agent Model Runs Input Output CacheRead CacheWrite $ Turns Hit%]
+          body = rows.map { |row| cost_cells(row, precise) }
+          body << totals_cells(totals, precise)
+          render_table(headers, body)
+        end
+
+        def by_iteration_text(report, precise)
+          report["iterations"].flat_map do |bucket|
+            label = bucket["starts_at"] || "-"
+            [
+              "—— #{bucket['name']} (starts_at #{label})",
+              cost_table(bucket["rows"], bucket["totals"], precise),
+              ""
+            ]
+          end + ["Grand total", totals_table(report["grand_total"], precise)]
+        end
+
+        def latency_table(rows, precise)
+          headers = %w[Model Rounds Mean\ wall\ (s) Turn\ tok/s Gen\ tok/s Wait%]
+          body = rows.map do |row|
+            [row["model"], count_label(row["rounds"], precise), format("%.2f", row["mean_wall_s"]),
+             format("%.2f", row["output_toks_per_s"]), format("%.2f", row["gen_toks_per_s"]),
+             format("%.1f%%", row["wait_share"] * 100)]
+          end
+          render_table(headers, body)
+        end
+
+        def totals_table(totals, precise)
+          render_table(%w[Runs Input Output CacheRead CacheWrite $ Turns Hit%], [totals_cells(totals, precise)[2..]])
+        end
+
+        def totals_cells(totals, precise)
+          ["TOTAL", "", count_label(totals["runs"], precise), count_label(totals["input"], precise),
+           count_label(totals["output"], precise), count_label(totals["cache_read"], precise),
+           count_label(totals["cache_write"], precise), format("%.4f", totals["cost"]),
+           count_label(totals["turns"], precise), hit_label(totals["cache_hit_ratio"])]
+        end
+
+        def cost_cells(row, precise)
+          [row["agent"], row["model"], count_label(row["runs"], precise), count_label(row["input"], precise),
+           count_label(row["output"], precise), count_label(row["cache_read"], precise),
+           count_label(row["cache_write"], precise), format("%.4f", row["cost"]),
+           count_label(row["turns"], precise), hit_label(row["cache_hit_ratio"])]
+        end
+
+        def hit_label(ratio)
+          format("%.1f%%", ratio * 100)
+        end
+
+        # Token counts are unreadable as raw digit strings at loop scale
+        # (1,833,889,482 cache-read tokens): 3 significant figures with an SI
+        # suffix by default, exact thousands-separated integers for --precise.
+        SIG_UNITS = [["T", 1e12], ["B", 1e9], ["M", 1e6], ["K", 1e3]].freeze
+        private_constant :SIG_UNITS
+
+        def count_label(value, precise)
+          integer = value.to_i
+          return integer.to_s if integer < 1000
+          # stdlib has no thousands-separator format (the %'d flag is glibc, not Ruby)
+          return integer.to_s.reverse.scan(/\d{1,3}/).join(",").reverse if precise
+
+          SIG_UNITS.each_with_index do |(suffix, scale), index|
+            next unless integer >= scale
+            mantissa = integer.fdiv(scale)
+            decimals = mantissa >= 100 ? 0 : mantissa >= 10 ? 1 : 2
+            text = format("%.#{decimals}f", mantissa)
+            # Rounding overflowed the mantissa (999,500 → "1000K") — bump one
+            # scale up (units run large → small).
+            return "1#{SIG_UNITS[index - 1][0]}" if text.to_f >= 1000 && index.positive?
+            return "#{text}#{suffix}"
+          end
+        end
+
+        # Colors on the human views: header and TOTAL rows bold, the $ column
+        # yellow. terminal.table cannot do this — it pads by raw length before
+        # styling, so a pre-colored cell would skew alignment (and its by-header
+        # color dispatch belongs to space-cadet) — so the cost views pad from
+        # plain strings here, then style through terminal.pastel: the
+        # --color/--colors gating is inherited unchanged.
+        def render_table(headers, rows)
+          widths = headers.each_index.map do |index|
+            ([headers[index]] + rows.map { |row| row[index].to_s }).map(&:length).max
+          end
+          lines = [table_line(headers, widths, bold: true)]
+          cost_index = headers.index("$")
+          rows.each do |row|
+            lines << table_line(row, widths, bold: row.first.to_s == "TOTAL", color_index: cost_index)
+          end
+          lines.join("\n")
+        end
+
+        def table_line(cells, widths, bold: false, color_index: nil)
+          cells.each_with_index.map do |cell, index|
+            text = cell.to_s
+            styled = if bold
+              terminal.pastel.bold(text)
+            elsif index == color_index
+              terminal.pastel.yellow(text)
+            else
+              text
+            end
+            "#{styled}#{' ' * (widths[index] - text.length)}"
+          end.join("   ").rstrip
+        end
+      end
+
       class InstallSkills < BaseCommand
         desc "Install bundled skills (architect, architect-research, architect-vocabulary) for a harness"
         phase 53, "Project"
@@ -840,7 +1004,7 @@ module Space::Architect
           argument :space,     required: false, desc: "Space identifier (default: $PWD)"
           option   :base,      default: nil,          desc: "Base ref (default: HEAD of repo)"
           option   :harness,   default: nil,          desc: "Harness (pi; default: space.yaml project.harness, else pi)"
-          option   :model,     default: nil,           desc: "Model; a trailing :<level> suffix (e.g. foo:high) is parsed into --effort (default: space.yaml project.model, else the pi default #{Harness::DEFAULT_MODEL})"
+          option   :model,     default: nil,           desc: "Model; a trailing :<level> suffix (e.g. foo:high) is parsed into --effort (default: architect.yaml builder role, else space.yaml project.model, else the pi default #{Harness::DEFAULT_MODEL} — a loudly-informed last resort)"
           option   :effort,    default: nil,           desc: "Thinking/reasoning effort level — alias for --thinking/--reasoning (off, minimal, low, medium, high, xhigh, max)"
           option   :thinking,  default: nil,           desc: "Thinking/reasoning effort level — alias for --effort/--reasoning (off, minimal, low, medium, high, xhigh, max)"
           option   :reasoning, default: nil,           desc: "Thinking/reasoning effort level — alias for --effort/--thinking (off, minimal, low, medium, high, xhigh, max)"
@@ -923,7 +1087,7 @@ module Space::Architect
           argument :repo,      required: true,  desc: "Repo name (under repos/)"
           argument :iteration, required: true,  desc: "Iteration name"
           argument :space,     required: false, desc: "Space identifier (default: $PWD)"
-          option   :pairs,     required: true,  desc: "Comma-separated harness[:model] pairs (e.g. pi,pi:#{Harness::DEFAULT_MODEL})"
+          option   :pairs,     required: true,  desc: "Comma-separated harness[:model] pairs (e.g. \"pi,pi:provider/model-id:high\"); a pair without a model resolves via the lane model chain (see worktree add)"
           option   :base,      default: nil,    desc: "Base ref (default: HEAD of repo)"
           option   :prompt,    default: nil,    desc: "Prompt file to fan-out byte-identical to each variant"
 
@@ -1168,6 +1332,17 @@ module Space::Architect
             end
 
             def format_failure(f) = f.is_a?(Hash) ? f.inspect : f.to_s
+
+            # The launchd-agent seam is repo-tender's — a soft dependency, never a
+            # gemspec runtime dep. Required lazily so `sessions agent …` degrades
+            # with an actionable hint instead of failing at boot when the gem is
+            # absent; handle_errors turns the raise into a red message + exit 1.
+            def agent
+              require "repo_tender"
+              RepoTender::Launchd::Agent
+            rescue LoadError
+              raise Space::Core::Error, "sessions agent needs the repo-tender gem — install it with: gem install repo-tender"
+            end
           end
 
           class Install < BaseCommand
@@ -1196,7 +1371,7 @@ module Space::Architect
                 File.write(pp, xml)
                 File.chmod(0o600, pp)
 
-                result = Space::Src::Launchd::Agent.new(label: SessionSync::LABEL).install(pp)
+                result = agent.new(label: SessionSync::LABEL).install(pp)
                 raise Space::Core::Error, "bootstrap failed: #{format_failure(result.failure)}" if result.failure?
 
                 terminal.say "Installed: #{terminal.path(pp)}"
@@ -1213,7 +1388,7 @@ module Space::Architect
               setup_terminal(**opts.slice(:color, :colors))
               handle_errors do
                 pp = plist_path
-                result = Space::Src::Launchd::Agent.new(label: SessionSync::LABEL).uninstall
+                result = agent.new(label: SessionSync::LABEL).uninstall
                 terminal.say "bootout reported: #{format_failure(result.failure)}" if result.failure?
 
                 if File.exist?(pp)
@@ -1234,7 +1409,7 @@ module Space::Architect
             def call(**opts)
               setup_terminal(**opts.slice(:color, :colors))
               handle_errors do
-                result = Space::Src::Launchd::Agent.new(label: SessionSync::LABEL).status
+                result = agent.new(label: SessionSync::LABEL).status
                 raise Space::Core::Error, "status failed: #{format_failure(result.failure)}" if result.failure?
 
                 s = result.success
@@ -1256,6 +1431,8 @@ end
 # Loop-phase declarations above sort the architect help listing; its namespaces
 # (brief/worktree/variant/research) declare no phase and list under this header.
 Space::Core::CLI::Help.trailing_group_label = "Groups"
+Space::Core::CLI::Help.product_name = "architect"
+Space::Core::CLI::Help.product_version = Space::Architect::VERSION
 
 Space::Architect::CLI::Registry.register "init",   Space::Architect::CLI::Architect::Init
 Space::Architect::CLI::Registry.register "ground", Space::Architect::CLI::Architect::Ground
@@ -1275,6 +1452,7 @@ Space::Architect::CLI::Registry.register "integrate", Space::Architect::CLI::Arc
 Space::Architect::CLI::Registry.register "gate",      Space::Architect::CLI::Architect::Gate
 Space::Architect::CLI::Registry.register "install-skills", Space::Architect::CLI::Architect::InstallSkills
 Space::Architect::CLI::Registry.register "bug-report",     Space::Architect::CLI::Architect::BugReport
+Space::Architect::CLI::Registry.register "cost",           Space::Architect::CLI::Architect::Cost
 Space::Architect::CLI::Registry.register "brief" do |b|
   b.register "new", Space::Architect::CLI::Architect::Brief::New
 end

data/lib/space_architect/cli/research.rb

@@ -8,7 +8,7 @@ module Space::Architect
           desc "Dispatch detached read-only research lanes (one per prompt file)"
           argument :prompts, type: :array, required: true,
             desc: "Prompt file(s) to dispatch (space-separated paths)"
-          option :model,     default: nil, desc: "Researcher model override (default: the pi default #{Space::Architect::Harness::DEFAULT_MODEL})"
+          option :model,     default: nil, desc: "Researcher model override (researchers are not architect.yaml-routed; without it the pi default #{Space::Architect::Harness::DEFAULT_MODEL} is used — a loudly-informed last resort)"
           option :max_turns, default: "40", desc: "Max turns per researcher"
 
           def call(prompts:, model: nil, max_turns: "40", **opts)

data/lib/space_architect/cli.rb

@@ -33,21 +33,11 @@ module Space::Architect
       end
 
       if VERSION_REQUEST.include?(argv)
-        out.puts Space::Core::VERSION
+        out.puts Space::Architect::VERSION
         return 0
       end
 
-      if argv.first == "src"
-        return dispatch_src(argv[1..], out, err)
-      end
-
-      normalized = normalize_args(argv)
-
-      if normalized.first == "space"
-        return dispatch_space(normalized[1..], out, err)
-      end
-
-      Dry::CLI.new(Registry).call(arguments: normalized, out: out, err: err)
+      Dry::CLI.new(Registry).call(arguments: normalize_args(argv), out: out, err: err)
       last_outcome&.exit_code || 0
     end
 
@@ -88,6 +78,13 @@ module Space::Architect
     end
 
     def self.run(argv, out = $stdout, err = $stderr)
+      # One-shot 8.x app-dir migration (the substrate's config/state, owned by
+      # Space::Core::Migration in space-cadet) before dispatch — skipped for
+      # the pure help/version queries so they stay side-effect-free. Running it
+      # here too means `architect` picks up an 8.x user's config even if they
+      # never ran `space` first.
+      Space::Core::Migration.run(err: err) unless TOP_LEVEL_HELP.include?(argv) || VERSION_REQUEST.include?(argv)
+
       Kernel.exit(call(argv, out, err))
     rescue Interrupt
       err.puts "interrupted"
@@ -97,6 +94,4 @@ module Space::Architect
 end
 
 require_relative "cli/architect"
-require_relative "cli/space"
-require_relative "cli/src"
 require_relative "cli/research"