create-walle 0.9.21 → 0.9.23

package/README.md

@@ -1,6 +1,6 @@
 # create-walle
 
-Set up **CTM + Wall-E** in one command — a browser-based command center for AI coding agents, remote phone access, review workflows, and a personal AI agent that builds a searchable second brain from your work life.
+Set up **CTM + Wall-E** in one command — a browser-based command center for AI coding agents, remote phone and tablet access, review workflows, and a personal AI agent that builds a searchable second brain from your work life.
 
 ## What You Get
 
@@ -12,7 +12,7 @@ A web dashboard for running and managing AI coding sessions across multiple prov
 - **Prompt Editor** — Save, version, and organize prompts with folders, tags, chains, templates, and AI search
 - **Task Queue** — Queue prompts for sequential execution with auto-advance when the agent finishes, or step through manually
 - **Approval Workflows** — Auto-approve tool-use requests based on learned rules; uncertain cases escalate to you
-- **Remote Phone Access** — Pair your phone with a QR code and use a mobile CTM UI over Microsoft Dev Tunnels, Tailscale, Cloudflare Tunnel, or Walle Remote, with live prompts and model controls
+- **Remote Phone & Tablet Access** — Pair your phone or tablet with a QR code and use a responsive CTM UI over Microsoft Dev Tunnels, Tailscale, Cloudflare Tunnel, or Walle Remote, with live prompts and model controls
 - **Code & Doc Review** — Review git diffs and Markdown docs side by side, add anchored comments, and send feedback into an agent session or queue
 - **Model Registry** — Manage providers (Anthropic, OpenAI, Google, DeepSeek, Ollama, LM Studio, MLX, and CLI subscription providers), compare pricing, switch models per session
 - **Session Insights** — Analyze patterns across sessions to optimize prompts and workflows
@@ -35,7 +35,7 @@ An always-on AI agent that learns from your Slack, email, calendar, and coding s
 npx create-walle install ./walle
 ```
 
-This copies the project, installs dependencies, auto-detects your name and timezone, and starts the server. Open **http://localhost:3456** to finish setup in the browser, then pair your phone from Setup if you want remote access.
+This copies the project, installs dependencies, auto-detects your name and timezone, and starts the server. Open **http://localhost:3456** to finish setup in the browser, then pair your phone or tablet from Setup if you want remote access.
 
 ## Commands
 
@@ -55,6 +55,28 @@ against the exact Node.js binary Wall-E will use. If you switch Node versions,
 Wall-E automatically runs the needed `npm rebuild` before starting so CTM does
 not crash with a `NODE_MODULE_VERSION` mismatch.
 
+### Pinning Node (optional — for machines with more than one Node)
+
+On a machine with a **single** Node, the auto-rebuild above is all you need.
+But if you have **two or more** Node versions (e.g. a system Node *and* a
+Homebrew Node, or you switch with `nvm`/`fnm`), the daemon and a background skill
+can run under different majors and fight over the one compiled `better-sqlite3`
+binary — each rebuild flips its ABI and the other side crash-loops with
+"MCP never became ready".
+
+To stop that, lock CTM + Wall-E to one Node:
+
+```bash
+bash bin/pin-node.sh          # pin to your current node version
+bash bin/pin-node.sh 22.12.0  # …or an explicit version
+bash bin/pin-node.sh --unpin  # revert to the default (auto-rebuild) behavior
+```
+
+This writes a `.node-version` so the launchers always resolve that exact Node
+and the daemon refuses to start under a different major (with a clear message)
+instead of silently corrupting the native binary. Existing installs adopt it the
+moment you run the command — nothing else changes.
+
 ## Setup
 
 On first launch, the browser setup page guides you through:
@@ -62,7 +84,7 @@ On first launch, the browser setup page guides you through:
 1. **Owner name** — auto-detected from `git config`
 2. **API key** — enter manually, or click "Auto-detect" to find it from your shell environment, Claude Code OAuth, or corporate devbox
 3. **Integrations** — connect Slack (OAuth), email and calendar auto-detected on macOS
-4. **Remote phone access** — optional QR pairing with Microsoft Dev Tunnels, Tailscale, Cloudflare Tunnel, or Walle Remote, including phone-friendly prompts and model controls
+4. **Remote phone and tablet access** — optional QR pairing with Microsoft Dev Tunnels, Tailscale, Cloudflare Tunnel, or Walle Remote, including touch-friendly prompts and model controls
 
 ## Custom Port
 
@@ -78,7 +100,7 @@ Everything runs locally. CTM serves the dashboard, Wall-E runs as a background a
 
 | Component | Default Port | What it does |
 |-----------|-------------|--------------|
-| CTM | 3456 | Dashboard, multi-agent terminal, prompt editor, queue, model registry, code/doc review, remote phone UI |
+| CTM | 3456 | Dashboard, multi-agent terminal, prompt editor, queue, model registry, code/doc review, remote phone/tablet UI |
 | Wall-E | 3457 | AI agent, brain database, skills engine, multi-model chat API |
 
 ## Links

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-walle",
-  "version": "0.9.21",
-  "description": "CTM + Wall-E \u2014 AI coding dashboard and personal digital twin agent. Multi-agent terminal for Claude Code, Codex, Gemini, Aider, OpenCode, and more, plus prompt editor, task queue, remote phone access, code/doc review, and an agent that learns from Slack, email & calendar.",
+  "version": "0.9.23",
+  "description": "CTM + Wall-E \u2014 AI coding dashboard and personal digital twin agent. Multi-agent terminal for Claude Code, Codex, Gemini, Aider, OpenCode, and more, plus prompt editor, task queue, remote phone and tablet access, code/doc review, and an agent that learns from Slack, email & calendar.",
   "bin": {
     "create-walle": "bin/create-walle.js"
   },

package/template/CLAUDE.md

@@ -19,8 +19,8 @@ kills all active sessions. This applies to ALL operations: curl, fetch, restart,
 
 When developing CTM or Wall-E code:
 1. Use the `/ctm-dev` skill (or run it manually)
-2. Pick a random port pair: `DEV_CTM_PORT=$((4100 + RANDOM % 900))`
-3. Start a dev instance: `DEV_CTM_PORT=$port DEV_WALLE_PORT=$((port+1)) bash bin/dev.sh`
+2. Start a dev instance: `bash bin/dev.sh --fresh` or `bash bin/dev.sh --refresh`
+3. Read the printed `Dev CTM:` URL and use that port for all curl/browser tests
 4. Test ONLY against your dev port, never 3456
 5. Only restart primary when the user explicitly asks — and ask for confirmation first
 

package/template/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Juncao Li
+Copyright (c) 2026 Wall-E contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/template/bin/ctm-dev-cleanup.js

@@ -2,6 +2,12 @@
 'use strict';
 
 const { execFileSync } = require('child_process');
+const {
+  CTM_PROCESS_NAME,
+  WALLE_PROCESS_NAME,
+  legacyProcessTitle,
+  processTitle,
+} = require('../claude-task-manager/lib/process-title');
 
 const DEFAULT_MAX_AGE_MIN = 24 * 60;
 const PROTECTED_PORTS = new Set([3456, 3457]);
@@ -107,21 +113,36 @@ function processDetails(pid, lsof = lsofBinary()) {
 
 function isProtectedProcess(proc, details = {}) {
   if (/^(ctm|walle)-primary\b/.test(proc.command)) return true;
+  if (proc.command === CTM_PROCESS_NAME || proc.command === WALLE_PROCESS_NAME) return true;
   return (details.ports || []).some(port => PROTECTED_PORTS.has(Number(port)));
 }
 
 function titleKind(command) {
+  const ctmName = CTM_PROCESS_NAME.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const walleName = WALLE_PROCESS_NAME.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   if (/^ctm-dev-\d+\b/.test(command)) return 'ctm-dev';
+  if (new RegExp(`^${ctmName}\\s+dev-\\d+\\b`).test(command)) return 'ctm-dev';
   if (/^walle-dev-\d+\b/.test(command)) return 'walle-dev';
+  if (new RegExp(`^${walleName}\\s+dev-\\d+\\b`).test(command)) return 'walle-dev';
   if (/^ctm-(?:badge-test|render-test|e2e|test)(?:[-\w]*)?\b/.test(command)) return 'ctm-test';
+  if (new RegExp(`^${ctmName}\\s+(?:badge-test|render-test|e2e|test)(?:[-\\w]*)?\\b`).test(command)) return 'ctm-test';
   if (/^walle-(?:staging|render-test|e2e|test)(?:[-\w]*)?\b/.test(command)) return 'walle-test';
+  if (new RegExp(`^${walleName}\\s+(?:staging|render-test|e2e|test)(?:[-\\w]*)?\\b`).test(command)) return 'walle-test';
   return null;
 }
 
 function commandMatchesExactPort(command, port, wallePort) {
   if (PROTECTED_PORTS.has(Number(port)) || PROTECTED_PORTS.has(Number(wallePort))) return false;
-  if (port && (command === `ctm-dev-${port}` || command === `walle-dev-${port}`)) return true;
-  if (wallePort && command === `walle-dev-${Number(wallePort) - 1}`) return true;
+  if (port && (
+    command === legacyProcessTitle('ctm', `dev-${port}`)
+    || command === processTitle('ctm', `dev-${port}`)
+    || command === legacyProcessTitle('walle', `dev-${port}`)
+    || command === processTitle('walle', `dev-${port}`)
+  )) return true;
+  if (wallePort && (
+    command === legacyProcessTitle('walle', `dev-${Number(wallePort) - 1}`)
+    || command === processTitle('walle', `dev-${Number(wallePort) - 1}`)
+  )) return true;
   return false;
 }
 
@@ -235,7 +256,7 @@ function main(argv = process.argv.slice(2)) {
     console.log([
       'Usage: node bin/ctm-dev-cleanup.js [--kill] [--stale] [--max-age-min N] [--port N --wall-e-port N] [--json]',
       '',
-      'Dry-runs by default. Never targets ctm-primary/walle-primary or ports 3456/3457.',
+      `Dry-runs by default. Never targets ${CTM_PROCESS_NAME}/${WALLE_PROCESS_NAME} or ports 3456/3457.`,
     ].join('\n'));
     return 0;
   }

package/template/bin/ctm-launch.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# launchd entrypoint for the CTM primary.
+#
+# Resolves the pinned Node via bin/node-bin.sh (ignoring ambient PATH, so a
+# `brew upgrade node` or a v26-first shell can't flip the ABI) and exec's the
+# server. `exec` replaces this shell with the node process, so launchd's
+# KeepAlive supervises node directly. Because the runtime is chosen from
+# .node-version, a deliberate Node upgrade is just "edit .node-version" — the
+# LaunchAgent plist never needs to change.
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+NODE_BIN="$(bash "$ROOT/bin/node-bin.sh")"
+exec "$NODE_BIN" "$ROOT/claude-task-manager/server.js" "$@"

package/template/bin/dev.sh

@@ -3,16 +3,129 @@
 # Primary instance stays untouched. Ctrl+C to stop.
 #
 # Usage:
-#   bash bin/dev.sh              # Start dev instance with fresh empty DBs
-#   bash bin/dev.sh --refresh    # Explicitly copy production DBs before starting
-#   bash bin/dev.sh --fresh      # Reset to empty DBs before starting
+#   bash bin/dev.sh              # Pick ports and start with fresh empty DBs
+#   bash bin/dev.sh --refresh    # Pick ports and copy production DBs before starting
+#   bash bin/dev.sh --fresh      # Pick ports and reset to empty DBs before starting
+#   bash bin/dev.sh --reuse      # Pick ports and reuse existing DBs in WALLE_DEV_DIR
+#   bash bin/dev.sh --refresh --no-images  # Copy DBs only; skip image assets
+#   DEV_CTM_PORT=4456 bash bin/dev.sh  # Use an explicit port pair
 
 set -e
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-DEV_DIR="${WALLE_DEV_DIR:-/tmp/walle-dev}"
-DEV_CTM_PORT="${DEV_CTM_PORT:-4000}"
-DEV_WALLE_PORT="${DEV_WALLE_PORT:-4001}"
+# Resolve the pinned Node binary (ignores ambient PATH) so a dev instance can
+# never run under a different Node major and rebuild the shared better-sqlite3
+# to a mismatched ABI — which would crash-loop the primary daemon.
+NODE_BIN="$(bash "$ROOT/bin/node-bin.sh")" || { echo "[dev] could not resolve the pinned Node (see bin/node-bin.sh)" >&2; exit 1; }
+MODE="fresh"
+PRINT_CONFIG=0
+COPY_IMAGES=1
+KEEP_DATA_ON_EXIT="${CTM_DEV_KEEP_DATA:-0}"
+
+usage() {
+  cat <<'EOF'
+Usage: bash bin/dev.sh [--fresh|--refresh|--reuse] [--no-images] [--keep-data] [--print-config]
+
+Starts an isolated CTM/Wall-E dev instance on random non-primary ports.
+
+Options:
+  --fresh        Reset dev SQLite DBs before start (default)
+  --refresh      Snapshot production CTM/Wall-E DBs before start
+  --reuse        Reuse existing DBs in WALLE_DEV_DIR and keep data on exit
+  --no-images    With --refresh, skip copying CTM image assets
+  --keep-data    Do not remove the dev data dir when the launcher exits
+  --print-config Print resolved ports/data dir and exit
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --fresh)
+      MODE="fresh"
+      ;;
+    --refresh)
+      MODE="refresh"
+      ;;
+    --reuse|--keep)
+      MODE="reuse"
+      KEEP_DATA_ON_EXIT=1
+      ;;
+    --no-images)
+      COPY_IMAGES=0
+      ;;
+    --keep-data)
+      KEEP_DATA_ON_EXIT=1
+      ;;
+    --print-config)
+      PRINT_CONFIG=1
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "[dev] Unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+  shift
+done
+
+is_integer() {
+  [[ "$1" =~ ^[0-9]+$ ]]
+}
+
+assert_safe_port() {
+  local name="$1"
+  local port="$2"
+  if ! is_integer "$port"; then
+    echo "[dev] $name must be an integer port, got: $port" >&2
+    exit 1
+  fi
+  if [[ "$port" == "3456" || "$port" == "3457" ]]; then
+    echo "[dev] Refusing to use primary CTM/Wall-E port $port" >&2
+    exit 1
+  fi
+}
+
+port_is_free() {
+  local port="$1"
+  [[ -z "$(lsof -ti ":$port" -sTCP:LISTEN 2>/dev/null || true)" ]]
+}
+
+pick_ctm_port() {
+  local attempt candidate
+  for attempt in $(seq 1 80); do
+    candidate=$((4100 + RANDOM % 898))
+    if port_is_free "$candidate" && port_is_free "$((candidate + 1))" && port_is_free "$((candidate + 2))"; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+  echo "[dev] Could not find a free dev port pair in 4100-4999" >&2
+  exit 1
+}
+
+if [[ -z "${DEV_CTM_PORT:-}" ]]; then
+  DEV_CTM_PORT="$(pick_ctm_port)"
+else
+  assert_safe_port "DEV_CTM_PORT" "$DEV_CTM_PORT"
+fi
+
+DEV_WALLE_PORT="${DEV_WALLE_PORT:-$((DEV_CTM_PORT + 1))}"
 DEV_OAUTH_PROXY_PORT="${DEV_OAUTH_PROXY_PORT:-$((DEV_CTM_PORT + 2))}"
+assert_safe_port "DEV_WALLE_PORT" "$DEV_WALLE_PORT"
+assert_safe_port "DEV_OAUTH_PROXY_PORT" "$DEV_OAUTH_PROXY_PORT"
+
+DEV_DIR="${WALLE_DEV_DIR:-/tmp/walle-dev-$DEV_CTM_PORT}"
+
+if [[ "$PRINT_CONFIG" == "1" ]]; then
+  echo "DEV_CTM_PORT=$DEV_CTM_PORT"
+  echo "DEV_WALLE_PORT=$DEV_WALLE_PORT"
+  echo "DEV_OAUTH_PROXY_PORT=$DEV_OAUTH_PROXY_PORT"
+  echo "WALLE_DEV_DIR=$DEV_DIR"
+  exit 0
+fi
 
 # Source production .env to find DB paths. DEV_SOURCE_* lets worktrees without
 # their own .env refresh from the primary repo's configured data directory.
@@ -31,47 +144,55 @@ cleanup_processes() {
   if [[ "${1:-}" == "--stale" ]]; then
     stale_args=(--stale --max-age-min "${CTM_DEV_STALE_MAX_MIN:-1440}")
   fi
-  node "$ROOT/bin/ctm-dev-cleanup.js" \
+  "$NODE_BIN" "$ROOT/bin/ctm-dev-cleanup.js" \
     --kill \
     --port "$DEV_CTM_PORT" \
     --wall-e-port "$DEV_WALLE_PORT" \
     "${stale_args[@]}" >/dev/null 2>&1 || true
   pkill -f "ctm-dev-$DEV_CTM_PORT" 2>/dev/null || true
+  pkill -f "Coding Task Manager dev-$DEV_CTM_PORT" 2>/dev/null || true
   pkill -f "walle-dev-$DEV_CTM_PORT" 2>/dev/null || true
+  pkill -f "Wall-E dev-$DEV_CTM_PORT" 2>/dev/null || true
   lsof -ti ":$DEV_CTM_PORT" -sTCP:LISTEN 2>/dev/null | xargs kill 2>/dev/null || true
   lsof -ti ":$DEV_WALLE_PORT" -sTCP:LISTEN 2>/dev/null | xargs kill 2>/dev/null || true
   lsof -ti ":$DEV_OAUTH_PROXY_PORT" -sTCP:LISTEN 2>/dev/null | xargs kill 2>/dev/null || true
 }
 
 cleanup_dev() {
-  node "$ROOT/bin/ctm-dev-cleanup.js" \
+  "$NODE_BIN" "$ROOT/bin/ctm-dev-cleanup.js" \
     --kill \
     --port "$DEV_CTM_PORT" \
     --wall-e-port "$DEV_WALLE_PORT" >/dev/null 2>&1 || true
   cleanup_processes
   # Remove dev data directory to prevent /tmp bloat (each copy is ~2-6 GB)
-  if [[ "$DEV_DIR" == /tmp/walle-* && -d "$DEV_DIR" ]]; then
+  if [[ "$KEEP_DATA_ON_EXIT" != "1" && "$DEV_DIR" == /tmp/walle-* && -d "$DEV_DIR" ]]; then
     echo "[dev] Cleaning up $DEV_DIR ..."
     rm -rf "$DEV_DIR"
+  elif [[ "$KEEP_DATA_ON_EXIT" == "1" && -d "$DEV_DIR" ]]; then
+    echo "[dev] Keeping dev data $DEV_DIR"
   fi
 }
 
 cleanup_processes --stale
 
-# Handle flags
-if [[ "$1" == "--fresh" || -z "$1" ]]; then
+# Handle launch mode
+if [[ "$MODE" == "fresh" ]]; then
   echo "[dev] Starting with fresh (empty) databases"
   rm -f "$DEV_DIR"/*.db "$DEV_DIR"/*.db-wal "$DEV_DIR"/*.db-shm
-elif [[ "$1" == "--refresh" ]]; then
+elif [[ "$MODE" == "refresh" ]]; then
   echo "[dev] Snapshotting production databases to $DEV_DIR ..."
-  node "$ROOT/bin/sqlite-snapshot.js" "$PROD_CTM_DIR/task-manager.db" "$DEV_DIR/task-manager.db" "CTM"
-  node "$ROOT/bin/sqlite-snapshot.js" "$PROD_WALLE_DIR/wall-e-brain.db" "$DEV_DIR/wall-e-brain.db" "Brain"
-  if [[ -d "$PROD_CTM_DIR/images" ]]; then
+  "$NODE_BIN" "$ROOT/bin/sqlite-snapshot.js" "$PROD_CTM_DIR/task-manager.db" "$DEV_DIR/task-manager.db" "CTM"
+  "$NODE_BIN" "$ROOT/bin/sqlite-snapshot.js" "$PROD_WALLE_DIR/wall-e-brain.db" "$DEV_DIR/wall-e-brain.db" "Brain"
+  if [[ "$COPY_IMAGES" == "1" && -d "$PROD_CTM_DIR/images" ]]; then
     echo "  Images: syncing $PROD_CTM_DIR/images -> $DEV_DIR/images"
-    node "$ROOT/bin/sync-images.js" "$PROD_CTM_DIR/images" "$DEV_DIR/images"
+    "$NODE_BIN" "$ROOT/bin/sync-images.js" "$PROD_CTM_DIR/images" "$DEV_DIR/images"
+  elif [[ "$COPY_IMAGES" != "1" ]]; then
+    echo "  Images: skipped (--no-images)"
   fi
   # Ensure the dev instance owns its WAL files from first open.
   rm -f "$DEV_DIR"/*.db-wal "$DEV_DIR"/*.db-shm
+elif [[ "$MODE" == "reuse" ]]; then
+  echo "[dev] Reusing existing databases in $DEV_DIR"
 fi
 
 echo ""
@@ -127,6 +248,16 @@ export CTM_SESSION_MEMORY_API_BASE_URL="http://127.0.0.1:$DEV_CTM_PORT"
 export WALLE_MCP_AUTO_CONFIG="${WALLE_MCP_AUTO_CONFIG:-0}"
 export CTM_SKIP_DOTENV="1"
 
+CTM_DEV_CHILD_PID=""
+forward_signal() {
+  local signal="$1"
+  if [[ -n "$CTM_DEV_CHILD_PID" ]]; then
+    kill -"$signal" "$CTM_DEV_CHILD_PID" 2>/dev/null || true
+  fi
+}
+
+trap 'forward_signal INT' INT
+trap 'forward_signal TERM' TERM
 trap cleanup_dev EXIT
 
 # Clean up stale dev/e2e data dirs older than 24h (from crashed sessions)
@@ -134,6 +265,13 @@ find /tmp -maxdepth 1 -name "walle-dev-*" -type d -mmin +1440 -exec rm -rf {} +
 find /tmp -maxdepth 1 -name "walle-e2e-*" -type d -mmin +1440 -exec rm -rf {} + 2>/dev/null || true
 find /tmp -maxdepth 1 -name "ctm-dev-*" -type d -mmin +1440 -exec rm -rf {} + 2>/dev/null || true
 
-# Run in foreground so Ctrl+C stops it cleanly
+# Run in foreground so Ctrl+C stops it cleanly while keeping the shell trap alive.
 cd "$ROOT"
-exec node claude-task-manager/server.js
+"$NODE_BIN" claude-task-manager/server.js &
+CTM_DEV_CHILD_PID="$!"
+set +e
+wait "$CTM_DEV_CHILD_PID"
+status="$?"
+set -e
+CTM_DEV_CHILD_PID=""
+exit "$status"

package/template/bin/node-bin.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# Resolve the canonical pinned Node binary for CTM + Wall-E and print its
+# ABSOLUTE, immutable path on stdout. Exits non-zero (diagnostic on stderr) when
+# the pinned version cannot be located.
+#
+# The pin lives in <repo-root>/.node-version (single source of truth). This
+# resolver deliberately IGNORES ambient PATH so a Homebrew upgrade that repoints
+# /opt/homebrew/bin/node, or a v26-first shell, can never select the wrong ABI
+# for the shared native modules (better-sqlite3, sqlite-vec, tree-sitter).
+#
+# In a non-owner / shipped create-walle install the pin file is absent, so this
+# degrades to the PATH `node` and never constrains other users.
+set -euo pipefail
+
+find_repo_root() {
+  local dir="$1"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/.node-version" && -d "$dir/wall-e" && -d "$dir/claude-task-manager" ]]; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(find_repo_root "$SCRIPT_DIR" || true)"
+
+if [[ -z "${ROOT:-}" ]]; then
+  # No pin (non-owner / shipped context): fall back to PATH node.
+  if command -v node >/dev/null 2>&1; then
+    command -v node
+    exit 0
+  fi
+  echo "[node-bin] no .node-version pin found and no node on PATH" >&2
+  exit 1
+fi
+
+PIN="$(tr -d 'v[:space:]' < "$ROOT/.node-version")"
+if [[ -z "$PIN" ]]; then
+  echo "[node-bin] empty .node-version pin at $ROOT" >&2
+  exit 1
+fi
+
+candidates=(
+  "/opt/homebrew/Cellar/node/$PIN/bin/node"
+  "/usr/local/Cellar/node/$PIN/bin/node"
+  "$HOME/.fnm/node-versions/v$PIN/installation/bin/node"
+  "$HOME/.local/share/fnm/node-versions/v$PIN/installation/bin/node"
+  "$HOME/.nvm/versions/node/v$PIN/bin/node"
+)
+
+for c in "${candidates[@]}"; do
+  if [[ -x "$c" ]]; then
+    got="$("$c" --version 2>/dev/null | tr -d 'v[:space:]')"
+    if [[ "$got" == "$PIN" ]]; then
+      printf '%s\n' "$c"
+      exit 0
+    fi
+  fi
+done
+
+# Last resort: the ambient `node` IF it already equals the pin. Covers system
+# installs (nodejs.org pkg, distro packages) where node lives outside Cellar/
+# fnm/nvm. We still gate on an exact version match, so this never selects a
+# mismatched ABI — it just avoids a false "not found" for non-manager installs.
+if command -v node >/dev/null 2>&1; then
+  got="$(node --version 2>/dev/null | tr -d 'v[:space:]')"
+  if [[ "$got" == "$PIN" ]]; then
+    command -v node
+    exit 0
+  fi
+fi
+
+{
+  echo "[node-bin] Pinned Node v$PIN not found. CTM + Wall-E require it so the"
+  echo "  shared native modules (better-sqlite3, sqlite-vec, tree-sitter) keep a"
+  echo "  stable ABI. Install it, e.g.:"
+  echo "    brew install node@${PIN%%.*}     # or: fnm install $PIN / nvm install $PIN"
+  echo "  Looked in:"
+  printf '    %s\n' "${candidates[@]}"
+} >&2
+exit 1

package/template/bin/pin-node.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Opt into the CTM + Wall-E Node version pin.
+#
+# Writes <repo-root>/.node-version (and .nvmrc) so the runtime guard + launchers
+# lock onto ONE Node — eliminating the better-sqlite3 ABI ping-pong that happens
+# on machines with more than one Node (e.g. system + Homebrew, or nvm/fnm
+# switching). Pins to the CURRENTLY-RUNNING node by default, which is by
+# definition the version your install already works under.
+#
+# This is OPTIONAL and OFF by default for npx/create-walle installs: a
+# single-Node machine never hits the ABI flip, so most users never need it.
+#
+# Usage:
+#   bash bin/pin-node.sh            # pin to the current `node` version
+#   bash bin/pin-node.sh 22.12.0    # pin to an explicit version
+#   bash bin/pin-node.sh --unpin    # remove the pin (back to permissive)
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+if [[ ! -d "$ROOT/wall-e" || ! -d "$ROOT/claude-task-manager" ]]; then
+  echo "[pin-node] $ROOT does not look like a CTM + Wall-E checkout (missing wall-e/ or claude-task-manager/)." >&2
+  exit 1
+fi
+
+if [[ "${1:-}" == "--unpin" ]]; then
+  rm -f "$ROOT/.node-version" "$ROOT/.nvmrc"
+  echo "[pin-node] Removed .node-version / .nvmrc — Node version is now unpinned (guard is a no-op)."
+  exit 0
+fi
+
+VERSION="${1:-}"
+if [[ -z "$VERSION" ]]; then
+  if ! command -v node >/dev/null 2>&1; then
+    echo "[pin-node] No node on PATH and no version given. Pass one: bash bin/pin-node.sh 22.12.0" >&2
+    exit 1
+  fi
+  VERSION="$(node --version | tr -d 'v[:space:]')"
+fi
+
+# Sanity: a bare semver-ish string.
+if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+  echo "[pin-node] '$VERSION' is not a valid Node version (expected e.g. 22.12.0)." >&2
+  exit 1
+fi
+
+printf '%s\n' "$VERSION" > "$ROOT/.node-version"
+printf '%s\n' "$VERSION" > "$ROOT/.nvmrc"
+echo "[pin-node] Pinned CTM + Wall-E to Node v$VERSION (.node-version + .nvmrc at $ROOT)."
+echo "[pin-node] The boot guard now hard-fails any launch under a different Node major,"
+echo "[pin-node] and bin/node-bin.sh resolves this version for the launchers."
+echo "[pin-node] Undo with: bash bin/pin-node.sh --unpin"