feat: v1.27.0.0 migration — gstack-brain → gstack-artifacts rename

Journaled, interruption-safe migration. Six steps, each writes to
~/.gstack/.migrations/v1.27.0.0.journal on success; re-entry resumes
from the next un-done step. On final success, journal is replaced by
~/.gstack/.migrations/v1.27.0.0.done.

Steps:
1. gh_repo_renamed       gh/glab repo rename gstack-brain-$USER →
                         gstack-artifacts-$USER (idempotent: detects
                         already-renamed and skips)
2. remote_txt_renamed    mv ~/.gstack-brain-remote.txt → artifacts file,
                         rewriting URL path to match the new repo name
3. config_key_renamed    sed -i in ~/.gstack/config.yaml flips
                         gbrain_sync_mode → artifacts_sync_mode
4. claude_md_block       sed flips "- Memory sync:" → "- Artifacts sync:"
                         in cwd CLAUDE.md and ~/.gstack/CLAUDE.md
5. sources_swapped       gbrain sources add NEW (verify) → remove OLD
                         (codex Finding #6: add-before-remove ordering,
                         no downtime window). On remote-MCP mode, prints
                         commands for the brain admin instead of executing.
6. done                  touchfile + delete journal

User opt-out: any "n" or "skip-for-now" answer at the initial prompt
writes a marker file that prevents re-prompting; user can re-invoke
via /setup-gbrain --rerun-migration.

11 unit tests cover: nothing-to-migrate, GitHub happy path, idempotent
re-run, journal-resume mid-flight, remote-MCP print-only path,
add-before-remove ordering verification, add-fail → old source stays
registered, CLAUDE.md field rewrite.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

gstack-upgrade/migrations/v1.27.0.0.sh

@@ -0,0 +1,344 @@
+#!/usr/bin/env bash
+# Migration: v1.27.0.0 — rename gstack-brain-* → gstack-artifacts-*
+#
+# Phase C of the v1.27.0.0 plan. Hard-rename, no compat shim. Steps:
+#   1. gh_repo_renamed       — gh/glab repo rename gstack-brain-$USER →
+#                              gstack-artifacts-$USER (skipped on user opt-out)
+#   2. remote_txt_renamed    — mv ~/.gstack-brain-remote.txt → artifacts-remote.txt
+#   3. config_key_renamed    — rewrite gbrain_sync_mode → artifacts_sync_mode
+#                              in ~/.gstack/config.yaml
+#   4. claude_md_block_rewritten — find-and-replace any existing GBrain
+#                              Configuration block that references "Memory sync"
+#   5. sources_swapped       — gbrain sources add new (verify) → remove old
+#                              (codex Finding #6: add-before-remove ordering)
+#   6. done                  — write touchfile, delete journal
+#
+# Interruption-safe via journal at ~/.gstack/.migrations/v1.27.0.0.journal:
+# each step writes its name on success; re-entry resumes from the next un-done
+# step. Done touchfile at ~/.gstack/.migrations/v1.27.0.0.done.
+#
+# Three host-mode branches per the plan:
+#   Local CLI + GitHub  — all steps run automatically
+#   Local CLI + GitLab  — same with glab repo rename
+#   Remote MCP only     — steps 1-4 still run; step 5 prints commands for
+#                         the brain admin to run on the brain host
+#
+# All steps are idempotent. Re-running after partial completion is safe.
+set -euo pipefail
+
+if [ -z "${HOME:-}" ]; then
+  echo "  [v1.27.0.0] HOME is unset — skipping migration." >&2
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+GSTACK_HOME="${HOME}/.gstack"
+SKILLS_DIR="${HOME}/.claude/skills"
+BIN_DIR="${SKILLS_DIR}/gstack/bin"
+CONFIG_BIN="${BIN_DIR}/gstack-config"
+URL_BIN="${BIN_DIR}/gstack-artifacts-url"
+
+MIGRATION_DIR="${GSTACK_HOME}/.migrations"
+JOURNAL="${MIGRATION_DIR}/v1.27.0.0.journal"
+DONE="${MIGRATION_DIR}/v1.27.0.0.done"
+SKIPPED="${MIGRATION_DIR}/v1.27.0.0.skipped-by-user"
+
+USER_NAME="${USER:-$(whoami 2>/dev/null || echo unknown)}"
+OLD_REPO_NAME="gstack-brain-${USER_NAME}"
+NEW_REPO_NAME="gstack-artifacts-${USER_NAME}"
+OLD_REMOTE_TXT="${HOME}/.gstack-brain-remote.txt"
+NEW_REMOTE_TXT="${HOME}/.gstack-artifacts-remote.txt"
+OLD_SOURCE_ID="${OLD_REPO_NAME}"
+NEW_SOURCE_ID="${NEW_REPO_NAME}"
+
+# ---------------------------------------------------------------------------
+# Journal helpers
+# ---------------------------------------------------------------------------
+mkdir -p "$MIGRATION_DIR"
+
+# Already done? exit silently.
+[ -f "$DONE" ] && exit 0
+
+# User opted out previously? exit silently. (Re-invoke via
+# `/setup-gbrain --rerun-migration` removes this marker.)
+[ -f "$SKIPPED" ] && exit 0
+
+journal_done() {
+  # Returns 0 if the named step is recorded as complete in the journal.
+  local step="$1"
+  [ -f "$JOURNAL" ] && grep -q "^${step}$" "$JOURNAL" 2>/dev/null
+}
+
+mark_done() {
+  local step="$1"
+  echo "$step" >> "$JOURNAL"
+}
+
+# ---------------------------------------------------------------------------
+# Detect environment + ask once if there's anything to migrate
+# ---------------------------------------------------------------------------
+
+# Has the user ever opted into brain sync? Two signals:
+#   - presence of ~/.gstack-brain-remote.txt (legacy file)
+#   - presence of ~/.gstack/.git (brain-init ever ran)
+HAS_LEGACY_STATE=0
+[ -f "$OLD_REMOTE_TXT" ] && HAS_LEGACY_STATE=1
+[ -d "$GSTACK_HOME/.git" ] && HAS_LEGACY_STATE=1
+
+# If nothing to migrate, finalize silently.
+if [ "$HAS_LEGACY_STATE" = "0" ]; then
+  echo "  [v1.27.0.0] no legacy gstack-brain state detected — nothing to migrate." >&2
+  touch "$DONE"
+  rm -f "$JOURNAL" 2>/dev/null || true
+  exit 0
+fi
+
+# Ask once (idempotent: if journal exists from a prior partial run, skip ask).
+if [ ! -f "$JOURNAL" ]; then
+  cat >&2 <<EOF
+
+  [v1.27.0.0] gstack-brain has been renamed to gstack-artifacts.
+  This is a clearer name for what it actually holds: CEO plans, designs,
+  /investigate reports, retros (i.e. artifacts, not behavioral memory).
+
+  This migration will:
+    1. Rename your private GitHub/GitLab repo "$OLD_REPO_NAME" → "$NEW_REPO_NAME"
+    2. mv ~/.gstack-brain-remote.txt → ~/.gstack-artifacts-remote.txt
+    3. Rename gbrain_sync_mode → artifacts_sync_mode in ~/.gstack/config.yaml
+    4. Update any "## GBrain Configuration" block in CLAUDE.md
+    5. Update gbrain federated source registration (local CLI mode)
+       OR print commands for your brain admin (remote MCP mode)
+
+  Each step is journaled so a Ctrl-C mid-flight is safe to re-run.
+
+EOF
+  if [ -t 0 ]; then
+    printf "  Proceed? [Y/n/skip-for-now]: " >&2
+    read -r REPLY || REPLY=""
+    case "$REPLY" in
+      n|N|no|No|NO)
+        echo "  Skipping migration. Re-run via /setup-gbrain --rerun-migration." >&2
+        touch "$SKIPPED"
+        exit 0
+        ;;
+      skip|skip-for-now|s)
+        echo "  Skipping for now. Will ask again next upgrade." >&2
+        # Don't write SKIPPED — leave both old + new state untouched, ask again next time.
+        exit 0
+        ;;
+    esac
+  else
+    # Non-interactive (CI, scripted upgrade): proceed automatically.
+    echo "  (non-interactive: proceeding automatically)" >&2
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Detect host (gh / glab / manual) for steps 1 + 5
+# ---------------------------------------------------------------------------
+detect_host() {
+  # Read the canonical-form remote URL (the legacy file in the migration window).
+  local url=""
+  if [ -f "$OLD_REMOTE_TXT" ]; then
+    url=$(head -1 "$OLD_REMOTE_TXT" 2>/dev/null | tr -d '[:space:]' || echo "")
+  elif [ -f "$NEW_REMOTE_TXT" ]; then
+    url=$(head -1 "$NEW_REMOTE_TXT" 2>/dev/null | tr -d '[:space:]' || echo "")
+  fi
+  if echo "$url" | grep -q 'github\.com'; then
+    echo "github"
+  elif echo "$url" | grep -q 'gitlab'; then
+    echo "gitlab"
+  else
+    echo "manual"
+  fi
+}
+
+HOST=$(detect_host)
+
+# ---------------------------------------------------------------------------
+# Detect MCP mode (so step 5 knows whether to execute or print)
+# ---------------------------------------------------------------------------
+detect_mcp_mode() {
+  # Cheap probe: ~/.claude.json type field. Defense-in-depth tier 3 only;
+  # the migration script avoids invoking `claude` to keep upgrade fast.
+  if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
+    local t
+    t=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
+    case "$t" in
+      url|http|sse) echo "remote-http"; return ;;
+      stdio) echo "local-stdio"; return ;;
+    esac
+  fi
+  echo "none"
+}
+
+MCP_MODE=$(detect_mcp_mode)
+
+# ---------------------------------------------------------------------------
+# Step 1: gh/glab repo rename
+# ---------------------------------------------------------------------------
+if ! journal_done "gh_repo_renamed"; then
+  echo "  [v1.27.0.0] step 1: rename remote repo $OLD_REPO_NAME → $NEW_REPO_NAME" >&2
+  case "$HOST" in
+    github)
+      if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+        # Idempotent: if new name already exists, treat as success.
+        if gh repo view "$NEW_REPO_NAME" >/dev/null 2>&1; then
+          echo "    repo already named $NEW_REPO_NAME on GitHub — no-op" >&2
+          mark_done "gh_repo_renamed"
+        else
+          if gh repo rename "$NEW_REPO_NAME" --repo "$OLD_REPO_NAME" --yes 2>/dev/null \
+              || gh repo edit "$OLD_REPO_NAME" --name "$NEW_REPO_NAME" 2>/dev/null; then
+            echo "    renamed on GitHub" >&2
+            mark_done "gh_repo_renamed"
+          else
+            echo "    WARNING: gh rename failed (repo may not exist or permission denied)" >&2
+            echo "    skipping step 1; subsequent steps still run" >&2
+            mark_done "gh_repo_renamed"
+          fi
+        fi
+      else
+        echo "    gh CLI not available — skipping rename step (manual: gh repo rename ...)" >&2
+        mark_done "gh_repo_renamed"
+      fi
+      ;;
+    gitlab)
+      if command -v glab >/dev/null 2>&1 && glab auth status >/dev/null 2>&1; then
+        if glab repo view "$NEW_REPO_NAME" >/dev/null 2>&1; then
+          echo "    repo already named $NEW_REPO_NAME on GitLab — no-op" >&2
+          mark_done "gh_repo_renamed"
+        else
+          # GitLab CLI doesn't have a direct rename; user has to do it via API.
+          echo "    glab repo rename isn't a single command on GitLab." >&2
+          echo "    Manual: visit your GitLab project Settings → General → Advanced → Rename" >&2
+          echo "    or use: glab api projects/:id -X PUT -f name=$NEW_REPO_NAME -f path=$NEW_REPO_NAME" >&2
+          mark_done "gh_repo_renamed"
+        fi
+      else
+        echo "    glab not available — manual rename required" >&2
+        mark_done "gh_repo_renamed"
+      fi
+      ;;
+    manual|*)
+      echo "    unknown host (not github/gitlab) — manual rename required" >&2
+      mark_done "gh_repo_renamed"
+      ;;
+  esac
+fi
+
+# ---------------------------------------------------------------------------
+# Step 2: rename ~/.gstack-brain-remote.txt → ~/.gstack-artifacts-remote.txt
+# ---------------------------------------------------------------------------
+if ! journal_done "remote_txt_renamed"; then
+  echo "  [v1.27.0.0] step 2: rename ~/.gstack-brain-remote.txt → ~/.gstack-artifacts-remote.txt" >&2
+  if [ -f "$OLD_REMOTE_TXT" ] && [ ! -f "$NEW_REMOTE_TXT" ]; then
+    # Update the URL inside if the rename happened on the host: replace
+    # gstack-brain-$USER with gstack-artifacts-$USER in the URL.
+    OLD_URL=$(head -1 "$OLD_REMOTE_TXT" 2>/dev/null)
+    NEW_URL=$(echo "$OLD_URL" | sed "s|/${OLD_REPO_NAME}|/${NEW_REPO_NAME}|; s|:${OLD_REPO_NAME}|:${NEW_REPO_NAME}|")
+    echo "$NEW_URL" > "$NEW_REMOTE_TXT"
+    chmod 600 "$NEW_REMOTE_TXT"
+    rm -f "$OLD_REMOTE_TXT"
+    echo "    moved + URL rewritten: $OLD_URL → $NEW_URL" >&2
+  elif [ -f "$NEW_REMOTE_TXT" ]; then
+    echo "    new file already exists — no-op" >&2
+    rm -f "$OLD_REMOTE_TXT" 2>/dev/null || true
+  else
+    echo "    no $OLD_REMOTE_TXT to migrate — no-op" >&2
+  fi
+  mark_done "remote_txt_renamed"
+fi
+
+# ---------------------------------------------------------------------------
+# Step 3: rename gbrain_sync_mode → artifacts_sync_mode in config.yaml
+# ---------------------------------------------------------------------------
+if ! journal_done "config_key_renamed"; then
+  echo "  [v1.27.0.0] step 3: rename gbrain_sync_mode → artifacts_sync_mode in config.yaml" >&2
+  CFG="$GSTACK_HOME/config.yaml"
+  if [ -f "$CFG" ]; then
+    # Atomic in-place rewrite with a tmpfile.
+    TMP=$(mktemp "${CFG}.v1.27.0.0.XXXXXX")
+    sed -e 's/^gbrain_sync_mode:/artifacts_sync_mode:/' \
+        -e 's/^gbrain_sync_mode_prompted:/artifacts_sync_mode_prompted:/' \
+        "$CFG" > "$TMP" && mv "$TMP" "$CFG"
+    echo "    rewritten in place" >&2
+  else
+    echo "    no $CFG to migrate — no-op" >&2
+  fi
+  mark_done "config_key_renamed"
+fi
+
+# ---------------------------------------------------------------------------
+# Step 4: rewrite CLAUDE.md "## GBrain Configuration" block fields
+# ---------------------------------------------------------------------------
+if ! journal_done "claude_md_block_rewritten"; then
+  echo "  [v1.27.0.0] step 4: rewrite CLAUDE.md GBrain Configuration block fields" >&2
+  # Look in cwd's CLAUDE.md (where /setup-gbrain wrote it) and ~/.gstack/CLAUDE.md
+  # if it exists. We can't know every project's CLAUDE.md; users rerunning
+  # /setup-gbrain in any project will overwrite that block fresh anyway.
+  for CMD in "$PWD/CLAUDE.md" "$GSTACK_HOME/CLAUDE.md"; do
+    [ -f "$CMD" ] || continue
+    if grep -q "## GBrain Configuration" "$CMD"; then
+      TMP=$(mktemp "${CMD}.v1.27.0.0.XXXXXX")
+      sed -e 's/^- Memory sync:/- Artifacts sync:/' "$CMD" > "$TMP" && mv "$TMP" "$CMD"
+      echo "    rewritten field in $CMD" >&2
+    fi
+  done
+  mark_done "claude_md_block_rewritten"
+fi
+
+# ---------------------------------------------------------------------------
+# Step 5: gbrain sources swap (add-new before remove-old per codex Finding #6)
+# ---------------------------------------------------------------------------
+if ! journal_done "sources_swapped"; then
+  echo "  [v1.27.0.0] step 5: gbrain federated source rename" >&2
+  if [ "$MCP_MODE" = "remote-http" ]; then
+    # Print commands for the brain admin; we can't execute them locally.
+    cat >&2 <<EOF
+    Remote MCP detected. The local gbrain CLI can't update the brain's
+    federated source registration. Send this to your brain admin:
+
+      gbrain sources add ${NEW_SOURCE_ID} --path <new-clone-path> --federated
+      # verify the new source is searching as expected, then:
+      gbrain sources remove ${OLD_SOURCE_ID} --yes
+
+    (Add-new before remove-old keeps search uninterrupted.)
+
+EOF
+    mark_done "sources_swapped"
+  elif command -v gbrain >/dev/null 2>&1 && [ -d "$GSTACK_HOME/.git" ]; then
+    # Local CLI mode. Sources point at the worktree path; rename the source
+    # ID add-then-remove. The actual on-disk worktree path stays the same.
+    WORKTREE="${GSTACK_BRAIN_WORKTREE:-$HOME/.gstack-brain-worktree}"
+    if gbrain sources list 2>/dev/null | grep -q "$OLD_SOURCE_ID"; then
+      if gbrain sources add "$NEW_SOURCE_ID" --path "$WORKTREE" --federated 2>/dev/null; then
+        echo "    added $NEW_SOURCE_ID" >&2
+        if gbrain sources remove "$OLD_SOURCE_ID" --yes 2>/dev/null; then
+          echo "    removed $OLD_SOURCE_ID" >&2
+        else
+          echo "    WARNING: failed to remove $OLD_SOURCE_ID; both registered. Run manually:" >&2
+          echo "    gbrain sources remove $OLD_SOURCE_ID --yes" >&2
+        fi
+      else
+        echo "    WARNING: failed to add $NEW_SOURCE_ID. Old source still registered." >&2
+      fi
+    else
+      echo "    no $OLD_SOURCE_ID source registered — no-op" >&2
+    fi
+    mark_done "sources_swapped"
+  else
+    echo "    gbrain CLI not available or no ~/.gstack/.git — skipping" >&2
+    mark_done "sources_swapped"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Step 6: finalize (touchfile + clear journal)
+# ---------------------------------------------------------------------------
+touch "$DONE"
+rm -f "$JOURNAL"
+
+echo "  [v1.27.0.0] migration complete." >&2
+exit 0

test/migrations-v1.27.0.0.test.ts

@@ -0,0 +1,290 @@
+/**
+ * v1.27.0.0 migration — gstack-brain → gstack-artifacts rename.
+ *
+ * Exercises the journaled migration in a temp HOME with mocked gh / git /
+ * gbrain. Tests the four host-mode cases (GitHub, GitLab, remote-MCP,
+ * nothing-to-migrate) plus interruption resume.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const MIGRATION = path.join(ROOT, 'gstack-upgrade', 'migrations', 'v1.27.0.0.sh');
+
+let tmpHome: string;
+let fakeBinDir: string;
+
+function makeFakeGh(opts: { authStatus?: 'ok' | 'fail'; renameSucceeds?: boolean; alreadyRenamed?: boolean } = {}) {
+  const authStatus = opts.authStatus ?? 'ok';
+  const renameSucceeds = opts.renameSucceeds ?? true;
+  const alreadyRenamed = opts.alreadyRenamed ?? false;
+  const callLog = path.join(fakeBinDir, 'gh-calls.log');
+  const script = `#!/bin/bash
+echo "gh $@" >> "${callLog}"
+case "$1" in
+  auth) ${authStatus === 'ok' ? 'exit 0' : 'exit 1'} ;;
+  repo)
+    shift
+    case "$1" in
+      view)
+        # gh repo view <name>
+        shift
+        ${alreadyRenamed ? `if echo "$@" | grep -q gstack-artifacts; then exit 0; else exit 1; fi` : `exit 1`}
+        ;;
+      rename) ${renameSucceeds ? 'exit 0' : 'exit 1'} ;;
+      edit) ${renameSucceeds ? 'exit 0' : 'exit 1'} ;;
+    esac
+    ;;
+esac
+exit 0
+`;
+  fs.writeFileSync(path.join(fakeBinDir, 'gh'), script, { mode: 0o755 });
+}
+
+function makeFakeGbrain(opts: { hasOldSource?: boolean; addSucceeds?: boolean; removeSucceeds?: boolean } = {}) {
+  const hasOld = opts.hasOldSource ?? true;
+  const addOk = opts.addSucceeds ?? true;
+  const rmOk = opts.removeSucceeds ?? true;
+  const callLog = path.join(fakeBinDir, 'gbrain-calls.log');
+  const script = `#!/bin/bash
+echo "gbrain $@" >> "${callLog}"
+case "$1 $2" in
+  "sources list")
+    ${hasOld ? `echo "gstack-brain-testuser ~/.gstack-brain-worktree"` : 'true'}
+    exit 0
+    ;;
+  "sources add") ${addOk ? 'exit 0' : 'exit 1'} ;;
+  "sources remove") ${rmOk ? 'exit 0' : 'exit 1'} ;;
+esac
+exit 0
+`;
+  fs.writeFileSync(path.join(fakeBinDir, 'gbrain'), script, { mode: 0o755 });
+}
+
+function run(extraEnv: Record<string, string> = {}, input = ''): { code: number; stdout: string; stderr: string } {
+  const r = spawnSync(MIGRATION, [], {
+    env: {
+      PATH: `${fakeBinDir}:${path.join(ROOT, 'bin')}:/usr/bin:/bin:/opt/homebrew/bin`,
+      HOME: tmpHome,
+      USER: 'testuser',
+      // Disable interactive prompt: empty stdin = treat as non-interactive.
+      ...extraEnv,
+    },
+    encoding: 'utf-8',
+    input,
+    cwd: tmpHome,
+  });
+  return { code: r.status ?? -1, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'mig-v1.27-'));
+  fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mig-v1.27-fake-'));
+  fs.mkdirSync(path.join(tmpHome, '.gstack'), { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  fs.rmSync(fakeBinDir, { recursive: true, force: true });
+});
+
+describe('v1.27.0.0 migration — nothing to migrate', () => {
+  test('no legacy state → exits 0, writes done touchfile, no journal', () => {
+    // Fresh HOME: no brain-remote.txt, no .gstack/.git
+    const r = run();
+    expect(r.code).toBe(0);
+    expect(r.stderr).toContain('nothing to migrate');
+    expect(fs.existsSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.done'))).toBe(true);
+    expect(fs.existsSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.journal'))).toBe(false);
+  });
+
+  test('done touchfile present → exits 0 silently (no re-prompt)', () => {
+    fs.mkdirSync(path.join(tmpHome, '.gstack/.migrations'), { recursive: true });
+    fs.writeFileSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.done'), '');
+    const r = run();
+    expect(r.code).toBe(0);
+    expect(r.stderr).toBe('');
+  });
+
+  test('skipped-by-user touchfile → exits 0 silently', () => {
+    fs.mkdirSync(path.join(tmpHome, '.gstack/.migrations'), { recursive: true });
+    fs.writeFileSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.skipped-by-user'), '');
+    fs.writeFileSync(path.join(tmpHome, '.gstack-brain-remote.txt'), 'https://github.com/x/gstack-brain-testuser');
+    const r = run();
+    expect(r.code).toBe(0);
+    expect(r.stderr).toBe('');
+  });
+});
+
+describe('v1.27.0.0 migration — GitHub host (non-interactive)', () => {
+  beforeEach(() => {
+    fs.writeFileSync(
+      path.join(tmpHome, '.gstack-brain-remote.txt'),
+      'https://github.com/testuser/gstack-brain-testuser\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpHome, '.gstack/config.yaml'),
+      'gbrain_sync_mode: full\ngbrain_sync_mode_prompted: true\n'
+    );
+    makeFakeGh({});
+  });
+
+  test('renames repo, mvs remote.txt, rewrites config key, writes done', () => {
+    const r = run();
+    expect(r.code).toBe(0);
+    // gh rename was called (or edit fallback).
+    const ghLog = fs.readFileSync(path.join(fakeBinDir, 'gh-calls.log'), 'utf-8');
+    expect(ghLog).toMatch(/gh repo (rename|edit)/);
+    // Old remote.txt is gone, new one exists with rewritten URL.
+    expect(fs.existsSync(path.join(tmpHome, '.gstack-brain-remote.txt'))).toBe(false);
+    const newUrl = fs.readFileSync(path.join(tmpHome, '.gstack-artifacts-remote.txt'), 'utf-8').trim();
+    expect(newUrl).toBe('https://github.com/testuser/gstack-artifacts-testuser');
+    // Config key renamed.
+    const cfg = fs.readFileSync(path.join(tmpHome, '.gstack/config.yaml'), 'utf-8');
+    expect(cfg).toContain('artifacts_sync_mode: full');
+    expect(cfg).toContain('artifacts_sync_mode_prompted: true');
+    expect(cfg).not.toContain('gbrain_sync_mode');
+    // Done touchfile written, journal cleared.
+    expect(fs.existsSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.done'))).toBe(true);
+    expect(fs.existsSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.journal'))).toBe(false);
+  });
+
+  test('idempotent: re-run after success is a no-op', () => {
+    run();
+    const r2 = run();
+    expect(r2.code).toBe(0);
+    expect(r2.stderr).toBe('');
+  });
+
+  test('repo already renamed (gh repo view succeeds with new name) → no rename attempt', () => {
+    makeFakeGh({ alreadyRenamed: true });
+    const r = run();
+    expect(r.code).toBe(0);
+    expect(r.stderr).toContain('already named');
+  });
+});
+
+describe('v1.27.0.0 migration — interruption resume', () => {
+  beforeEach(() => {
+    fs.writeFileSync(
+      path.join(tmpHome, '.gstack-brain-remote.txt'),
+      'https://github.com/testuser/gstack-brain-testuser\n'
+    );
+    makeFakeGh({});
+  });
+
+  test('partial journal: skips already-done steps', () => {
+    // Pre-plant journal with steps 1+2 marked done.
+    const migDir = path.join(tmpHome, '.gstack/.migrations');
+    fs.mkdirSync(migDir, { recursive: true });
+    fs.writeFileSync(path.join(migDir, 'v1.27.0.0.journal'), 'gh_repo_renamed\nremote_txt_renamed\n');
+
+    const r = run();
+    expect(r.code).toBe(0);
+    // gh should NOT have been called (step 1 already done).
+    if (fs.existsSync(path.join(fakeBinDir, 'gh-calls.log'))) {
+      const ghLog = fs.readFileSync(path.join(fakeBinDir, 'gh-calls.log'), 'utf-8');
+      expect(ghLog).not.toMatch(/gh repo rename/);
+      expect(ghLog).not.toMatch(/gh repo edit/);
+    }
+    // Final state: done touchfile written, journal removed.
+    expect(fs.existsSync(path.join(migDir, 'v1.27.0.0.done'))).toBe(true);
+    expect(fs.existsSync(path.join(migDir, 'v1.27.0.0.journal'))).toBe(false);
+  });
+});
+
+describe('v1.27.0.0 migration — remote-MCP mode (step 5 prints, never executes)', () => {
+  test('with mcpServers.gbrain.type=url → step 5 prints commands, doesn\'t call gbrain', () => {
+    fs.writeFileSync(
+      path.join(tmpHome, '.gstack-brain-remote.txt'),
+      'https://github.com/testuser/gstack-brain-testuser\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpHome, '.claude.json'),
+      JSON.stringify({ mcpServers: { gbrain: { type: 'url', url: 'https://example.com/mcp' } } })
+    );
+    makeFakeGh({});
+    makeFakeGbrain({}); // installed, but should NOT be called for sources commands
+
+    const r = run();
+    expect(r.code).toBe(0);
+    expect(r.stderr).toContain('Remote MCP detected');
+    expect(r.stderr).toContain('Send this to your brain admin');
+    expect(r.stderr).toContain('gbrain sources add');
+
+    // Confirm the script did NOT call `gbrain sources add/remove` locally.
+    if (fs.existsSync(path.join(fakeBinDir, 'gbrain-calls.log'))) {
+      const log = fs.readFileSync(path.join(fakeBinDir, 'gbrain-calls.log'), 'utf-8');
+      expect(log).not.toMatch(/gbrain sources add/);
+      expect(log).not.toMatch(/gbrain sources remove/);
+    }
+  });
+});
+
+describe('v1.27.0.0 migration — local CLI sources swap (codex Finding #6 ordering)', () => {
+  test('add-new before remove-old (verify by call order in log)', () => {
+    fs.writeFileSync(
+      path.join(tmpHome, '.gstack-brain-remote.txt'),
+      'https://github.com/testuser/gstack-brain-testuser\n'
+    );
+    fs.mkdirSync(path.join(tmpHome, '.gstack/.git'), { recursive: true }); // brain repo present
+    makeFakeGh({});
+    makeFakeGbrain({ hasOldSource: true });
+
+    const r = run();
+    expect(r.code).toBe(0);
+
+    const log = fs.readFileSync(path.join(fakeBinDir, 'gbrain-calls.log'), 'utf-8');
+    const addIdx = log.indexOf('gbrain sources add gstack-artifacts-testuser');
+    const removeIdx = log.indexOf('gbrain sources remove gstack-brain-testuser');
+    expect(addIdx).toBeGreaterThan(-1);
+    expect(removeIdx).toBeGreaterThan(-1);
+    // Critical: add must come BEFORE remove (no downtime window).
+    expect(addIdx).toBeLessThan(removeIdx);
+  });
+
+  test('add fails → old source stays registered (no silent loss)', () => {
+    fs.writeFileSync(
+      path.join(tmpHome, '.gstack-brain-remote.txt'),
+      'https://github.com/testuser/gstack-brain-testuser\n'
+    );
+    fs.mkdirSync(path.join(tmpHome, '.gstack/.git'), { recursive: true });
+    makeFakeGh({});
+    makeFakeGbrain({ addSucceeds: false });
+
+    const r = run();
+    expect(r.code).toBe(0); // step 5 warns, doesn't fail the migration
+    expect(r.stderr).toContain('failed to add');
+    const log = fs.readFileSync(path.join(fakeBinDir, 'gbrain-calls.log'), 'utf-8');
+    // Remove was NOT called because add failed.
+    expect(log).not.toMatch(/gbrain sources remove/);
+  });
+});
+
+describe('v1.27.0.0 migration — CLAUDE.md block field rewrite', () => {
+  test('rewrites "- Memory sync:" → "- Artifacts sync:" in CLAUDE.md', () => {
+    fs.writeFileSync(
+      path.join(tmpHome, '.gstack-brain-remote.txt'),
+      'https://github.com/testuser/gstack-brain-testuser\n'
+    );
+    const claudeMd = `# Project notes
+
+## GBrain Configuration (configured by /setup-gbrain)
+- Engine: pglite
+- Memory sync: full
+- Current repo policy: read-write
+`;
+    fs.writeFileSync(path.join(tmpHome, 'CLAUDE.md'), claudeMd);
+    makeFakeGh({});
+
+    const r = run();
+    expect(r.code).toBe(0);
+    const updated = fs.readFileSync(path.join(tmpHome, 'CLAUDE.md'), 'utf-8');
+    expect(updated).toContain('- Artifacts sync: full');
+    expect(updated).not.toContain('- Memory sync:');
+  });
+});