aether-colony 3.1.5 → 3.1.16

package/CHANGELOG.md

@@ -41,6 +41,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Session Freshness Detection System** — Global system to prevent stale session files from silently breaking Aether workflows. Implements `session-verify-fresh` and `session-clear` commands with support for 7 commands (survey, oracle, watch, swarm, init, seal, entomb). Features cross-platform timestamp detection (macOS/Linux), environment variable overrides for testing, and protected operations (init/seal/entomb never auto-clear). Backward compatibility maintained with `survey-verify-fresh` and `survey-clear` wrappers. Added comprehensive test suite (`tests/bash/test-session-freshness.sh`) and API documentation (`docs/session-freshness-api.md`). (`.aether/aether-utils.sh`, `tests/bash/test-session-freshness.sh`, `docs/session-freshness-api.md`)
+  - `/ant:colonize` — Added `--force-resurvey` flag, stale survey detection, and verification
+  - `/ant:oracle` — Added `--force` flag, stale session detection with user options
+  - `/ant:watch` — Added session timestamp capture and stale file handling
+  - `/ant:swarm` — Added auto-clear for stale findings with verification
+  - `/ant:init` — Added freshness check with protected state (no auto-clear)
+  - `/ant:seal` — Added incomplete archive detection and integrity verification
+  - `/ant:entomb` — Added incomplete chamber detection and integrity verification
+
+### Fixed
+- **Architecture Cleanup: Source of Truth Flipped** — Complete review and cleanup of the flipped source-of-truth architecture. `.aether/` is now the source of truth for system files, with `runtime/` auto-populated by `bin/sync-to-runtime.sh` during npm install. Fixed 6 stale documentation files, updated 5 planning files, expanded allowlist from 20 to 36 files, handled 4 orphan files, and verified zero drift between directories. (`.aether/recover.sh`, `.aether/RECOVERY-PLAN.md`, `.planning/codebase/STRUCTURE.md`, `.planning/codebase/ARCHITECTURE.md`, `.planning/codebase/CONVENTIONS.md`, `TO-DOS.md`, `bin/sync-to-runtime.sh`, `bin/lib/update-transaction.js`)
+
+### Changed
+- **Phase 4: UX Improvements to Lay-Eggs** — Enhanced lay-eggs.md with visual lifecycle diagrams (🟢 ACTIVE COLONY → 🏺 SEAL/ENTOMB → 🥚 LAY EGGS) in error messages to clarify workflow progression. Updated success output to explicitly distinguish between sealing vs laying eggs for new projects, preserving wisdom across colony lifecycles. (`.claude/commands/ant/lay-eggs.md`)
+
 ### Fixed
 - **Phase 2: Fix Blocker Severity and Auto-Resolve Logic** — Made auto_resolve_on conditional by flag source: chaos-sourced blockers require manual resolution (auto_resolve_on: null), verification blockers auto-resolve on build pass. Reordered continue.md Flags Gate to run auto-resolve before blocker count check. Added advisory blocker warning (Step 1.5) to build.md so builders see active blockers before execution. (`.aether/aether-utils.sh`, `runtime/aether-utils.sh`, `.claude/commands/ant/continue.md`, `.opencode/commands/ant/continue.md`, `.claude/commands/ant/build.md`, `.opencode/commands/ant/build.md`)
 - **Phase 1: Fix Chaos Ant Duplicate Flagging** — Eliminated duplicate flag creation during build-rebuild cycles by removing redundant chaos flagging from build.md Step 5.5 (Step 5.4.2 already handles it), injected existing flag titles into Chaos Ant spawn prompt to prevent re-investigating known issues, and added flag persistence to standalone /ant:chaos for critical/high findings using source 'chaos-standalone'. (`.claude/commands/ant/build.md`, `.opencode/commands/ant/build.md`, `.claude/commands/ant/chaos.md`, `.opencode/commands/ant/chaos.md`)

package/README.md

@@ -18,7 +18,7 @@
   [![npm version](https://img.shields.io/npm/v/aether-colony.svg)](https://www.npmjs.com/package/aether-colony)
   [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-  **v1.1.0** — Production ready with model routing
+  **v3.1.14** — Production ready with model routing
 </div>
 
 ---
@@ -43,9 +43,9 @@ Aether brings **ant colony intelligence** to Claude Code. Instead of one agent d
    ├── 🔍 Scouts — research docs
    ├── 🗺️ Colonizers — explore codebases
    ├── 📋 Route-setters — plan phases
-   ├── 🏛️ Architects — extract patterns
+   ├── 🏗️ Architects — extract patterns
    ├── 🏺 Archaeologists — excavate git history
-   ├── 🔮 Oracles — deep research
+   ├── 🔮 Oracles — deep research (RALF pattern)
    └── 🎲 Chaos Ants — resilience testing
 ```
 
@@ -59,6 +59,8 @@ When a Builder hits something complex, it spawns a Scout to research. When code
 - **6-Phase Verification** — Build, types, lint, tests, security, diff before advancing
 - **Colony Memory** — Learnings and instincts persist across sessions
 - **Pause/Resume** — Full state serialization for context breaks
+- **Oracle Deep Research** — 50+ iteration autonomous research loop (RALF pattern)
+- **Multi-Agent Surveys** — 4 parallel scouts for codebase analysis
 
 ---
 
@@ -96,74 +98,101 @@ That's it. The colony takes over from there.
 
 ---
 
-## Commands
+## Complete Command Reference (33 Commands)
 
-Aether has **33 slash commands** organized into categories.
+### 🌱 Core Lifecycle Commands
 
-### Core Lifecycle
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:init "goal"` | 🌱 | Initialize colony with mission |
+| `/ant:plan` | 📝 | Generate phased roadmap (50-iteration research loop) |
+| `/ant:build N` | 🔨 | Execute phase N with worker waves |
+| `/ant:continue` | ➡️ | 6-phase verification, then advance to next phase |
+| `/ant:pause-colony` | 💾 | Save state for context break |
+| `/ant:resume-colony` | ▶️ | Restore from pause |
+| `/ant:lay-eggs "new goal"` | 🥚 | Start fresh colony (preserves instincts) |
+| `/ant:seal` | 🏺 | Complete and archive colony |
+| `/ant:entomb` | ⚰️ | Create chamber from completed colony |
 
-| Command | Purpose |
-|---------|---------|
-| `/ant:init "goal"` | Initialize colony with mission |
-| `/ant:plan` | Generate phased roadmap (50-iteration research loop) |
-| `/ant:build N` | Execute phase N with worker waves |
-| `/ant:continue` | 6-phase verification, then advance |
-| `/ant:status` | Colony overview |
-| `/ant:pause-colony` | Save state for context break |
-| `/ant:resume-colony` | Restore from pause |
-
-### Pheromone Signals
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:focus "area"` | Guide colony attention |
-| `/ant:redirect "pattern"` | Warn away from approaches |
-| `/ant:feedback "msg"` | Teach preferences |
-
-### Power Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:swarm "problem"` | Deploy 4 parallel scouts for stubborn bugs |
-| `/ant:council` | Clarify intent via multi-choice questions |
-| `/ant:oracle` | Deep research with 50+ iterations |
-
-### Research & Analysis
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:colonize` | Analyze existing codebase |
-| `/ant:archaeology <path>` | Excavate git history |
-| `/ant:chaos <target>` | Resilience testing |
-| `/ant:organize` | Codebase hygiene report |
-| `/ant:dream` | Philosophical codebase wanderer |
-| `/ant:interpret` | Ground dreams in reality |
-
-### Issue Tracking
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:flag "issue"` | Create blocker/issue/note |
-| `/ant:flags` | List and manage flags |
-
-### Visibility
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:watch` | Live tmux monitoring |
-| `/ant:phase N` | View phase details |
-| `/ant:history` | Recent colony activity |
-| `/ant:help` | Full command reference |
-
-### System
+**Core Lifecycle Flow:**
+```
+/ant:init → /ant:plan → /ant:build 1 → /ant:continue → /ant:build 2 → ... → /ant:seal → /ant:entomb
+```
 
-| Command | Purpose |
-|---------|---------|
-| `/ant:update` | Sync system files from hub |
-| `/ant:migrate-state` | Upgrade old state format |
-| `/ant:verify-castes` | Check model routing |
-| `/ant:seal` | Complete and archive colony |
-| `/ant:entomb` | Create chamber from completed colony |
+### 📊 Research & Analysis Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:colonize` | 🗺️ | **Multi-agent territory survey** — 4 parallel scouts analyze your codebase and produce: `STRUCTURE.md`, `INTEGRATIONS.md`, `CONVENTIONS.md`, `ARCHITECTURE.md`, `CONCERNS.md` |
+| `/ant:archaeology <path>` | 🏺 | Excavate git history for any file/directory — traces why code exists, surfaces tribal knowledge, identifies "don't touch" areas |
+| `/ant:oracle ["topic"]` | 🔮 | **Deep research with RALF pattern** — 50+ iteration autonomous research loop. Use `stop` or `status` as arguments |
+| `/ant:chaos <target>` | 🎲 | Resilience testing — probes edge cases, boundary conditions, finds cracks before they break |
+| `/ant:swarm ["problem"]` | 🔥 | Deploy 4 parallel scouts for stubborn bugs OR view real-time swarm display |
+| `/ant:dream` | 💭 | The Dreamer — philosophical codebase wanderer that observes and imagines |
+| `/ant:interpret` | 🔍 | Ground dreams in reality — validates observations against actual code |
+| `/ant:organize` | 🧹 | Codebase hygiene report — scans for stale files, dead code, orphaned configs |
+
+**Research Command Details:**
+
+#### `/ant:colonize` — Territory Survey
+Dispatches 4 parallel Scout agents to analyze your codebase:
+- **Scout 1**: Maps directory structure, identifies entry points, dependencies
+- **Scout 2**: Maps integrations (databases, APIs, third-party services)
+- **Scout 3**: Documents conventions (naming, patterns, architecture decisions)
+- **Scout 4**: Identifies concerns (tech debt, risks, areas needing attention)
+
+Produces 5 documentation files in `.aether/docs/`.
+
+#### `/ant:oracle` — Deep Research (RALF Pattern)
+The Oracle runs autonomously in a separate process using the Recursive Agent Loop Framework:
+1. Configure research topic via interactive wizard
+2. Oracle iterates 50+ times, accumulating knowledge
+3. Each iteration reads previous progress, researches gaps
+4. Produces comprehensive findings in `.aether/oracle/discoveries/`
+
+Non-invasive: Never touches colony state, only writes to `.aether/oracle/`.
+
+### 🧭 Planning & Coordination Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:council` | 🏛️ | Clarify intent via multi-choice questions |
+| `/ant:focus "area"` | 🔦 | Emit FOCUS signal — guide colony attention |
+| `/ant:redirect "pattern"` | ⚠️ | Emit REDIRECT signal — warn away from approaches |
+| `/ant:feedback "msg"` | 💬 | Emit FEEDBACK signal — teach preferences |
+
+**Pheromone Signals:**
+- **FOCUS** (normal priority): "Pay attention here"
+- **REDIRECT** (high priority): "Don't do this" (hard constraint)
+- **FEEDBACK** (low priority): "Adjust based on this"
+
+### 📋 Visibility & Status Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:status` | 📈 | Colony overview — current phase, progress, active workers |
+| `/ant:phase N` | 📝 | View phase details — tasks, status, assignments |
+| `/ant:history` | 📜 | Recent colony activity log |
+| `/ant:maturity` | 👑 | View colony maturity journey with ASCII art anthill |
+| `/ant:watch` | 👁️ | Set up tmux session to watch ants working in real-time |
+| `/ant:tunnels [ch1] [ch2]` | 🕳️ | Explore tunnels — browse archived colonies, compare chambers |
+| `/ant:flags` | 🚩 | List and manage flags (blockers, issues, notes) |
+| `/ant:help` | 📖 | Full command reference |
+
+### 🚩 Issue Tracking Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:flag "issue"` | 🚩 | Create blocker/issue/note |
+| `/ant:flags` | 📋 | List and manage flags |
+
+### ⚙️ System Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:update` | 🔄 | Sync system files from global hub |
+| `/ant:verify-castes` | ✓ | Check caste model assignments and system status |
+| `/ant:migrate-state` | 🚚 | One-time state migration from v1 to v2.0 format |
 
 ---
 
@@ -175,20 +204,36 @@ The `aether` CLI provides additional utilities:
 # View version and status
 aether version
 
+# Update all registered repos
+aether update --all
+aether update --all --force  # Force even with dirty repos
+
 # Manage model routing
 aether caste-models list
 aether caste-models set builder=kimi-k2.5
+aether caste-models reset builder
 
-# Checkpoints
+# Checkpoints (safe snapshots)
 aether checkpoint create "before refactor"
 aether checkpoint list
 aether checkpoint restore <id>
+aether checkpoint verify <id>
 
 # View telemetry
 aether telemetry
+aether telemetry model kimi-k2.5
+aether telemetry performance
 
 # Sync state with planning docs
 aether sync-state
+
+# Context
+aether context        # Show auto-loaded context including nestmates
+aether nestmates      # List sibling colonies
+aether spawn-tree     # Display worker spawn tree
+
+# Initialize in current repo
+aether init --goal "My project"
 ```
 
 ---
@@ -226,18 +271,18 @@ Set `LITELLM_AUTH_TOKEN` environment variable for custom auth.
 
 ## The Castes
 
-| Caste | Role | Model |
-|-------|------|-------|
-| 👑 **Queen** | Orchestrates, spawns workers, synthesizes | glm-5 |
-| 🔨 **Builder** | Writes code, TDD-first | kimi-k2.5 |
-| 👁️ **Watcher** | Tests, validates, quality gates | kimi-k2.5 |
-| 🔍 **Scout** | Researches docs, finds answers | minimax-2.5 |
-| 🗺️ **Colonizer** | Explores codebases, maps structure | minimax-2.5 |
-| 🏛️ **Architect** | Synthesizes patterns, coordinates docs | glm-5 |
-| 📋 **Route-Setter** | Plans phases, breaks down goals | kimi-k2.5 |
-| 🏺 **Archaeologist** | Excavates git history | glm-5 |
-| 🔮 **Oracle** | Deep research, architecture analysis | minimax-2.5 |
-| 🎲 **Chaos** | Resilience testing, adversarial probing | kimi-k2.5 |
+| Caste | Emoji | Role | Model |
+|-------|-------|------|-------|
+| 👑 **Queen** | — | Orchestrates, spawns workers, synthesizes | glm-5 |
+| 🔨 **Builder** | 🛠️ | Writes code, TDD-first | kimi-k2.5 |
+| 👁️ **Watcher** | 👀 | Tests, validates, quality gates | kimi-k2.5 |
+| 🔍 **Scout** | 🗺️ | Researches docs, finds answers | minimax-2.5 |
+| 🗺️ **Colonizer** | 📊 | Explores codebases, maps structure | minimax-2.5 |
+| 🏗️ **Architect** | 🏛️ | Synthesizes patterns, coordinates docs | glm-5 |
+| 📋 **Route-Setter** | 🧭 | Plans phases, breaks down goals | kimi-k2.5 |
+| 🏺 **Archaeologist** | 📜 | Excavates git history | glm-5 |
+| 🔮 **Oracle** | 🔮 | Deep research, architecture analysis | minimax-2.5 |
+| 🎲 **Chaos** | 🎲 | Resilience testing, adversarial probing | kimi-k2.5 |
 
 ---
 
@@ -328,8 +373,33 @@ Detected automatically via `milestone-detect` utility.
     ├── aether-utils.sh           # Utility layer (50+ subcommands)
     ├── model-profiles.yaml       # Caste-to-model routing
     ├── verification-loop.md      # 6-phase verification reference
+    ├── QUEEN_ANT_ARCHITECTURE.md # Complete system architecture
+    ├── coding-standards.md       # Coding standards reference
+    ├── debugging.md              # Debugging discipline
+    ├── tdd.md                    # TDD discipline
+    │
+    ├── docs/                     # Documentation
+    │   ├── known-issues.md       # Known bugs and workarounds
+    │   ├── implementation-learnings.md  # Workflow patterns
+    │   ├── codebase-review.md    # Command inventory
+    │   ├── planning-discipline.md # Planning guidelines
+    │   └── ...
     │
-    ├── data/                     # Per-project state
+    ├── utils/                    # Utility scripts
+    │   ├── atomic-write.sh
+    │   ├── colorize-log.sh
+    │   ├── file-lock.sh
+    │   ├── spawn-tree.sh
+    │   └── ...
+    │
+    ├── oracle/                   # Oracle research infrastructure
+    │   ├── oracle.sh             # RALF loop script
+    │   ├── oracle.md             # Oracle agent prompt
+    │   ├── research.json         # Active research config
+    │   ├── progress.md           # Research progress
+    │   └── discoveries/          # Research findings
+    │
+    ├── data/                     # Per-project state (NEVER synced)
     │   ├── COLONY_STATE.json     # Goal, plan, memory, instincts
     │   ├── flags.json            # Blockers, issues, notes
     │   ├── constraints.json      # Focus areas and redirects
@@ -338,7 +408,8 @@ Detected automatically via `milestone-detect` utility.
     │   ├── telemetry.json        # Model performance data
     │   └── completion-report.md  # End-of-project summary
     │
-    ├── dreams/                   # Dream session files
+    ├── dreams/                   # Dream session files (NEVER synced)
+    ├── checkpoints/              # Update rollback data (NEVER synced)
     └── chambers/                 # Entombed (archived) colonies
 
 bin/                              # CLI
@@ -354,7 +425,9 @@ bin/                              # CLI
 
 ---
 
-## Typical Workflow
+## Typical Workflows
+
+### Starting a New Project
 
 ```
 1. /ant:init "Build feature X"     # Set the goal
@@ -367,6 +440,26 @@ bin/                              # CLI
 8. /ant:seal                        # Complete and archive
 ```
 
+### Deep Research Workflow
+
+```
+/ant:oracle "research topic"    # Configure and launch Oracle
+# Oracle runs autonomously for 50+ iterations
+/ant:oracle status              # Check progress
+/ant:oracle stop                # Stop if needed
+# Read findings in .aether/oracle/discoveries/
+```
+
+### Codebase Analysis Workflow
+
+```
+/ant:colonize                   # 4 scouts survey territory
+# Read generated docs in .aether/docs/
+/ant:archaeology src/legacy/    # Excavate git history
+/ant:organize                   # Hygiene report
+/ant:chaos "auth module"        # Resilience test
+```
+
 ### Between Sessions
 
 ```bash
@@ -390,7 +483,7 @@ bin/                              # CLI
 
 ## OpenCode Agents
 
-Aether includes 4 specialized OpenCode agents:
+Aether includes specialized OpenCode agents:
 
 | Agent | Purpose | Temperature |
 |-------|---------|-------------|
@@ -424,15 +517,30 @@ Aether includes 4 specialized OpenCode agents:
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### Three-Tier Distribution
+
+```
+Aether Repo (.aether/)  →  Hub (~/.aether/)  →  Target Repos (.aether/)
+         │                        │                        │
+         │   npm install -g .     │    aether update       │
+         └───────────────────────→┴───────────────────────→┘
+                              (excluding user data)
+```
+
+**User data directories are NEVER synced:** `data/`, `dreams/`, `checkpoints/`, `locks/`, `temp/`
+
 ---
 
 ## Safety Features
 
-- **File Locking** — Prevents concurrent modification of state
+- **File Locking** — Prevents concurrent modification of state with configurable stale lock detection
 - **Atomic Writes** — Temp file + rename pattern
 - **Update Transactions** — Two-phase commit with rollback
+- **State Validation** — Schema validation before any state modifications
+- **Event Pruning** — Automatic cleanup prevents unbounded event history
 - **Git Checkpoints** — Automatic commits before phases
 - **Ant Graveyards** — Failed files marked for future caution
+- **Checkpoint System** — Safe snapshots before updates with `aether checkpoint`
 
 ---
 
@@ -459,11 +567,16 @@ npm install -g aether-colony
 # Verify install
 aether version
 ls ~/.claude/commands/ant/
+ls ~/.aether/  # Check hub structure
 
 # Verify runtime (from inside any repo)
 ls .aether/
 
-# Update
+# Update system files in all registered repos
+aether update --all
+aether update --all --force  # Force even with dirty repos
+
+# Update npm package
 npm update -g aether-colony
 
 # Uninstall (preserves project state)

package/bin/cli.js

@@ -70,11 +70,9 @@ const COMMANDS_DEST = path.join(HOME, '.claude', 'commands', 'ant');
 
 // Hub paths
 const HUB_DIR = path.join(HOME, '.aether');
-const HUB_SYSTEM = path.join(HUB_DIR, 'system');
 const HUB_COMMANDS_CLAUDE = path.join(HUB_DIR, 'commands', 'claude');
 const HUB_COMMANDS_OPENCODE = path.join(HUB_DIR, 'commands', 'opencode');
 const HUB_AGENTS = path.join(HUB_DIR, 'agents');
-const HUB_VISUALIZATIONS = path.join(HUB_DIR, 'visualizations');
 const HUB_REGISTRY = path.join(HUB_DIR, 'registry.json');
 const HUB_VERSION = path.join(HUB_DIR, 'version.json');
 
@@ -836,6 +834,122 @@ function gitStashFiles(repoPath, files) {
   }
 }
 
+// Directories to exclude from hub sync (user data, local state)
+const HUB_EXCLUDE_DIRS = ['data', 'dreams', 'checkpoints', 'locks', 'temp'];
+
+/**
+ * Check if a path should be excluded from hub sync
+ * @param {string} relPath - Relative path from .aether/
+ * @returns {boolean} True if should be excluded
+ */
+function shouldExcludeFromHub(relPath) {
+  const parts = relPath.split(path.sep);
+  // Exclude if any part of the path is in the exclude list
+  return parts.some(part => HUB_EXCLUDE_DIRS.includes(part));
+}
+
+/**
+ * Sync .aether/ directory to hub, excluding user data directories
+ * @param {string} srcDir - Source .aether/ directory
+ * @param {string} destDir - Destination hub directory
+ * @returns {object} Sync result with copied, removed, skipped counts
+ */
+function syncAetherToHub(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) {
+    return { copied: 0, removed: 0, skipped: 0 };
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  // Get all files in source, filtering out excluded directories
+  const srcFiles = [];
+  function collectFiles(dir, base) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.relative(base, fullPath);
+
+      if (shouldExcludeFromHub(relPath)) continue;
+
+      if (entry.isDirectory()) {
+        collectFiles(fullPath, base);
+      } else {
+        srcFiles.push(relPath);
+      }
+    }
+  }
+  collectFiles(srcDir, srcDir);
+
+  // Copy files with hash comparison
+  let copied = 0;
+  let skipped = 0;
+  for (const relPath of srcFiles) {
+    const srcPath = path.join(srcDir, relPath);
+    const destPath = path.join(destDir, relPath);
+
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+
+    // Hash comparison
+    let shouldCopy = true;
+    if (fs.existsSync(destPath)) {
+      const srcHash = hashFileSync(srcPath);
+      const destHash = hashFileSync(destPath);
+      if (srcHash === destHash) {
+        shouldCopy = false;
+        skipped++;
+      }
+    }
+
+    if (shouldCopy) {
+      fs.copyFileSync(srcPath, destPath);
+      if (relPath.endsWith('.sh')) {
+        fs.chmodSync(destPath, 0o755);
+      }
+      copied++;
+    }
+  }
+
+  // Cleanup: remove files in dest that aren't in source (and aren't excluded)
+  const destFiles = [];
+  function collectDestFiles(dir, base) {
+    if (!fs.existsSync(dir)) return;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'registry.json' || entry.name === 'version.json' || entry.name === 'manifest.json') continue;
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.relative(base, fullPath);
+
+      if (shouldExcludeFromHub(relPath)) continue;
+
+      if (entry.isDirectory()) {
+        collectDestFiles(fullPath, base);
+      } else {
+        destFiles.push(relPath);
+      }
+    }
+  }
+  collectDestFiles(destDir, destDir);
+
+  const srcSet = new Set(srcFiles);
+  const removed = [];
+  for (const relPath of destFiles) {
+    if (!srcSet.has(relPath)) {
+      removed.push(relPath);
+      try {
+        fs.unlinkSync(path.join(destDir, relPath));
+      } catch (err) {
+        // Ignore cleanup errors
+      }
+    }
+  }
+
+  // Clean up empty directories
+  cleanEmptyDirs(destDir);
+
+  return { copied, removed, skipped };
+}
+
 function setupHub() {
   // Create ~/.aether/ directory structure and populate from package
   try {
@@ -848,17 +962,35 @@ function setupHub() {
       log(`  Warning: previous manifest is invalid, regenerating`);
     }
 
-    // Sync runtime/ -> ~/.aether/system/
+    // Sync runtime/ -> ~/.aether/ (clean production files)
+    // runtime/ is the staging area - explicit allowlist via sync-to-runtime.sh
     const runtimeSrc = path.join(PACKAGE_DIR, 'runtime');
     if (fs.existsSync(runtimeSrc)) {
-      const result = syncDirWithCleanup(runtimeSrc, HUB_SYSTEM);
-      log(`  Hub system: ${result.copied} files -> ${HUB_SYSTEM}`);
+      const result = syncAetherToHub(runtimeSrc, HUB_DIR);
+      log(`  Hub system: ${result.copied} files, ${result.skipped} unchanged -> ${HUB_DIR}`);
       if (result.removed.length > 0) {
         log(`  Hub system: removed ${result.removed.length} stale files`);
         for (const f of result.removed) log(`    - ${f}`);
       }
     }
 
+    // Clean up legacy directories from old hub structure
+    const legacyDirs = [
+      path.join(HUB_DIR, 'system'),
+      path.join(HUB_DIR, '.aether'),
+      path.join(HUB_DIR, 'visualizations'),
+    ];
+    for (const legacyDir of legacyDirs) {
+      if (fs.existsSync(legacyDir)) {
+        try {
+          removeDirSync(legacyDir);
+          log(`  Cleaned up legacy: ${path.basename(legacyDir)}/`);
+        } catch (err) {
+          // Ignore cleanup errors
+        }
+      }
+    }
+
     // Sync .claude/commands/ant/ -> ~/.aether/commands/claude/
     const claudeCmdSrc = fs.existsSync(COMMANDS_SRC)
       ? COMMANDS_SRC
@@ -894,17 +1026,6 @@ function setupHub() {
       }
     }
 
-    // Sync .aether/visualizations/ -> ~/.aether/visualizations/
-    const visualizationsSrc = path.join(PACKAGE_DIR, '.aether', 'visualizations');
-    if (fs.existsSync(visualizationsSrc)) {
-      const result = syncDirWithCleanup(visualizationsSrc, HUB_VISUALIZATIONS);
-      log(`  Hub visualizations: ${result.copied} files -> ${HUB_VISUALIZATIONS}`);
-      if (result.removed.length > 0) {
-        log(`  Hub visualizations: removed ${result.removed.length} stale files`);
-        for (const f of result.removed) log(`    - ${f}`);
-      }
-    }
-
     // Create/preserve registry.json
     if (!fs.existsSync(HUB_REGISTRY)) {
       writeJsonSync(HUB_REGISTRY, { schema_version: 1, repos: [] });
@@ -971,7 +1092,7 @@ async function updateRepo(repoPath, sourceVersion, opts) {
   }
 
   // Use UpdateTransaction for two-phase commit with automatic rollback
-  const transaction = new UpdateTransaction(repoPath, { sourceVersion, quiet });
+  const transaction = new UpdateTransaction(repoPath, { sourceVersion, quiet, force });
 
   try {
     const result = await transaction.execute(sourceVersion, { dryRun });
@@ -980,18 +1101,15 @@ async function updateRepo(repoPath, sourceVersion, opts) {
     const systemCopied = result.sync_result?.system?.copied || 0;
     const commandsCopied = (result.sync_result?.commands?.copied || 0);
     const agentsCopied = result.sync_result?.agents?.copied || 0;
-    const visualizationsCopied = result.sync_result?.visualizations?.copied || 0;
 
     const systemRemoved = result.sync_result?.system?.removed?.length || 0;
     const commandsRemoved = result.sync_result?.commands?.removed?.length || 0;
     const agentsRemoved = result.sync_result?.agents?.removed?.length || 0;
-    const visualizationsRemoved = result.sync_result?.visualizations?.removed?.length || 0;
 
     const allRemovedFiles = [
       ...(result.sync_result?.system?.removed || []),
       ...(result.sync_result?.commands?.removed || []).map(f => `.claude/commands/ant/${f}`),
       ...(result.sync_result?.agents?.removed || []).map(f => `.opencode/agents/${f}`),
-      ...(result.sync_result?.visualizations?.removed || []).map(f => `.aether/visualizations/${f}`),
     ];
 
     return {
@@ -1001,8 +1119,7 @@ async function updateRepo(repoPath, sourceVersion, opts) {
       system: systemCopied,
       commands: commandsCopied,
       agents: agentsCopied,
-      visualizations: visualizationsCopied,
-      removed: systemRemoved + commandsRemoved + agentsRemoved + visualizationsRemoved,
+      removed: systemRemoved + commandsRemoved + agentsRemoved,
       removedFiles: allRemovedFiles,
       stashCreated: !!transaction.checkpoint?.stashRef,
       checkpoint_id: result.checkpoint_id,
@@ -1171,14 +1288,14 @@ program
             console.error(`  Skipping. Use --force to stash and update.`);
             dirty++;
           } else if (result.status === 'dry-run') {
-            log(`  Would update: ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents, ${result.visualizations} visualizations]`);
+            log(`  Would update: ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents]`);
             if (result.removed > 0) {
               log(`  Would remove ${result.removed} stale files:`);
               for (const f of result.removedFiles) log(`    - ${f}`);
             }
             updated++;
           } else if (result.status === 'updated') {
-            log(`  ${c.success('Updated:')} ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents, ${result.visualizations} visualizations]`);
+            log(`  ${c.success('Updated:')} ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents]`);
             if (result.removed > 0) {
               log(`  Removed ${result.removed} stale files:`);
               for (const f of result.removedFiles) log(`    - ${f}`);
@@ -1254,7 +1371,7 @@ program
 
         if (result.status === 'dry-run') {
           console.log(`Would update: ${result.from} -> ${result.to}`);
-          console.log(`  ${result.system} system files, ${result.commands} command files, ${result.agents} agent files, ${result.visualizations} visualization files`);
+          console.log(`  ${result.system} system files, ${result.commands} command files, ${result.agents} agent files`);
           if (result.removed > 0) {
             console.log(`  Would remove ${result.removed} stale files:`);
             for (const f of result.removedFiles) console.log(`    - ${f}`);