@cairnkeep/cli 2.1.0 → 2.2.1

package/scripts/cairn-container

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+VERSION=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$ROOT/package.json" | head -1)
+ENGINE=${CONTAINER_ENGINE:-podman}
+SERVER_IMAGE=${CAIRNKEEP_CONTAINER_IMAGE:-ghcr.io/cairnkeep/cairnkeep:${VERSION:-latest}}
+WORKSPACE_IMAGE=${CAIRNKEEP_WORKSPACE_IMAGE:-ghcr.io/cairnkeep/cairnkeep-workspace:${VERSION:-latest}}
+
+usage() {
+  cat <<'EOF'
+Usage:
+  cairn-container stdio [--image IMAGE] [--volume VOLUME]
+  cairn-container http --token-file FILE [--port PORT] [--name NAME]
+                       [--allowed-hosts HOSTS] [--image IMAGE]
+                       [--volume VOLUME] [--env-file FILE]
+  cairn-container workspace --repo PATH [--mode sandbox|shared]
+                            [--image IMAGE] [--data-volume VOLUME]
+                            [--workspace-volume VOLUME] [--home-volume VOLUME]
+                            [--env-file FILE] [--secret NAME=FILE]... [--] [COMMAND...]
+
+`sandbox` copies the selected repository into a named volume and leaves the
+host checkout untouched. `shared` bind-mounts the selected repository read/write.
+Secret files are mounted read-only and exposed through NAME_FILE variables.
+EOF
+}
+
+fail() {
+  echo "cairn-container: $*" >&2
+  exit 2
+}
+
+require_engine() {
+  command -v "$ENGINE" >/dev/null 2>&1 || fail "$ENGINE is not installed"
+}
+
+absolute_dir() {
+  [ -d "$1" ] || fail "not a directory: $1"
+  (cd "$1" && pwd -P)
+}
+
+absolute_file() {
+  [ -f "$1" ] || fail "not a regular file: $1"
+  [ ! -L "$1" ] || fail "refusing symlink: $1"
+  dir=$(dirname "$1")
+  base=$(basename "$1")
+  printf '%s/%s\n' "$(cd "$dir" && pwd -P)" "$base"
+}
+
+check_secret_mode() {
+  file=$1
+  if stat -c '%a' "$file" >/dev/null 2>&1; then
+    mode=$(stat -c '%a' "$file")
+  else
+    mode=$(stat -f '%Lp' "$file")
+  fi
+  case "$mode" in
+    400 | 600) ;;
+    *) fail "secret file must have mode 400 or 600: $file" ;;
+  esac
+}
+
+safe_name() {
+  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9_.-' '-'
+}
+
+podman_base_args() {
+  PODMAN_ARGS=(
+    run --rm
+    --userns=keep-id:uid=10001,gid=10001
+    --cap-drop=all
+    --security-opt=no-new-privileges
+    --read-only
+    --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777
+  )
+}
+
+run_stdio() {
+  image=$SERVER_IMAGE
+  volume=cairnkeep-data
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --image) [ "$#" -ge 2 ] || fail "--image requires a value"; image=$2; shift 2 ;;
+      --volume) [ "$#" -ge 2 ] || fail "--volume requires a value"; volume=$2; shift 2 ;;
+      -h | --help) usage; exit 0 ;;
+      *) fail "unknown stdio option: $1" ;;
+    esac
+  done
+
+  require_engine
+  podman_base_args
+  exec "$ENGINE" "${PODMAN_ARGS[@]}" -i \
+    --volume "$volume:/data:Z,U" \
+    "$image" stdio
+}
+
+run_http() {
+  image=$SERVER_IMAGE
+  volume=cairnkeep-data
+  name=cairnkeep
+  port=7801
+  token_file=
+  env_file=
+  allowed_hosts=
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --image) [ "$#" -ge 2 ] || fail "--image requires a value"; image=$2; shift 2 ;;
+      --volume) [ "$#" -ge 2 ] || fail "--volume requires a value"; volume=$2; shift 2 ;;
+      --name) [ "$#" -ge 2 ] || fail "--name requires a value"; name=$2; shift 2 ;;
+      --port) [ "$#" -ge 2 ] || fail "--port requires a value"; port=$2; shift 2 ;;
+      --token-file) [ "$#" -ge 2 ] || fail "--token-file requires a value"; token_file=$2; shift 2 ;;
+      --env-file) [ "$#" -ge 2 ] || fail "--env-file requires a value"; env_file=$2; shift 2 ;;
+      --allowed-hosts) [ "$#" -ge 2 ] || fail "--allowed-hosts requires a value"; allowed_hosts=$2; shift 2 ;;
+      -h | --help) usage; exit 0 ;;
+      *) fail "unknown http option: $1" ;;
+    esac
+  done
+
+  [ -n "$token_file" ] || fail "http mode requires --token-file"
+  token_file=$(absolute_file "$token_file")
+  check_secret_mode "$token_file"
+  case "$port" in *[!0-9]* | "") fail "invalid port: $port" ;; esac
+
+  require_engine
+  podman_base_args
+  PODMAN_ARGS+=(--detach --replace --name "$name")
+  [ -z "$env_file" ] || PODMAN_ARGS+=(--env-file "$(absolute_file "$env_file")")
+  if [ -z "$allowed_hosts" ]; then
+    allowed_hosts="localhost:${port},127.0.0.1:${port},localhost:7801,127.0.0.1:7801"
+  fi
+
+  exec "$ENGINE" "${PODMAN_ARGS[@]}" \
+    --publish "127.0.0.1:${port}:7801" \
+    --volume "$volume:/data:Z,U" \
+    --volume "$token_file:/run/secrets/http-token:ro,Z" \
+    --env MCP_HTTP_HOST=0.0.0.0 \
+    --env MCP_HTTP_PORT=7801 \
+    --env "CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=$allowed_hosts" \
+    --env CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token \
+    "$image" http
+}
+
+run_workspace() {
+  image=$WORKSPACE_IMAGE
+  mode=sandbox
+  repo=
+  data_volume=cairnkeep-data
+  home_volume=cairnkeep-home
+  workspace_volume=
+  env_file=
+  secret_specs=()
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --repo) [ "$#" -ge 2 ] || fail "--repo requires a value"; repo=$2; shift 2 ;;
+      --mode) [ "$#" -ge 2 ] || fail "--mode requires a value"; mode=$2; shift 2 ;;
+      --image) [ "$#" -ge 2 ] || fail "--image requires a value"; image=$2; shift 2 ;;
+      --data-volume) [ "$#" -ge 2 ] || fail "--data-volume requires a value"; data_volume=$2; shift 2 ;;
+      --home-volume) [ "$#" -ge 2 ] || fail "--home-volume requires a value"; home_volume=$2; shift 2 ;;
+      --workspace-volume) [ "$#" -ge 2 ] || fail "--workspace-volume requires a value"; workspace_volume=$2; shift 2 ;;
+      --env-file) [ "$#" -ge 2 ] || fail "--env-file requires a value"; env_file=$2; shift 2 ;;
+      --secret) [ "$#" -ge 2 ] || fail "--secret requires NAME=FILE"; secret_specs+=("$2"); shift 2 ;;
+      --) shift; break ;;
+      -h | --help) usage; exit 0 ;;
+      *) break ;;
+    esac
+  done
+
+  [ -n "$repo" ] || fail "workspace mode requires --repo"
+  repo=$(absolute_dir "$repo")
+  case "$mode" in sandbox | shared) ;; *) fail "--mode must be sandbox or shared" ;; esac
+  if [ -z "$workspace_volume" ]; then
+    repo_id=$(printf '%s' "$repo" | cksum | awk '{print $1}')
+    workspace_volume="cairnkeep-workspace-$(safe_name "$(basename "$repo")")-$repo_id"
+  fi
+
+  require_engine
+  podman_base_args
+  PODMAN_ARGS+=(-i)
+  [ ! -t 0 ] || PODMAN_ARGS+=(-t)
+  PODMAN_ARGS+=(
+    --volume "$data_volume:/data:Z,U"
+    --volume "$home_volume:/home/cairn:Z,U"
+    --env "CAIRN_WORKSPACE_MODE=$mode"
+  )
+  if [ "$mode" = shared ]; then
+    PODMAN_ARGS+=(--volume "$repo:/workspace:rw,Z")
+  else
+    PODMAN_ARGS+=(
+      --volume "$repo:/source:ro,Z"
+      --volume "$workspace_volume:/workspace:Z,U"
+    )
+  fi
+  [ -z "$env_file" ] || PODMAN_ARGS+=(--env-file "$(absolute_file "$env_file")")
+
+  for spec in "${secret_specs[@]}"; do
+    name=${spec%%=*}
+    file=${spec#*=}
+    [ "$name" != "$spec" ] || fail "--secret requires NAME=FILE"
+    case "$name" in *[!A-Z0-9_]* | "") fail "invalid secret variable name: $name" ;; esac
+    file=$(absolute_file "$file")
+    check_secret_mode "$file"
+    target=$(safe_name "$name")
+    PODMAN_ARGS+=(
+      --volume "$file:/run/secrets/$target:ro,Z"
+      --env "${name}_FILE=/run/secrets/$target"
+    )
+  done
+
+  if [ "$#" -eq 0 ]; then
+    set -- bash
+  fi
+  exec "$ENGINE" "${PODMAN_ARGS[@]}" "$image" "$@"
+}
+
+cmd=${1:-help}
+[ "$#" -eq 0 ] || shift
+case "$cmd" in
+  stdio) run_stdio "$@" ;;
+  http) run_http "$@" ;;
+  workspace) run_workspace "$@" ;;
+  help | -h | --help) usage ;;
+  *) fail "unknown command: $cmd" ;;
+esac

package/scripts/doctor.sh

@@ -28,6 +28,17 @@ fail() { printf '  [FAIL] %s\n' "$1"; fails=$((fails + 1)); }
 # reachable); a connect/timeout failure returns non-zero.
 reachable() { curl -sS -m 5 -o /dev/null "$1" >/dev/null 2>&1; }
 
+embedding_works() {
+  local payload
+  payload=$(node -e 'process.stdout.write(JSON.stringify({ model: process.argv[1], input: ["cairnkeep health check"] }))' \
+    "$CAIRN_MEMORY_EMBEDDING_MODEL") || return 1
+  curl -fsS -m 10 -o /dev/null \
+    -H "Authorization: Bearer $CAIRN_LLM_API_KEY" \
+    -H "Content-Type: application/json" \
+    --data "$payload" \
+    "${CAIRN_MEMORY_EMBEDDING_URL%/}/embeddings" >/dev/null 2>&1
+}
+
 echo "cairn doctor"
 
 # 1. Required memory server: prove that the shipped build and dependencies can
@@ -66,10 +77,12 @@ fi
 if [[ -n "${CAIRN_MEMORY_EMBEDDING_URL:-}" ]]; then
   if ! command -v curl >/dev/null 2>&1; then
     skip "embedding endpoint: curl not installed, cannot probe ${CAIRN_MEMORY_EMBEDDING_URL}"
-  elif reachable "$CAIRN_MEMORY_EMBEDDING_URL"; then
-    pass "embedding endpoint reachable (${CAIRN_MEMORY_EMBEDDING_URL})"
+  elif [[ -z "${CAIRN_LLM_API_KEY:-}" || -z "${CAIRN_MEMORY_EMBEDDING_MODEL:-}" ]]; then
+    fail "embedding configuration incomplete (CAIRN_LLM_API_KEY and CAIRN_MEMORY_EMBEDDING_MODEL are required)"
+  elif embedding_works; then
+    pass "embedding endpoint accepted model ${CAIRN_MEMORY_EMBEDDING_MODEL} (${CAIRN_MEMORY_EMBEDDING_URL})"
   else
-    fail "embedding endpoint unreachable (${CAIRN_MEMORY_EMBEDDING_URL})"
+    fail "embedding request failed for model ${CAIRN_MEMORY_EMBEDDING_MODEL} (${CAIRN_MEMORY_EMBEDDING_URL})"
   fi
 else
   skip "embedding endpoint (CAIRN_MEMORY_EMBEDDING_URL unset)"

package/scripts/probe-container-memory.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const [mode, rawUrl, token] = process.argv.slice(2);
+if (!["write", "read"].includes(mode) || !rawUrl || !token) {
+    console.error("usage: probe-container-memory.mjs <write|read> URL TOKEN");
+    process.exit(2);
+}
+
+const client = new Client({ name: "cairnkeep-container-probe", version: "1" });
+const transport = new StreamableHTTPClientTransport(new URL(rawUrl), {
+    requestInit: {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "X-Cairn-Project": "container-smoke",
+            "X-Cairn-Scopes": "identity,project",
+        },
+    },
+});
+
+try {
+    await client.connect(transport);
+    if (mode === "write") {
+        const response = await client.callTool({
+            name: "memory_write",
+            arguments: {
+                scope: "identity",
+                key: "patterns/container-persistence",
+                value: "survives container replacement",
+            },
+        });
+        if (response.isError) throw new Error("memory_write returned an error");
+        console.log("container memory write: ok");
+    } else {
+        const response = await client.callTool({
+            name: "memory_read",
+            arguments: {
+                scope: "identity",
+                key: "patterns/container-persistence",
+            },
+        });
+        const value = response.structuredContent?.results?.[0]?.value;
+        if (value !== "survives container replacement") {
+            throw new Error("persisted memory was not recovered");
+        }
+        console.log("container memory persistence: ok");
+    }
+} finally {
+    await client.close();
+}

package/scripts/test-container-runner.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+capture=$tmp/args
+engine=$tmp/podman
+repo=$tmp/repository
+token=$tmp/token
+env_file=$tmp/container.env
+mkdir -p "$repo"
+printf 'token\n' > "$token"
+printf 'CAIRN_MEMORY_EMBEDDING_MODEL=example\n' > "$env_file"
+chmod 600 "$token"
+
+cat > "$engine" <<'EOF'
+#!/bin/sh
+printf '%s\n' "$@" > "$CAIRN_CONTAINER_CAPTURE"
+EOF
+chmod 755 "$engine"
+
+run_launcher() {
+  CAIRN_CONTAINER_CAPTURE=$capture CONTAINER_ENGINE=$engine \
+    "$ROOT/scripts/cairn-container" "$@"
+}
+
+has_arg() {
+  grep -Fqx -- "$1" "$capture" || {
+    echo "FAIL: missing container argument: $1" >&2
+    exit 1
+  }
+}
+
+lacks_arg() {
+  if grep -Fqx -- "$1" "$capture"; then
+    echo "FAIL: unexpected container argument: $1" >&2
+    exit 1
+  fi
+}
+
+run_launcher stdio --image example/server:1 --volume example-data
+has_arg --userns=keep-id:uid=10001,gid=10001
+has_arg --read-only
+has_arg --cap-drop=all
+has_arg example-data:/data:Z,U
+has_arg example/server:1
+has_arg stdio
+
+run_launcher http --image example/server:1 --token-file "$token" --port 8123 \
+  --allowed-hosts memory.example.com --env-file "$env_file"
+has_arg --detach
+has_arg 127.0.0.1:8123:7801
+has_arg "$token:/run/secrets/http-token:ro,Z"
+has_arg CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=memory.example.com
+has_arg CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token
+has_arg "$env_file"
+
+chmod 644 "$token"
+if run_launcher http --token-file "$token" >"$tmp/out" 2>"$tmp/err"; then
+  echo "FAIL: permissive token file was accepted" >&2
+  exit 1
+fi
+grep -Fq "mode 400 or 600" "$tmp/err"
+chmod 600 "$token"
+
+run_launcher workspace --repo "$repo" --image example/workspace:1 \
+  --workspace-volume example-workspace -- echo sandbox
+has_arg "$repo:/source:ro,Z"
+has_arg example-workspace:/workspace:Z,U
+has_arg CAIRN_WORKSPACE_MODE=sandbox
+lacks_arg "$repo:/workspace:rw,Z"
+has_arg echo
+has_arg sandbox
+
+run_launcher workspace --repo "$repo" --mode shared --image example/workspace:1
+has_arg "$repo:/workspace:rw,Z"
+has_arg CAIRN_WORKSPACE_MODE=shared
+lacks_arg "$repo:/source:ro,Z"
+has_arg bash
+
+repo_id=$(printf '%s' "$repo" | cksum | awk '{print $1}')
+run_launcher workspace --repo "$repo" --image example/workspace:1
+has_arg "cairnkeep-workspace-repository-$repo_id:/workspace:Z,U"
+
+echo "PASS: container launcher security and workspace contracts"

package/scripts/test-container.sh

@@ -0,0 +1,214 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${CAIRN_TEST_CONTAINERS:-0}" != 1 ]]; then
+  echo "SKIP: container integration (set CAIRN_TEST_CONTAINERS=1 to run)"
+  exit 0
+fi
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+ENGINE=${CONTAINER_ENGINE:-}
+if [[ -z "$ENGINE" ]]; then
+  if command -v podman >/dev/null 2>&1; then ENGINE=podman
+  elif command -v docker >/dev/null 2>&1; then ENGINE=docker
+  else echo "FAIL: Podman or Docker is required" >&2; exit 1
+  fi
+fi
+command -v "$ENGINE" >/dev/null 2>&1 || { echo "FAIL: container engine not found: $ENGINE" >&2; exit 1; }
+
+suffix=$$
+server_image="localhost/cairnkeep-test-server:$suffix"
+workspace_image="localhost/cairnkeep-test-workspace:$suffix"
+volume="cairnkeep-test-data-$suffix"
+sandbox_volume="cairnkeep-test-workspace-$suffix"
+conflict_volume="cairnkeep-test-conflict-$suffix"
+name="cairnkeep-test-$suffix"
+tmp=$(mktemp -d)
+
+cleanup() {
+  "$ENGINE" rm -f "$name" >/dev/null 2>&1 || true
+  "$ENGINE" volume rm -f "$volume" "$sandbox_volume" "$conflict_volume" >/dev/null 2>&1 || true
+  "$ENGINE" image rm -f "$server_image" "$workspace_image" >/dev/null 2>&1 || true
+  rm -rf "$tmp"
+}
+trap cleanup EXIT
+
+cd "$ROOT"
+"$ENGINE" build --target server -t "$server_image" -f Containerfile .
+"$ENGINE" build --target workspace -t "$workspace_image" -f Containerfile .
+
+image_user=$("$ENGINE" image inspect --format '{{.Config.User}}' "$server_image")
+[[ "$image_user" == "10001:10001" ]] || {
+  echo "FAIL: server image must run as 10001:10001, got $image_user" >&2
+  exit 1
+}
+
+"$ENGINE" volume create "$volume" >/dev/null
+node scripts/probe-memory-server.mjs --command \
+  "$ENGINE" run --rm -i --volume "$volume:/data" "$server_image" stdio
+
+if "$ENGINE" run --rm "$server_image" http >/dev/null 2>&1; then
+  echo "FAIL: HTTP mode started without a token" >&2
+  exit 1
+fi
+
+token=container-smoke-token
+printf '%s' "$token" > "$tmp/http-token"
+# Docker bind mounts preserve the host UID; world-read is acceptable for this
+# non-secret fixture. The real Podman launcher requires mode 400 or 600.
+chmod 644 "$tmp/http-token"
+port=$(node -e 'const s=require("net").createServer();s.listen(0,"127.0.0.1",()=>{console.log(s.address().port);s.close()})')
+
+start_http() {
+  "$ENGINE" run --detach --name "$name" \
+    --read-only --cap-drop=all --security-opt=no-new-privileges \
+    --tmpfs /tmp:rw,noexec,nosuid,size=64m,mode=1777 \
+    --publish "127.0.0.1:${port}:7801" \
+    --volume "$volume:/data" \
+    --volume "$tmp/http-token:/run/secrets/http-token:ro" \
+    --env MCP_HTTP_HOST=0.0.0.0 \
+    --env MCP_HTTP_PORT=7801 \
+    --env "CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=127.0.0.1:${port}" \
+    --env CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token \
+    "$server_image" http >/dev/null
+
+  for _ in $(seq 1 50); do
+    if node scripts/probe-container-memory.mjs read "http://127.0.0.1:${port}/mcp" "$token" \
+      >"$tmp/read.out" 2>"$tmp/read.err"; then
+      return 0
+    fi
+    if ! "$ENGINE" inspect "$name" >/dev/null 2>&1; then break; fi
+    sleep 0.2
+  done
+  return 1
+}
+
+# First boot: wait for MCP, then write the canary.
+"$ENGINE" run --detach --name "$name" \
+  --read-only --cap-drop=all --security-opt=no-new-privileges \
+  --tmpfs /tmp:rw,noexec,nosuid,size=64m,mode=1777 \
+  --publish "127.0.0.1:${port}:7801" \
+  --volume "$volume:/data" \
+  --volume "$tmp/http-token:/run/secrets/http-token:ro" \
+  --env MCP_HTTP_HOST=0.0.0.0 \
+  --env MCP_HTTP_PORT=7801 \
+  --env "CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=127.0.0.1:${port}" \
+  --env CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token \
+  "$server_image" http >/dev/null
+written=0
+for _ in $(seq 1 50); do
+  if node scripts/probe-container-memory.mjs write "http://127.0.0.1:${port}/mcp" "$token" \
+    >"$tmp/write.out" 2>"$tmp/write.err"; then
+    written=1
+    break
+  fi
+  sleep 0.2
+done
+[[ "$written" == 1 ]] || {
+  cat "$tmp/write.err" >&2
+  echo "FAIL: container HTTP server did not become ready" >&2
+  exit 1
+}
+cat "$tmp/write.out"
+"$ENGINE" exec "$name" node /usr/local/lib/cairnkeep/container-healthcheck.mjs
+"$ENGINE" rm -f "$name" >/dev/null
+
+# Replacement boot with the same volume must recover the canary.
+start_http || {
+  cat "$tmp/read.err" >&2
+  echo "FAIL: persisted memory was not readable after replacement" >&2
+  exit 1
+}
+cat "$tmp/read.out"
+"$ENGINE" rm -f "$name" >/dev/null
+
+mkdir -p "$tmp/repo"
+printf 'source\n' > "$tmp/repo/source.txt"
+
+# Shared mode deliberately writes through to the selected host repository.
+if [[ "$ENGINE" == podman ]]; then
+  "$ENGINE" run --rm --userns=keep-id:uid=10001,gid=10001 \
+    --volume "$tmp/repo:/workspace:Z" \
+    --env CAIRN_WORKSPACE_MODE=shared \
+    "$workspace_image" sh -c 'printf shared > shared.txt'
+else
+  chmod 755 "$tmp"
+  chmod 777 "$tmp/repo"
+  chmod 666 "$tmp/repo/source.txt"
+  "$ENGINE" run --rm \
+    --volume "$tmp/repo:/workspace" \
+    --env CAIRN_WORKSPACE_MODE=shared \
+    "$workspace_image" sh -c 'printf shared > shared.txt'
+fi
+[[ $(cat "$tmp/repo/shared.txt") == shared ]] || {
+  echo "FAIL: shared workspace did not write through" >&2
+  exit 1
+}
+
+# Prepare a writable named volume for the image's unprivileged runtime user.
+"$ENGINE" volume create "$sandbox_volume" >/dev/null
+if [[ "$ENGINE" == podman ]]; then
+  "$ENGINE" run --rm --userns=keep-id:uid=10001,gid=10001 \
+    --volume "$tmp/repo:/source:ro,Z" \
+    --volume "$sandbox_volume:/workspace:Z,U" \
+    --env CAIRN_WORKSPACE_MODE=sandbox \
+    "$workspace_image" sh -c 'printf sandbox > sandbox.txt'
+else
+  "$ENGINE" run --rm --user root --entrypoint sh \
+    --volume "$sandbox_volume:/workspace" "$workspace_image" \
+    -c 'chown 10001:10001 /workspace'
+  "$ENGINE" run --rm \
+    --volume "$tmp/repo:/source:ro" \
+    --volume "$sandbox_volume:/workspace" \
+    --env CAIRN_WORKSPACE_MODE=sandbox \
+    "$workspace_image" sh -c 'printf sandbox > sandbox.txt'
+fi
+[[ ! -e "$tmp/repo/sandbox.txt" ]] || {
+  echo "FAIL: sandbox mode modified the host repository" >&2
+  exit 1
+}
+if [[ "$ENGINE" == podman ]]; then
+  "$ENGINE" run --rm --userns=keep-id:uid=10001,gid=10001 \
+    --volume "$tmp/repo:/source:ro,Z" \
+    --volume "$sandbox_volume:/workspace:Z,U" \
+    --env CAIRN_WORKSPACE_MODE=sandbox \
+    "$workspace_image" sh -c 'test "$(cat sandbox.txt)" = sandbox'
+else
+  "$ENGINE" run --rm \
+    --volume "$tmp/repo:/source:ro" \
+    --volume "$sandbox_volume:/workspace" \
+    --env CAIRN_WORKSPACE_MODE=sandbox \
+    "$workspace_image" sh -c 'test "$(cat sandbox.txt)" = sandbox'
+fi
+
+# A pre-populated, unmarked volume must not be merged with repository content.
+"$ENGINE" volume create "$conflict_volume" >/dev/null
+if [[ "$ENGINE" == podman ]]; then
+  "$ENGINE" run --rm --userns=keep-id:uid=10001,gid=10001 \
+    --volume "$conflict_volume:/workspace:Z,U" \
+    --env CAIRN_WORKSPACE_MODE=shared \
+    "$workspace_image" sh -c 'printf unrelated > unrelated.txt'
+else
+  "$ENGINE" run --rm --user root --entrypoint sh \
+    --volume "$conflict_volume:/workspace" "$workspace_image" \
+    -c 'printf unrelated > /workspace/unrelated.txt; chown -R 10001:10001 /workspace'
+fi
+if [[ "$ENGINE" == podman ]]; then
+  conflict_mounts=(
+    --userns=keep-id:uid=10001,gid=10001
+    --volume "$tmp/repo:/source:ro,Z"
+    --volume "$conflict_volume:/workspace:Z,U"
+  )
+else
+  conflict_mounts=(
+    --volume "$tmp/repo:/source:ro"
+    --volume "$conflict_volume:/workspace"
+  )
+fi
+if "$ENGINE" run --rm "${conflict_mounts[@]}" \
+  --env CAIRN_WORKSPACE_MODE=sandbox "$workspace_image" true >/dev/null 2>&1; then
+  echo "FAIL: sandbox merged into a non-empty unmarked volume" >&2
+  exit 1
+fi
+
+echo "PASS: container stdio, guarded HTTP, persistence, shared, and sandbox modes"

package/scripts/test-doctor.sh

@@ -5,7 +5,12 @@ set -uo pipefail
 
 ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 tmp=$(mktemp -d)
-trap 'rm -rf "$tmp"' EXIT
+server_pid=""
+cleanup() {
+  [[ -n "$server_pid" ]] && kill "$server_pid" 2>/dev/null || true
+  rm -rf "$tmp"
+}
+trap cleanup EXIT
 fail() { echo "FAIL: $1" >&2; exit 1; }
 
 doctor="$ROOT/scripts/doctor.sh"
@@ -46,4 +51,59 @@ else
   echo "  (curl absent — skipped the unreachable-endpoint case)"
 fi
 
-echo "PASS: cairn doctor (skip unconfigured, fail configured-unreachable)"
+# 4. The embedding check performs a real authenticated model request.
+if command -v curl >/dev/null 2>&1; then
+  cat > "$tmp/embedding-server.mjs" <<'EOF'
+import { createServer } from "node:http";
+import { writeFileSync } from "node:fs";
+
+const server = createServer((request, response) => {
+  const chunks = [];
+  request.on("data", (chunk) => chunks.push(chunk));
+  request.on("end", () => {
+    let body = {};
+    try { body = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch {}
+    const valid = request.url === "/v1/embeddings"
+      && request.headers.authorization === "Bearer test-key"
+      && body.model === "test-embedding";
+    response.writeHead(valid ? 200 : 404, { "Content-Type": "application/json" });
+    response.end(JSON.stringify(valid
+      ? { data: [{ index: 0, embedding: [1, 0] }] }
+      : { error: "invalid request" }));
+  });
+});
+server.listen(0, "127.0.0.1", () => {
+  writeFileSync(process.argv[2], String(server.address().port));
+});
+EOF
+  node "$tmp/embedding-server.mjs" "$tmp/embedding-port" &
+  server_pid=$!
+  for _ in $(seq 1 50); do [[ -s "$tmp/embedding-port" ]] && break; sleep 0.1; done
+  [[ -s "$tmp/embedding-port" ]] || fail "embedding test server did not start"
+  port=$(cat "$tmp/embedding-port")
+
+  proj3="$tmp/embedding-ok"; mkdir -p "$proj3/.ai"
+  cat > "$proj3/.ai/.env" <<EOF
+CAIRN_MEMORY_EMBEDDING_URL=http://127.0.0.1:$port/v1
+CAIRN_MEMORY_EMBEDDING_MODEL=test-embedding
+CAIRN_LLM_API_KEY=test-key
+EOF
+  ( cd "$proj3" && "$doctor" ) >"$tmp/out3" 2>&1 ||
+    fail "doctor rejected a working embedding endpoint:\n$(cat "$tmp/out3")"
+  grep -q "\[PASS\] embedding endpoint accepted model test-embedding" "$tmp/out3" ||
+    fail "expected a functional embedding PASS line"
+
+  proj4="$tmp/embedding-wrong-model"; mkdir -p "$proj4/.ai"
+  cat > "$proj4/.ai/.env" <<EOF
+CAIRN_MEMORY_EMBEDDING_URL=http://127.0.0.1:$port/v1
+CAIRN_MEMORY_EMBEDDING_MODEL=missing-model
+CAIRN_LLM_API_KEY=test-key
+EOF
+  if ( cd "$proj4" && "$doctor" ) >"$tmp/out4" 2>&1; then
+    fail "doctor should reject a missing embedding model:\n$(cat "$tmp/out4")"
+  fi
+  grep -q "\[FAIL\] embedding request failed for model missing-model" "$tmp/out4" ||
+    fail "expected a functional embedding FAIL line"
+fi
+
+echo "PASS: cairn doctor (skip unconfigured, fail unreachable, probe embeddings)"