space-cadet 9.1.0 → 9.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe74accf7bbff15d13d2de6eb5a9b6a99733ffed834023d78b49876c12e7eb8a
-  data.tar.gz: f34df4aee5aa19b2a25a695e7aa97807d8cff94c12e7006935cef71951a0904b
+  metadata.gz: c191a11ce1e7a132b55a094cf765ea168bc58a143c4d6239db28354349127ce9
+  data.tar.gz: a64cf8802acd3667b51783eaf3677223654a1cdb07f853d3ee9c72ef94ce55a5
 SHA512:
-  metadata.gz: 2a85cb897404242cf3e195ce6651c5f474a6765793264bde9e20a6ad23f11f24ce23c843cb08142f029bbf129c61146e73968a45d8be842ca277e0f89dc5e221
-  data.tar.gz: 4fbea23cf9429c4664777cb05819d8d20e5fa149bf36824f91f1e367be09defb108e8c4ccf38675dca9ce460d918aa06426e6486fd0db0b68a0944d47e6263d8
+  metadata.gz: 0a752744e4deb343a3f59b8cc45b25b67769e26243299e9825256e186db05361a8b299723877d71bcc1599c4321509d3735b4564f4ce876703c85d8ccade8dc2
+  data.tar.gz: c88b462412b4a43316678886c5c19ca3dcdbbe5492cd9af31031a6fc0f19064c3dda41dbca437684460d41c3e81be5d02fc1bdfd4b156bcea005c2df22e35dc0

data/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.2.0] - 2026-10-16
+
+### Added
+
+- **`--trust-host-key` flag on `space repo add` and `space new`.** Appends
+  `-o StrictHostKeyChecking=accept-new` to the ssh command used for clones
+  (TOFU: first-contact host keys are accepted automatically; *changed* keys
+  still fail verification, so MITM protection is retained). Using the flag
+  prints a stderr warning before fetching begins. `space` never sets
+  `StrictHostKeyChecking=no`.
+
+### Changed
+
+- **ssh clones never prompt.** Every network clone now runs the child with
+  `GIT_SSH_COMMAND` set to `<inherited GIT_SSH_COMMAND, or "ssh"> -o
+  BatchMode=yes` (options appended after an inherited value, assumed
+  ssh-compatible; git ignores the variable for https URLs), so host-key,
+  passphrase, and password prompts fail fast instead of hanging behind the
+  progress spinner. A failure containing `Host key verification failed`
+  surfaces guidance naming `--trust-host-key` and `known_hosts`; every other
+  failure surfaces the raw stderr as before.
+- **Idempotent `space repo add` / `space new -r`.** Re-adding an
+  already-tracked repo is a no-op success (`Already present: …`, no clone,
+  no new `space.yaml` entry), and an untracked destination that already
+  contains a `.git` directory is adopted — mise-trusted and registered with
+  no fetch (`Registered existing checkout: …`) — so the corrected rerun
+  after a partially-failed batch succeeds instead of erroring on the
+  orphaned destination. A destination without `.git` is still refused
+  (not-a-git-repository error), path/name collisions with a *different*
+  tracked repo still error, and registration remains all-or-nothing: any
+  fetch failure exits non-zero and registers nothing.
+
 ## [9.1.0] - 2026-10-10
 
 ### Added

data/README.md

@@ -16,244 +16,37 @@ evergreen checkouts spaces provision from).
 tool was absorbed into space-architect (up to 8.0.0) and is extracted back out
 here as of 9.0.0.
 
-## What's a space? 🪐
-
-A space is just a regular directory with a tiny YAML identity file and room for
-everything a task needs:
-
-```text
-~/architect/spaces/20260531-name-of-space/
-  space.yaml        # identity: id, title, status, repos, notes, tags
-  README.md
-  repos/            # cloned (or copy-on-write'd) repositories
-  notes/            # scratch, prompts, logs
-  architecture/     # project files when the space runs an Architect project
-  build/            # OCI contexts + scratch (build/oci/)
-  tmp/              # workspace-local temp — use this instead of /tmp
-```
-
-Run a command from anywhere inside a space and it just works — `space` walks up
-from `$PWD` until it finds the nearest `space.yaml`. No "current space" state
-to get out of sync; where you *are* is the space you mean. 🧭
-
 ## Installation 📦
 
-Add it to your `Gemfile`:
-
-```ruby
-gem "space-cadet"
-```
-
-```bash
-bundle install
-```
-
-Or grab it yourself:
-
-```bash
-gem install space-cadet
-```
-
-The gem is `space-cadet`; it installs one executable, `space`. 🎀
-
-## Quick start 🎀
-
-```sh
-space init                                        # create XDG config + state files
-space new "Name of Space"                         # blast off a new space 🚀
-space new "Name of Space" -r org/repo -r org/lib  # …with repos cloned in (repeat -r)
-space list                                        # see all your spaces
-space show                                        # show the space you're standing in
-
-# Containers (run from inside a space) — a portable, reproducible-by-SHA image of the space
-space pack                                         # render build/oci/ (Dockerfile + entrypoint)
-space build                                        # pack + build & tag <space-id>:<git-sha>
-space run                                          # run it — login shell, auth from your env
-```
-
-## Commands 🌌
-
-```sh
-space init
-space new "Name of Space"
-space new "Name of Space" -r org/repo -r example-tools/alpha -r example-tools/beta
-space list                                   # alias: space ls
-space show 20260531-name-of-space
-space path 20260531-name-of-space
-space current                                # based on $PWD
-space show                                   # based on $PWD
-space status                                 # report: metadata (+ project status when present)
-space status 20260531-name-of-space          # report another space
-space status done                            # set: active | paused | done | archived
-space status 20260531-name-of-space done
-space config set default_provider github.com
-space config set default_organization example-org
-space repo add example-app                   # github.com/example-org/example-app
-space repo add example-tools/alpha example-tools/beta
-space repo add gitlab.com/example-org/api
-space repo resolve example-app example-tools/async
-space repo ls                                # alias: space repos ls
-space use 20260531-name-of-space             # records recent state, prints the path
-space ls --color=always                      # auto | always | never (--colors also accepted)
-```
-
-`space status` is **report-or-set**: with no status keyword (bare, or with just
-a space id) it *reports* the space — its metadata plus a compact project-status
-block when the space declares one, quietly omitted otherwise; pass a status
-keyword (`active`, `paused`, `done`, `archived`) to *set* it instead. 🔁
-
-Repos are passed with a repeatable `-r` flag (`-r org/repo -r org/lib`); the
-comma form (`-r a,b`) works too. Space ids are date-prefixed
-(`20260531-name-of-space`) so they sort naturally, and duplicate names on the
-same day get a counter (`…-name-of-space-2`). 📅
-
-Full command reference: [docs/reference.md](docs/reference.md).
-
-## Containerize a space: `pack` · `build` · `run` 📦
-
-A space is self-describing enough to become a container. `space pack` renders a
-portable OCI build context from the space; `space build` packs and builds it into
-a **reproducible-by-SHA** image; `space run` runs that image with your auth
-injected at runtime and stateful paths bind-mounted back to the host. 🐳
-
 ```sh
-space pack                    # render build/oci/ (Dockerfile + entrypoint + ignore file)
-space pack -o /tmp/ctx        # …to a different output directory
-space build                   # pack, then build & tag <space-id>:<git-sha> and :latest
-space run                     # run <space-id>:latest — login shell, auth from your env
-space run architect status    # …or run a one-off command instead of the login shell
-space run --tty               # force an interactive TTY (default: auto-detect)
-```
-
-**What lands in the image.** The context copies the whole space tree (filtered by
-a generated `Dockerfile.dockerignore`) onto a `ruby:4.0.5` base with `git`, the
-Claude Code CLI, and the `space-cadet` gem — installed from the in-space
-`repos/space-cadet` checkout when present (a pinned build), else from
-RubyGems. Secrets never enter the layers: `.env`, `*.key`, `*.pem`, ssh keys,
-`build/`, and `tmp/` are all excluded by the generated ignore file. 🔒
-
-**Reproducible by SHA.** `space build` tags the image `<space-id>:<sha>`, where
-`<sha>` is the space repo's 12-char `HEAD` (suffixed `-dirty` when the tree has
-uncommitted changes), plus a moving `:latest`. Same commit → same tag → same
-image. It drives the `container` CLI, but the output is an ordinary OCI/Docker
-build context, so `docker build -f build/oci/Dockerfile .` (from the space root)
-works just as well.
-
-**Auth stays out of the layers.** `space run` injects only the auth environment
-variables that are actually set — `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`,
-`ANTHROPIC_BASE_URL` — with `-e` at run time, so credentials live in your shell,
-never in the image. 🗝️
-
-**Forwarding payload credentials.** Beyond the always-on auth trio, a space can declare
-`run.env:` in `space.yaml` — a list of host env var names forwarded into the container at
-run time. You can also pass `space run --env VAR` (repeatable) for ad hoc additions. All
-forwarding is bare `-e VAR` passthrough: values never appear in argv, `ps`, or the image.
-A requested-but-unset var warns on stderr instead of silently failing inside the guest.
-
-```yaml
-run:
-  env:                         # run-time: host var names, forwarded as bare -e VAR
-    - FIREWORKS_API_KEY
-    - OPENAI_API_KEY
-```
-
-**Declaring provisioning & persistence** — two optional keys in `space.yaml`:
-
-```yaml
-pack:
-  provision:                 # build-time: relative scripts, baked in by `space build`
-    - scripts/setup-toolchain.sh
-  persist:                   # run-time: absolute guest paths, bind-mounted per run
-    - /root/.claude
-    - /root/.local/state
-```
-
-`provision` scripts must live under the space root and be executable. Each script is
-copied into the image individually (`COPY <script> /space/<script>`) and then invoked
-(`RUN /space/<script>`) **before** the full space tree lands and **before** the gem is
-installed. This ordering is the cache-hygiene guarantee: editing any other space file
-leaves the provision and gem-install layers cached, so a rebuild completes in seconds
-instead of minutes. Scripts must therefore be self-contained — they run with only the
-base system layers and any earlier provision scripts' outputs; they cannot read other
-space files or call `space`. Scripts must have the executable bit set; COPY preserves
-the mode from the build context.
-
-`persist` paths must be absolute; `space run` bind-mounts each one from
-`<space>/.state<path>` on the host (created on first run) so a container's mutable state
-survives across runs. Both are validated at pack time.
-
-## Fish shell integration 🐟
-
-Shells can't let a child process change *their* working directory, so `space`
-ships a small fish wrapper function plus completions (commands, subcommands,
-spaces, statuses, config keys, repo refs). Install into fish's autoloaded
-directories:
-
-```fish
-space shell fish install
-exec fish
-```
-
-After restarting fish (or `exec fish`), `space new "…"` and
-`space use <id>` will `cd` into the selected space once the command succeeds;
-every other command keeps normal CLI behavior. 🚪 The functions and completions
-are written under `~/.config/fish/`, so there's no need to edit `config.fish`.
-For one-off testing without installing:
-
-```fish
-space shell init fish | source
-```
-
-## Configuration ⚙️
-
-Config lives at `~/.config/space-cadet/config.yml` (XDG-aware) and defaults to:
-
-```yaml
-version: 1
-base_dir: ~/architect            # spaces_dir + src_dir hang off this by default
-default_provider: github.com
-default_organization:
-git_clone_protocol: ssh          # ssh | https
+gem install space-cadet
 ```
 
-Derived defaults: `spaces_dir` → `<base_dir>/spaces`, `src_dir` (evergreen
-checkout root) → `<base_dir>/src`. Override either explicitly. View values with
-`space config show`; set one with `space config set KEY VALUE`. Editable keys:
-`base_dir`, `spaces_dir`, `src_dir`, `default_provider`, `default_organization`,
-`git_clone_protocol`.
+or add `gem "space-cadet"` to your `Gemfile` and `bundle install`. The gem
+installs one executable, `space`. 🎀
 
-## Repos: evergreen, copy-on-write, concurrent ⚡
-
-Repos are added to the current space under `repos/` and tracked in `space.yaml`.
-When an up-to-date evergreen checkout exists at
-`<src_dir>/<host>/<owner>/<name>` (e.g.
-`~/architect/src/github.com/example-org/example-app` — tended by
-[jetpks/repo-tender](https://github.com/jetpks/repo-tender)), `space` copies it
-into the space instead of cloning over the network — a copy-on-write clone on
-APFS. ⚡ Set `src_dir` empty to always clone:
+## 60-second start 🚀
 
 ```sh
-space config set src_dir ""
+space init                          # create XDG config + state files
+space new "My First Space"          # blast off a new space 🪐
+cd ~/architect/spaces/*my-first-space
+space status                        # report where you are
 ```
 
-Clone URLs default to SSH (`git@github.com:example-org/example-app.git`); switch
-with `space config set git_clone_protocol https`. Multiple repos passed to
-`space repo add` are fetched **concurrently**, up to five at a time, on fibers —
-no threads, all cooperative. 🧵 After each repo lands, `space` runs `mise trust`
-in it. Each space also gets a workspace-local `tmp/` — use it instead of `/tmp`.
-
-## Embedding 📚
-
-```ruby
-require "space_core"       # config, state, XDG, terminal, git/mise clients,
-                           # the space store — the `space` CLI runs on this alone
-```
+Full learning journey: [your first space](docs/tutorials/first-space.md).
 
 ## Documentation 📖
 
-- **[Command Reference](docs/reference.md)** — every command, flag, and behavior
-- **[Releasing](docs/RELEASING.md)** — how a release lands
-- **[Changelog](CHANGELOG.md)** — release history
+Organized by [Diátaxis](https://diataxis.fr/) — pick the quadrant that matches
+what you're here for:
+
+| I want to… | Go to |
+|---|---|
+| **learn** the tool step by step | [Tutorials](docs/tutorials/) |
+| **get something done** (a recipe) | [How-to guides](docs/how-to/) |
+| **look up** a command, flag, or path | [Reference](docs/reference/) |
+| **understand** why it works this way | [Explanation](docs/explanation/) |
 
 ## Development 🛠️
 

data/lib/space_core/cli/helpers.rb

@@ -5,6 +5,30 @@ require "dry/monads"
 module Space::Core::CLI
 module Helpers
   include Dry::Monads[:result]
+
+  # Printed before any fetch when --trust-host-key is set. The operator
+  # should see the TOFU semantics at flag time — deterministic and
+  # locale-independent — rather than via ssh's own "Permanently added …"
+  # stderr line, which would need locale-fragile scraping to relay.
+  TRUST_HOST_KEY_WARNING =
+    "Warning: trusting unknown host keys on first contact (--trust-host-key); changed keys still fail verification."
+
+  def warn_trust_host_key
+    terminal.error TRUST_HOST_KEY_WARNING
+  end
+
+  # One success line per repo-addition outcome. `Added <full_name>` keeps
+  # its exact historical shape (existing tests assert it); the other two
+  # make idempotent adds visible — what was fetched vs skipped vs adopted.
+  def repo_addition_line(result)
+    full_name = result.fetch(:repo).fetch("full_name")
+    case result.fetch(:outcome)
+    when :present then "Already present: #{full_name}"
+    when :adopted then "Registered existing checkout: #{full_name}"
+    else "Added #{full_name}"
+    end
+  end
+
   def project_config
     @project_config ||= Space::Core::Config.load
   end
@@ -67,9 +91,22 @@ class RepoProgress
     @statuses = {}
   end
 
+  # No fetch happens for an :adopted addition (its checkout is already on
+  # disk) — label it adopting, never cloning/copying. :present additions
+  # never start at all; they are marked done up front via #skip.
   def start(addition)
-    source = addition[:src_source]
-    @statuses[addition.fetch(:reference).full_name] = source&.directory? ? :copying : :cloning
+    repo = addition.fetch(:reference).full_name
+    case addition.fetch(:outcome, :added)
+    when :adopted
+      @statuses[repo] = :adopting
+    else
+      source = addition[:src_source]
+      @statuses[repo] = source&.directory? ? :copying : :cloning
+    end
+  end
+
+  def skip(addition)
+    @statuses[addition.fetch(:reference).full_name] = :done
   end
 
   def trust(addition)
@@ -89,14 +126,17 @@ class RepoProgress
     failed = @statuses.count { |_repo, status| status == :failed }
     copying = @statuses.select { |_repo, status| status == :copying }.keys
     cloning = @statuses.select { |_repo, status| status == :cloning }.keys
+    adopting = @statuses.select { |_repo, status| status == :adopting }.keys
     trusting = @statuses.select { |_repo, status| status == :trusting }.keys
 
     if @total == 1
       copying_repo = copying.first
       cloning_repo = cloning.first
+      adopting_repo = adopting.first
       trusting_repo = trusting.first
       return "Copying #{copying_repo}" if copying_repo
       return "Cloning #{cloning_repo}" if cloning_repo
+      return "Adopting #{adopting_repo}" if adopting_repo
       return "Trusting #{trusting_repo}" if trusting_repo
       return "Fetch failed" if failed.positive?
 
@@ -105,6 +145,7 @@ class RepoProgress
       active = []
       active << "copying #{copying.join(', ')}" unless copying.empty?
       active << "cloning #{cloning.join(', ')}" unless cloning.empty?
+      active << "adopting #{adopting.join(', ')}" unless adopting.empty?
       active << "trusting #{trusting.join(', ')}" unless trusting.empty?
       suffix = active.empty? ? nil : ": #{active.join('; ')}"
       failed_text = failed.positive? ? ", #{failed} failed" : ""

data/lib/space_core/cli/new.rb

@@ -6,9 +6,11 @@ class New < BaseCommand
   argument :title, required: true, desc: "Space title"
   option :repo, type: :array, aliases: ["-r"], desc: "Repo ref to clone (repeatable: pass -r once per repo)"
   option :git, type: :boolean, default: true, desc: "Initialize the space as a Git repository (use --no-git to skip)"
+  option :trust_host_key, type: :boolean, default: false,
+                          desc: "Accept unknown ssh host keys on first contact (changed keys still fail)"
   example "\"My Space\" -r org/repo -r example-tools/alpha   # clone two repos into the space"
 
-  def call(title:, repo: [], git: true, **opts)
+  def call(title:, repo: [], git: true, trust_host_key: false, **opts)
     setup_terminal(**opts.slice(:color, :colors))
     result = store.create(title, git: git).bind do |space|
       terminal.success "Created #{space.id}"
@@ -18,12 +20,15 @@ class New < BaseCommand
 
       next Success(space) if repo_specs.empty?
 
+      warn_trust_host_key if trust_host_key
       progress = RepoProgress.new(repo_specs.length)
       terminal.with_spinner(-> { progress.message }) do
-        store.add_repos_to(space, repo_specs, reporter: progress)
+        store.add_repos_to(space, repo_specs,
+                           scm: Space::Core::SCM::Git.new(trust_host_key: trust_host_key),
+                           reporter: progress)
       end.fmap do |results|
         results.each do |r|
-          terminal.success "Added #{r.fetch(:repo).fetch('full_name')}"
+          terminal.success repo_addition_line(r)
           terminal.say terminal.path(r.fetch(:path))
         end
         space

data/lib/space_core/cli/repo.rb

@@ -5,8 +5,10 @@ module Repo
   class Add < BaseCommand
     desc "Add repos to the current space (copy-on-write from an evergreen checkout when available, else clone)"
     argument :repos, type: :array, required: false, desc: "REPO [REPO...]"
+    option :trust_host_key, type: :boolean, default: false,
+                            desc: "Accept unknown ssh host keys on first contact (changed keys still fail)"
 
-    def call(repos: [], **opts)
+    def call(repos: [], trust_host_key: false, **opts)
       setup_terminal(**opts.slice(:color, :colors))
       handle_errors do
         specs = Array(repos).compact
@@ -16,13 +18,14 @@ module Repo
           next
         end
 
+        warn_trust_host_key if trust_host_key
         progress = RepoProgress.new(specs.length)
         add_result = terminal.with_spinner(-> { progress.message }) do
-          store.add_repos(specs, reporter: progress)
+          store.add_repos(specs, scm: Space::Core::SCM::Git.new(trust_host_key: trust_host_key), reporter: progress)
         end
         render(add_result) do |results|
           results.each do |result|
-            terminal.success "Added #{result.fetch(:repo).fetch('full_name')}"
+            terminal.success repo_addition_line(result)
             terminal.say terminal.path(result.fetch(:path))
           end
           CLI.record_outcome(Outcome.new(exit_code: 0))

data/lib/space_core/scm/git.rb

@@ -11,6 +11,17 @@ module Space::Core
     # Git CLI implementation of SCM::Client. All subprocess work is
     # delegated to Shell.run (which requires an ambient Async::Task).
     class Git < Client
+      # trust_host_key: append `-o StrictHostKeyChecking=accept-new` to the
+      # ssh command clones run under (TOFU: first-contact host keys are
+      # accepted automatically, changed keys still fail verification). The
+      # default (false) keeps strict host key checking. Host key
+      # verification is never disabled outright — the operator's "just
+      # disable it" urge is met with the strictly safer accept-new shape,
+      # opt-in only.
+      def initialize(trust_host_key: false)
+        @trust_host_key = trust_host_key
+      end
+
       # Resolve the bare remote's HEAD. First try the local
       # `origin/HEAD` symbolic ref; if missing/stale, do a one-shot
       # `git remote set-head origin -a` (network) to refresh it, then
@@ -107,10 +118,18 @@ module Space::Core
         Dry::Monads::Success(parsed)
       end
 
+      # Every clone runs ssh non-interactively. Open3.capture3 drains the
+      # child's stdout/stderr pipes, but ssh opens the controlling terminal
+      # (/dev/tty) directly for its host-key/passphrase/password prompts, so
+      # without BatchMode=yes a first-contact ssh clone hangs forever behind
+      # the CLI spinner. GIT_SSH_COMMAND makes every ssh prompt fail fast
+      # instead; git ignores it for https URLs, so it is set unconditionally
+      # — no URL-scheme conditional. An inherited GIT_SSH_COMMAND is honored
+      # with our options appended after it (assumed ssh-compatible).
       def clone(url, dest)
         parent = File.dirname(dest)
         FileUtils.mkdir_p(parent)
-        result = Shell.run("git", "clone", url, dest)
+        result = Shell.run("git", "clone", url, dest, env: {"GIT_SSH_COMMAND" => git_ssh_command})
         if result.success?
           Dry::Monads::Success(dest)
         else
@@ -165,6 +184,15 @@ module Space::Core
 
       private
 
+      # Computed at clone time from the in-process ENV so callers may set
+      # GIT_SSH_COMMAND after this SCM was constructed. An unset or blank
+      # inherited value degrades to plain "ssh".
+      def git_ssh_command
+        base = ENV["GIT_SSH_COMMAND"].to_s.strip.empty? ? "ssh" : ENV["GIT_SSH_COMMAND"]
+        trust_args = @trust_host_key ? ["-o", "StrictHostKeyChecking=accept-new"] : []
+        [base, "-o", "BatchMode=yes", *trust_args].join(" ")
+      end
+
       # `git symbolic-ref --short refs/remotes/origin/HEAD` returns
       # `origin/<branch>` (the short form of `refs/remotes/origin/<branch>`);
       # callers want the bare branch name. Returns nil when origin/HEAD

data/lib/space_core/space_store.rb

@@ -122,16 +122,22 @@ module Space::Core
 
     def add_repos_to(space, specs, scm: SCM::Git.new, cloner: nil, mise_client: MiseClient.new, reporter: nil)
       additions = prepare_repo_additions(space, specs)
+      # :present additions (already tracked) do no work at all; mark them
+      # done for the reporter so progress counts every spec without ever
+      # claiming a fetch for one.
+      additions.each { |addition| reporter&.skip(addition) if addition.fetch(:outcome) == :present }
       first_error = nil
 
       Async do |task|
         semaphore = Async::Semaphore.new(MAX_CONCURRENT_CLONES, parent: task)
 
         clone_tasks = additions.map do |addition|
+          next if addition.fetch(:outcome) == :present
+
           semaphore.async(finished: false) do
             clone_addition(addition, scm:, cloner:, mise_client:, reporter:)
           end
-        end
+        end.compact
 
         # Collect results without raising inside the reactor so the outer task
         # succeeds and async does not log "Task may have ended" for our errors.
@@ -145,8 +151,16 @@ module Space::Core
       return Failure(first_error) if first_error
 
       Success(additions.map do |addition|
-        repo_data = space.add_repo(addition.fetch(:reference), relative_path: addition.fetch(:relative_path), now: now.call)
-        { space: space, repo: repo_data, reference: addition.fetch(:reference), path: addition.fetch(:path) }
+        outcome = addition.fetch(:outcome)
+        repo_data =
+          if outcome == :present
+            # Already tracked: report the existing entry as-is — registration
+            # is not re-run (Space#add_repo's guard would rightly refuse).
+            addition.fetch(:existing_repo)
+          else
+            space.add_repo(addition.fetch(:reference), relative_path: addition.fetch(:relative_path), now: now.call)
+          end
+        { space: space, repo: repo_data, reference: addition.fetch(:reference), path: addition.fetch(:path), outcome: outcome }
       end)
     rescue Error => e
       Failure(e)
@@ -160,7 +174,9 @@ module Space::Core
 
     def clone_addition(addition, scm:, cloner:, mise_client:, reporter: nil)
       reporter&.start(addition)
-      fetch_addition(addition, scm:, cloner:)
+      # :adopted checkouts are already on disk — no fetch of any kind (no
+      # scm.clone, no Cloner call); only trust + registration remain.
+      fetch_addition(addition, scm:, cloner:) unless addition.fetch(:outcome) == :adopted
       reporter&.trust(addition)
       mise_client.trust(addition.fetch(:path))
       reporter&.finish(addition)
@@ -183,7 +199,19 @@ module Space::Core
         raise GitError, "clone failed (copy): #{result.failure}" if result.failure?
       else
         result = scm.clone(reference.clone_url, destination.to_s)
-        raise GitError, "clone failed: #{result.failure[:stderr]}" if result.failure?
+        return if result.success?
+
+        stderr = result.failure[:stderr]
+        message = "clone failed: #{stderr}"
+        # OpenSSH does not localize "Host key verification failed", so it is
+        # a stable trigger. Any other failure surfaces the raw stderr as
+        # before — fail-fast without a forward path is a support ticket, so
+        # teach the flag right where the operator will be looking.
+        if stderr.to_s.include?("Host key verification failed")
+          message += "\nHost key not in known_hosts; re-run with --trust-host-key to accept it on first contact, " \
+                     "or add it to your known_hosts manually."
+        end
+        raise GitError, message
       end
     end
 
@@ -194,13 +222,15 @@ module Space::Core
         relative_path = Pathname.new("repos").join(reference.directory_name)
         destination = space.path.join(relative_path)
 
-        ensure_repo_can_be_added!(space, reference, relative_path, destination)
+        outcome, existing_repo = ensure_repo_can_be_added!(space, reference, relative_path, destination)
 
         {
           reference: reference,
           relative_path: relative_path,
           path: destination,
-          src_source: src_dir && reference.src_path(src_dir)
+          src_source: src_dir && reference.src_path(src_dir),
+          outcome: outcome,
+          existing_repo: existing_repo
         }
       end
 
@@ -216,17 +246,36 @@ module Space::Core
       additions
     end
 
+    # Classify one resolved spec for the idempotent-add contract:
+    #   :added   — fetch (COW copy when an evergreen src exists, else
+    #              clone), then trust, then register (today's path);
+    #   :present — same full_name already tracked: skip fetch, trust, and
+    #              registration entirely (no-op success, whether or not the
+    #              directory is on disk — tracked ⇒ skip);
+    #   :adopted — destination exists on disk with .git, untracked: trust +
+    #              register, NO fetch (heals the orphaned checkouts a failed
+    #              batch leaves behind).
+    # Refusals (RepoExistsError): a tracked repo matching on path or name
+    # with a DIFFERENT full_name is a conflict, not idempotency, and a
+    # destination that exists without .git is not ours to register.
     def ensure_repo_can_be_added!(space, reference, relative_path, destination)
-      raise RepoExistsError, "Repo destination already exists: #{destination}" if destination.exist?
+      existing = space.repos.find { |repo| repo["full_name"] == reference.full_name }
+      return :present, existing if existing
+
+      conflicting = space.repos.find do |repo|
+        repo["path"] == relative_path.to_s || repo["name"] == reference.name
+      end
+      raise RepoExistsError, "Repo '#{reference.full_name}' already exists in #{space.id}" if conflicting
+
+      if destination.exist?
+        unless destination.join(".git").exist?
+          raise RepoExistsError, "Repo destination already exists and is not a git repository: #{destination}"
+        end
 
-      existing = space.repos.find do |repo|
-        repo["full_name"] == reference.full_name ||
-          repo["path"] == relative_path.to_s ||
-          repo["name"] == reference.name
+        return :adopted, nil
       end
-      return unless existing
 
-      raise RepoExistsError, "Repo '#{reference.full_name}' already exists in #{space.id}"
+      [:added, nil]
     end
 
     def metadata_for(id:, title:, timestamp:)

data/lib/space_core/version.rb

@@ -2,6 +2,6 @@
 
 module Space
   module Core
-    VERSION = "9.1.0"
+    VERSION = "9.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-cadet
 version: !ruby/object:Gem::Version
-  version: 9.1.0
+  version: 9.2.0
 platform: ruby
 authors:
 - Eric Jacobs