Skip to content

ahstn/oceans-llm / .agents/skills/verify-oceans-admin

verify-oceans-admin

Verified

Verify the Oceans LLM admin control plane and backend gateway against the real local stack, seeded demo data, and bounded live providers when required. Use for user-path checks of sign-in, models, API keys, observability, usage costs, spend controls, batches, agent sessions, request logs, Anthropic Messages thinking and effort compatibility, MCP registry and tool access, OpenRouter routing, guardrails, and Skills storage.

FileKindSize
SKILL.mdskill md29.0 KB
examples/mcp-candidates.jsonconfig3.0 KB
features/README.mdmarkdown10.0 KB
features/account-onboarding.mdmarkdown4.3 KB
features/agent-harnesses.mdmarkdown4.3 KB
features/agent-plugins.mdmarkdown1005 B
features/agent-sessions.mdmarkdown3.9 KB
features/anthropic-messages.mdmarkdown20.7 KB
features/api-keys.mdmarkdown6.5 KB
features/attribution.mdmarkdown13.9 KB
features/audit-log.mdmarkdown4.9 KB
features/backend-gateway.mdmarkdown5.2 KB
features/batch-requests.mdmarkdown4.2 KB
features/design-system.mdmarkdown4.6 KB
features/guardrails.mdmarkdown7.0 KB
features/harness-integration.mdmarkdown7.8 KB
features/identity.mdmarkdown4.2 KB
features/image-generation.mdmarkdown7.3 KB
features/leaderboard.mdmarkdown3.3 KB
features/live-llm-requests.mdmarkdown12.6 KB
features/mcp-client-oauth.mdmarkdown9.9 KB
features/mcp-ownership.mdmarkdown7.4 KB
features/mcp.mdmarkdown19.6 KB
features/models.mdmarkdown8.2 KB
features/password-sign-in.mdmarkdown8.3 KB
features/profile.mdmarkdown2.5 KB
features/rate-limits.mdmarkdown6.0 KB
features/request-logs.mdmarkdown8.6 KB
features/review-agent.mdmarkdown3.7 KB
features/routing.jsonconfig33.6 KB
features/service-tiers.mdmarkdown6.3 KB
features/skills.mdmarkdown9.8 KB
features/spend-controls.mdmarkdown7.3 KB
features/usage-costs.mdmarkdown3.7 KB
features/workspace-connections.mdmarkdown6.1 KB
scripts/check-messages.mjsexecutablescript2.4 KB
scripts/check-messages.test.mjsscript3.0 KB
scripts/control-oceans-adminexecutablescript25.3 KB
scripts/control-oceans-admin.test.mjsscript7.6 KB
scripts/drive-backend-gateway.mjsexecutablescript12.5 KB
scripts/drive-harness-integration.mjsscript6.6 KB
scripts/drive-mcp.mjsscript13.0 KB
scripts/drive-models.mjsscript12.9 KB
scripts/drive-observability.mjsscript16.8 KB
scripts/drive-profile.mjsscript8.2 KB
scripts/drive-service-tiers.mjsexecutablescript20.1 KB
scripts/drive-skills.mjsscript27.2 KB
scripts/mcp-browser.mjsscript26.5 KB
scripts/mcp-canary.mjsscript18.8 KB
scripts/mcp-candidates.mjsscript3.5 KB
scripts/mcp-verification.test.mjsscript10.2 KB
scripts/messages-regressions.mjsscript15.8 KB
scripts/plan-verification.mjsscript5.2 KB
scripts/plan-verification.test.mjsscript6.1 KB
scripts/proof-cli.mjsscript11.1 KB
scripts/proof.mjsscript9.2 KB
scripts/proof.test.mjsscript10.4 KB

scripts/control-oceans-admin

View on GitHub
#!/usr/bin/env bash
set -euo pipefail

repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
run_id="${OCEANS_VERIFY_RUN_ID:-}"
gateway_port="${OCEANS_VERIFY_GATEWAY_PORT:-38090}"
ui_port="${OCEANS_VERIFY_UI_PORT:-33010}"
state_base="${OCEANS_VERIFY_STATE_BASE:-/tmp/oceans-admin-verification}"
sha256_stdin() {
  if command -v shasum >/dev/null 2>&1; then
    shasum -a 256
  elif command -v sha256sum >/dev/null 2>&1; then
    sha256sum
  else
    echo "Required command 'shasum' or 'sha256sum' is not available." >&2
    exit 1
  fi
}
checkout_key="$(printf '%s' "$repo_root" | sha256_stdin | cut -c1-16)"
lock_dir="$state_base/checkout-$checkout_key.lock"

resolve_mise() {
  local mise_bin
  # `type -P` skips the `mise` shell function that activate_mise defines; `command -v`
  # would return the bare name and make a second activation evaluate an empty command.
  mise_bin="${MISE_BIN:-$(type -P mise 2>/dev/null || true)}"
  [[ -n "$mise_bin" ]] || mise_bin="$HOME/.local/bin/mise"
  [[ -x "$mise_bin" ]] || {
    echo "mise is required. Install it (https://mise.jdx.dev) or set MISE_BIN to its path." >&2
    exit 1
  }
  printf '%s\n' "$mise_bin"
}

if [[ "${1:-}" == "plan" ]]; then
  shift
  cd "$repo_root"
  exec "$(resolve_mise)" exec -- node "$repo_root/.agents/skills/verify-oceans-admin/scripts/plan-verification.mjs" "$@"
fi

if [[ -z "$run_id" || "$run_id" == "." || "$run_id" == ".." || ! "$run_id" =~ ^[A-Za-z0-9._-]+$ ]]; then
  echo "Set OCEANS_VERIFY_RUN_ID to a unique value containing letters, numbers, dots, underscores, or hyphens." >&2
  exit 2
fi

run_dir="$state_base/$run_id"
# Follow the run's recorded listeners even when a later shell only sets its run ID.
if [[ "${1:-}" != "launch" ]]; then
  [[ ! -f "$run_dir/gateway-port" ]] || gateway_port="$(<"$run_dir/gateway-port")"
  [[ ! -f "$run_dir/ui-port" ]] || ui_port="$(<"$run_dir/ui-port")"
fi
evidence_dir="$run_dir/evidence"
stack_pid_file="$run_dir/stack.pid"
gateway_pid_file="$run_dir/gateway.pid"
ui_pid_file="$run_dir/ui.pid"
log_file="$run_dir/stack.log"
base_url="http://127.0.0.1:$gateway_port"
stack_start_file="$run_dir/stack.start-time"
launch_sources_file="$run_dir/launch-sources.json"
stack_env_file="$run_dir/stack-env.json"
proof_script="$repo_root/.agents/skills/verify-oceans-admin/scripts/proof-cli.mjs"

require_command() {
  command -v "$1" >/dev/null 2>&1 || {
    echo "Required command '$1' is not available. Install it before running this verification control." >&2
    exit 1
  }
}

require_command lsof

activate_mise() {
  local mise_bin
  # Cleanup runs with errexit suspended, so stop here instead of evaluating an empty command.
  mise_bin="$(resolve_mise)" || return 1
  eval "$("$mise_bin" activate bash)"
}

listener_pid() {
  lsof -nP -tiTCP:"$1" -sTCP:LISTEN 2>/dev/null | head -1
}

# Prints the checkout that holds a process's working directory: the nearest ancestor of its
# canonical path that contains a `.git` entry. Walking the filesystem instead of asking Git
# keeps the answer independent of Git configuration and environment (a foreign checkout's
# `core.worktree` or an inherited GIT_DIR cannot redirect it), and a nested worktree still
# resolves to its own root because it carries its own `.git` file.
process_checkout() {
  local cwd dir
  cwd="$(lsof -a -p "$1" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p' | head -1)"
  [[ -n "$cwd" ]] || return 1
  dir="$(cd "$cwd" 2>/dev/null && pwd -P)" || return 1
  while [[ -n "$dir" ]]; do
    if [[ -e "$dir/.git" ]]; then
      printf '%s\n' "$dir"
      return 0
    fi
    [[ "$dir" != / ]] || return 1
    dir="$(dirname "$dir")"
  done
  return 1
}

repo_root_physical="$(cd "$repo_root" && pwd -P)"

# Another checkout's stack can bind the selected ports between the in-use check and readiness,
# so only a listener started from this checkout may be recorded, trusted, or signalled.
listener_owned_by_checkout() {
  [[ -n "$1" && "$(process_checkout "$1" || true)" == "$repo_root_physical" ]]
}

describe_listener() {
  local owner
  owner="$(process_checkout "$1" || true)"
  printf 'PID %s from %s' "$1" "${owner:-an unknown working directory}"
}

gateway_uses_this_checkout() {
  lsof -a -c gateway -d cwd -Fn 2>/dev/null | awk -v root="$repo_root" '
    /^p/ { pid=substr($0, 2) }
    /^n/ && substr($0, 2) == root { print pid }
  ' | head -1
}

remove_lock_if_owned() {
  if [[ -f "$lock_dir/run-id" ]] && [[ "$(<"$lock_dir/run-id")" == "$run_id" ]]; then
    rm -f "$lock_dir/run-id" "$lock_dir/pid" "$lock_dir/start-time"
    rmdir "$lock_dir" 2>/dev/null || true
  fi
}

process_start_time() {
  ps -p "$1" -o lstart= 2>/dev/null | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//'
}

lock_is_live() {
  local owner_pid owner_start current_start
  [[ -f "$lock_dir/pid" && -f "$lock_dir/start-time" ]] || return 1
  owner_pid="$(<"$lock_dir/pid")"
  owner_start="$(<"$lock_dir/start-time")"
  current_start="$(process_start_time "$owner_pid")"
  [[ -n "$current_start" && "$current_start" == "$owner_start" ]]
}

record_lock_owner() {
  local owner_pid="$1" owner_start
  owner_start="$(process_start_time "$owner_pid")"
  [[ -n "$owner_start" ]] || {
    echo "Could not record process identity for PID $owner_pid." >&2
    return 1
  }
  printf '%s\n' "$owner_pid" >"$lock_dir/pid"
  printf '%s\n' "$owner_start" >"$lock_dir/start-time"
}

redact_log() {
  local redacted_log
  [[ -f "$log_file" ]] || return 0
  redacted_log="$log_file.redacted"
  sed -E \
    -e 's/^(sample user password:).*/\1 [REDACTED]/' \
    -e 's/(gwk_[A-Za-z0-9]+\.)[^[:space:]]+/\1[REDACTED]/g' \
    "$log_file" >"$redacted_log"
  mv "$redacted_log" "$log_file"
}

# `daemons status` fails until the daemon is registered; `daemons ls` reports it either way.
rustfs_identity() {
  mise -E rustfs daemons ls --json | mise exec -- bun -e '
    const state = (await Bun.stdin.json()).find(daemon => daemon.name === "rustfs");
    if (!state) throw new Error("mise does not define a rustfs daemon for this checkout");
    console.log([state.status, state.pid ?? "-", state.port ?? "-"].join(" "));
  '
}

prepare_skills() {
  local identity daemon_status daemon_pid daemon_port setup_status=0
  identity="$(rustfs_identity)" || {
    echo "Could not read the RustFS daemon state from mise." >&2
    return 1
  }
  read -r daemon_status daemon_pid daemon_port <<<"$identity"
  # `available` is a daemon that is registered or defined but has never started here.
  if [[ "$daemon_pid" == "-" && "$daemon_status" != "stopped" && "$daemon_status" != "available" ]]; then
    echo "RustFS is changing state; wait for it to stop or become ready before launch." >&2
    return 1
  fi
  [[ "$daemon_pid" != "-" ]] || touch "$run_dir/rustfs-owned"
  mise -E rustfs run rustfs:setup || setup_status=$?
  read -r daemon_status daemon_pid daemon_port < <(rustfs_identity)
  if [[ "$daemon_pid" != "-" && -f "$run_dir/rustfs-owned" ]]; then
    printf '%s\n' "$daemon_pid" >"$run_dir/rustfs.pid"
    process_start_time "$daemon_pid" >"$run_dir/rustfs.start-time"
  fi
  [[ "$setup_status" == 0 && "$daemon_pid" != "-" ]] || return 1
  printf '%s\n' "$daemon_port" >"$run_dir/rustfs-port"
  printf '%s\n' "$daemon_pid" >"$run_dir/rustfs-listener.pid"
  printf 'skills-verify/%s/%s/\n' "$checkout_key" "$run_id" >"$run_dir/skills-prefix"

  OCEANS_VERIFY_SKILLS_CONFIG_SOURCE="${GATEWAY_CONFIG:-$repo_root/gateway.yaml}" \
    OCEANS_VERIFY_SKILLS_RUN_DIR="$run_dir" \
    mise -E rustfs exec --fresh-env -- bun -e '
      const fs = await import("node:fs/promises");
      const env = process.env;
      const dir = env.OCEANS_VERIFY_SKILLS_RUN_DIR;
      const config = Bun.YAML.parse(await Bun.file(env.OCEANS_VERIFY_SKILLS_CONFIG_SOURCE).text());
      const endpoint = env.OCEANS_SKILLS_S3_ENDPOINT;
      const bucket = env.OCEANS_RUSTFS_BUCKET;
      if (!/^http:\/\/127\.0\.0\.1:\d+$/.test(endpoint) || !/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(bucket)) {
        throw new Error("Skills verification requires the local RustFS endpoint and a valid bucket name");
      }
      const serviceAccount = config.service_accounts?.find(account => account.id === "local-ci-runner");
      const serviceKey = serviceAccount?.keys?.find(key => key.id === "primary");
      if (!serviceKey) throw new Error("Skills verification requires the seeded local-ci-runner primary key");
      const token = `gwk_verify${crypto.randomUUID().replaceAll("-", "")}.${crypto.randomUUID().replaceAll("-", "")}`;
      serviceKey.value = `literal.${token}`;
      serviceKey.auto_create = false;
      config.database = { path: `${dir}/skills.db` };
      config.skills = {
        enabled: true,
        storage: {
          bucket, region: env.OCEANS_RUSTFS_REGION, endpoint,
          prefix: (await Bun.file(`${dir}/skills-prefix`).text()).trim(),
          force_path_style: true, allow_http: true,
          access_key_id: "env.RUSTFS_ACCESS_KEY", secret_access_key: "env.RUSTFS_SECRET_KEY"
        }
      };
      await fs.writeFile(`${dir}/gateway-skills.yaml`, Bun.YAML.stringify(config), { mode: 0o600 });
      await fs.writeFile(`${dir}/skills-service-account-key`, token, { mode: 0o600 });
      await fs.writeFile(`${dir}/skills-endpoint`, endpoint);
      await fs.writeFile(`${dir}/skills-bucket`, bucket);
      await fs.writeFile(`${dir}/skills-region`, env.OCEANS_RUSTFS_REGION);
    '
  export GATEWAY_CONFIG="$run_dir/gateway-skills.yaml"
}

# Attach the storage result to the Skills proof, so `evidence skills` after
# teardown fails when the run's object prefix or database was left behind.
skills_cleanup_check() {
  local check="storage-cleanup=pass:object prefix empty and private database removed"
  [[ "$1" == 0 ]] || check="storage-cleanup=fail:object prefix or private database retained for retry"
  [[ -f "$evidence_dir/skills-proof.json" ]] || return 0
  activate_mise
  (cd "$repo_root" && OCEANS_VERIFY_EVIDENCE_DIR="$evidence_dir" mise exec -- node "$proof_script" add-check skills-proof.json "$check") ||
    echo "Could not record Skills storage cleanup in skills-proof.json." >&2
}

cleanup_skills() {
  local cleanup_status=0 daemon_status daemon_pid daemon_port stored_pid stored_start
  [[ -f "$run_dir/skills-prefix" || -f "$run_dir/rustfs-owned" ]] || return 0
  activate_mise
  if [[ -f "$run_dir/skills-prefix" && -f "$run_dir/skills-endpoint" ]]; then
    local prefix bucket endpoint region
    prefix="$(<"$run_dir/skills-prefix")"
    bucket="$(<"$run_dir/skills-bucket")"
    endpoint="$(<"$run_dir/skills-endpoint")"
    region="$(<"$run_dir/skills-region")"
    if [[ "$prefix" != "skills-verify/$checkout_key/$run_id/" || ! "$endpoint" =~ ^http://127\.0\.0\.1:[0-9]+$ ]]; then
      echo "Refusing Skills object cleanup because its recorded scope is invalid." >&2
      cleanup_status=1
    elif ! OCEANS_VERIFY_SKILLS_PREFIX="$prefix" OCEANS_VERIFY_SKILLS_BUCKET="$bucket" \
      OCEANS_VERIFY_SKILLS_ENDPOINT="$endpoint" OCEANS_VERIFY_SKILLS_REGION="$region" \
      mise -E rustfs exec --fresh-env -- bash -euc '
        export AWS_ACCESS_KEY_ID="$RUSTFS_ACCESS_KEY" AWS_SECRET_ACCESS_KEY="$RUSTFS_SECRET_KEY"
        export AWS_EC2_METADATA_DISABLED=true AWS_PAGER=""
        unset AWS_SESSION_TOKEN AWS_SECURITY_TOKEN AWS_PROFILE
        args=(--endpoint-url "$OCEANS_VERIFY_SKILLS_ENDPOINT" --region "$OCEANS_VERIFY_SKILLS_REGION" --cli-connect-timeout 5 --cli-read-timeout 10)
        aws "${args[@]}" s3 rm "s3://$OCEANS_VERIFY_SKILLS_BUCKET/$OCEANS_VERIFY_SKILLS_PREFIX" --recursive --only-show-errors
        count="$(aws "${args[@]}" s3api list-objects-v2 --bucket "$OCEANS_VERIFY_SKILLS_BUCKET" --prefix "$OCEANS_VERIFY_SKILLS_PREFIX" --max-keys 1 --query KeyCount --output text)"
        [[ "$count" == 0 ]]
      '; then
      echo "Skills object cleanup failed; its recorded scope is retained for retry." >&2
      cleanup_status=1
    else
      rm -f "$run_dir/skills-prefix"
    fi
  fi
  [[ "$cleanup_status" == 0 ]] || {
    skills_cleanup_check "$cleanup_status"
    return "$cleanup_status"
  }
  if [[ -f "$run_dir/rustfs.pid" && -f "$run_dir/rustfs.start-time" ]]; then
    stored_pid="$(<"$run_dir/rustfs.pid")"
    stored_start="$(<"$run_dir/rustfs.start-time")"
    read -r daemon_status daemon_pid daemon_port < <(rustfs_identity)
    if [[ "$daemon_pid" == "$stored_pid" && "$(process_start_time "$stored_pid" || true)" == "$stored_start" ]]; then
      mise -E rustfs daemons stop rustfs || cleanup_status=1
    fi
  fi
  if [[ "$cleanup_status" == 0 ]]; then
    rm -f "$run_dir/rustfs-owned" "$run_dir/rustfs.pid" "$run_dir/rustfs.start-time" "$run_dir/rustfs-port" "$run_dir/rustfs-listener.pid" \
      "$run_dir/skills-endpoint" "$run_dir/skills-bucket" "$run_dir/skills-region" "$run_dir/gateway-skills.yaml" \
      "$run_dir/skills-prefix" "$run_dir/skills-service-account-key" "$run_dir/skills.db" "$run_dir/skills.db-wal" "$run_dir/skills.db-shm" "$run_dir/skills.db-journal"
  fi
  skills_cleanup_check "$cleanup_status"
  return "$cleanup_status"
}

cleanup() {
  local stored current stored_start current_start cleanup_status=0
  if [[ -f "$stack_pid_file" && -f "$stack_start_file" ]]; then
    stored="$(<"$stack_pid_file")"
    stored_start="$(<"$stack_start_file")"
    current_start="$(process_start_time "$stored" || true)"
    if [[ -n "$current_start" && "$current_start" == "$stored_start" ]]; then
      kill -TERM "$stored" 2>/dev/null || true
      for _ in {1..40}; do
        kill -0 "$stored" 2>/dev/null || break
        sleep 0.25
      done
    fi
  fi

  for spec in "$gateway_pid_file:$gateway_port" "$ui_pid_file:$ui_port"; do
    local pid_file="${spec%%:*}"
    local port="${spec##*:}"
    [[ -f "$pid_file" ]] || continue
    stored="$(<"$pid_file")"
    current="$(listener_pid "$port" || true)"
    if [[ -n "$current" && "$current" == "$stored" ]]; then
      if listener_owned_by_checkout "$stored"; then
        kill -TERM "$stored" 2>/dev/null || true
      else
        echo "Not stopping $(describe_listener "$stored") on port $port; it belongs to another checkout." >&2
      fi
    fi
  done

  if [[ -f "$run_dir/skills-prefix" ]]; then
    for spec in "$gateway_pid_file:$gateway_port" "$ui_pid_file:$ui_port"; do
      local pid_file="${spec%%:*}" port="${spec##*:}"
      [[ -f "$pid_file" ]] || continue
      stored="$(<"$pid_file")"
      for _ in {1..40}; do
        [[ "$(listener_pid "$port" || true)" == "$stored" ]] || break
        sleep 0.25
      done
      if [[ "$(listener_pid "$port" || true)" == "$stored" ]]; then
        echo "Owned listener PID $stored did not stop; retaining Skills storage for retry." >&2
        cleanup_status=1
      fi
    done
    [[ "$cleanup_status" == 0 ]] || skills_cleanup_check "$cleanup_status"
  fi
  if [[ "$cleanup_status" == 0 ]]; then
    cleanup_skills || cleanup_status=$?
  fi
  if [[ "$cleanup_status" == 0 ]]; then
    rm -f "$stack_pid_file" "$stack_start_file" "$gateway_pid_file" "$ui_pid_file" "$run_dir/base-url" "$run_dir/gateway-port" "$run_dir/ui-port" "$run_dir/gateway-version" "$stack_env_file"
    remove_lock_if_owned
  fi
  redact_log
  if [[ "$cleanup_status" == 0 ]]; then
    echo "cleanup complete; evidence retained at $evidence_dir"
  else
    echo "cleanup incomplete; retained state at $run_dir" >&2
  fi
  return "$cleanup_status"
}

# Resolve the environment the way the stack command below does, from mise and this shell,
# and save only the MCP alias names and client base URL. Drivers read this file instead of
# their own environment, which a later shell or `mise exec` from another directory changes.
record_stack_env() {
  local -a stack_exec=(mise exec --)
  [[ "${OCEANS_VERIFY_SKILLS:-false}" != "true" ]] || stack_exec=(mise -E rustfs exec --fresh-env --)
  (cd "$repo_root" && "${stack_exec[@]}" node -e '
    const env = process.env;
    const aliases = Object.keys(env).filter((name) => /^OCEANS_MCP_DISCOVERY_[A-Z0-9_]+$/.test(name) && env[name]).sort();
    console.log(JSON.stringify({ mcpDiscoveryAliases: aliases, clientConfigBaseUrl: env.GATEWAY_CLIENT_CONFIG_BASE_URL ?? null }));
  ') >"$stack_env_file"
}

launch() {
  local existing pid start_time current_gateway current_ui
  mkdir -p "$state_base" "$run_dir" "$evidence_dir"
  chmod 700 "$run_dir"
  if ! mkdir "$lock_dir" 2>/dev/null; then
    if lock_is_live; then
      echo "Refusing to share this checkout database. Active lock: $lock_dir" >&2
      exit 1
    fi
    rm -f "$lock_dir/run-id" "$lock_dir/pid" "$lock_dir/start-time"
    rmdir "$lock_dir" 2>/dev/null || {
      echo "Refusing to replace lock with unexpected contents: $lock_dir" >&2
      exit 1
    }
    mkdir "$lock_dir"
  fi
  printf '%s\n' "$run_id" >"$lock_dir/run-id"
  record_lock_owner "$$"

  abort_launch() {
    local status="${1:-1}"
    trap - EXIT INT TERM
    cleanup
    exit "$status"
  }
  trap 'abort_launch $?' EXIT
  trap 'abort_launch 130' INT
  trap 'abort_launch 143' TERM

  if [[ -n "$(listener_pid "$gateway_port" || true)" || -n "$(listener_pid "$ui_port" || true)" ]]; then
    echo "Refusing to start because port $gateway_port or $ui_port is already in use." >&2
    exit 1
  fi

  existing="$(gateway_uses_this_checkout || true)"
  if [[ -n "$existing" ]]; then
    echo "Refusing to double-drive this checkout. Gateway PID $existing already uses $repo_root." >&2
    exit 1
  fi

  printf '%s\n' "$base_url" >"$run_dir/base-url"
  printf '%s\n' "$gateway_port" >"$run_dir/gateway-port"
  printf '%s\n' "$ui_port" >"$run_dir/ui-port"

  activate_mise
  # Proofs fingerprint the repository's gateway.yaml, so an external config would go unrecorded.
  if [[ -n "${GATEWAY_CONFIG:-}" && "$(cd "$(dirname "$GATEWAY_CONFIG")" 2>/dev/null && pwd)/$(basename "$GATEWAY_CONFIG")" != "$repo_root/gateway.yaml" ]]; then
    echo "Refusing to launch with GATEWAY_CONFIG=$GATEWAY_CONFIG; unset it so the stack uses the repository's gateway.yaml." >&2
    exit 1
  fi
  # Proofs compare against this snapshot, so edits after launch mark them stale.
  (cd "$repo_root" && OCEANS_VERIFY_EVIDENCE_DIR="$evidence_dir" mise exec -- node "$proof_script" snapshot-sources "$launch_sources_file")
  if [[ "${OCEANS_VERIFY_SKILLS:-false}" == "true" ]]; then
    prepare_skills
  fi
  # Generated MCP client configuration points at this run's gateway unless the caller chose another origin.
  export GATEWAY_CLIENT_CONFIG_BASE_URL="${GATEWAY_CLIENT_CONFIG_BASE_URL:-$base_url}"
  record_stack_env
  (
    cd "$repo_root"
    export GATEWAY_PORT="$gateway_port"
    export UI_PORT="$ui_port"
    if [[ "${OCEANS_VERIFY_SKILLS:-false}" == "true" ]]; then
      exec mise -E rustfs exec --fresh-env -- mise run dev-stack
    fi
    exec mise run dev-stack
  ) >"$log_file" 2>&1 &
  pid=$!
  start_time="$(process_start_time "$pid")"
  [[ -n "$start_time" ]] || {
    echo "Could not record process identity for the launched dev stack." >&2
    exit 1
  }
  printf '%s\n' "$pid" >"$stack_pid_file"
  printf '%s\n' "$start_time" >"$stack_start_file"
  record_lock_owner "$pid"

  local ready=false spec port listener
  for _ in {1..600}; do
    current_gateway="$(listener_pid "$gateway_port" || true)"
    current_ui="$(listener_pid "$ui_port" || true)"
    for spec in "$gateway_port:$current_gateway" "$ui_port:$current_ui"; do
      port="${spec%%:*}"
      listener="${spec#*:}"
      if [[ -n "$listener" ]] && ! listener_owned_by_checkout "$listener"; then
        echo "Port $port was taken by $(describe_listener "$listener") while this stack started. See $log_file" >&2
        exit 1
      fi
    done
    [[ -z "$current_gateway" ]] || printf '%s\n' "$current_gateway" >"$gateway_pid_file"
    [[ -z "$current_ui" ]] || printf '%s\n' "$current_ui" >"$ui_pid_file"

    # dev-stack runs the gateway in the foreground, so its exit means the stack is gone.
    if ! kill -0 "$pid" 2>/dev/null; then
      echo "The dev stack exited before it became ready. See $log_file" >&2
      exit 1
    fi
    if [[ -n "$current_gateway" && -n "$current_ui" ]] && curl --silent --fail --max-time 5 "$base_url/readyz" >/dev/null 2>&1; then
      ready=true
      break
    fi
    sleep 0.5
  done

  if [[ "$ready" != true ]]; then
    echo "The dev stack did not become ready. See $log_file" >&2
    exit 1
  fi

  doctor
  trap - EXIT INT TERM
  echo "ready: $base_url/admin/login"
}

doctor() {
  local recorded_gateway current_gateway recorded_ui current_ui health version pid
  [[ -f "$gateway_pid_file" && -f "$ui_pid_file" ]] || {
    echo "No launched verification instance is recorded for run $run_id." >&2
    exit 1
  }
  recorded_gateway="$(<"$gateway_pid_file")"
  recorded_ui="$(<"$ui_pid_file")"
  current_gateway="$(listener_pid "$gateway_port" || true)"
  current_ui="$(listener_pid "$ui_port" || true)"
  [[ "$current_gateway" == "$recorded_gateway" ]] || {
    echo "Port $gateway_port is not owned by recorded gateway PID $recorded_gateway." >&2
    exit 1
  }
  [[ "$current_ui" == "$recorded_ui" ]] || {
    echo "Port $ui_port is not owned by recorded UI PID $recorded_ui." >&2
    exit 1
  }
  for pid in "$recorded_gateway" "$recorded_ui"; do
    listener_owned_by_checkout "$pid" || {
      echo "Recorded $(describe_listener "$pid") does not belong to $repo_root_physical." >&2
      exit 1
    }
  done
  if [[ -f "$run_dir/rustfs-listener.pid" ]]; then
    local rustfs_port recorded_rustfs
    rustfs_port="$(<"$run_dir/rustfs-port")"
    recorded_rustfs="$(<"$run_dir/rustfs-listener.pid")"
    [[ "$(listener_pid "$rustfs_port" || true)" == "$recorded_rustfs" ]] || {
      echo "RustFS port $rustfs_port is not owned by recorded PID $recorded_rustfs." >&2
      exit 1
    }
    curl --silent --fail --max-time 2 "$(<"$run_dir/skills-endpoint")/health/ready" >/dev/null
  fi
  curl --silent --fail --max-time 5 "$base_url/readyz" | grep -q '"status":"ready"'
  health="$(curl --silent --fail --max-time 5 "$base_url/api/v1/health")"
  version="$(printf '%s' "$health" | sed -n 's/.*"version":"\([^"]*\)".*/\1/p')"
  [[ -n "$version" ]] || {
    echo "Gateway health did not include a version: $health" >&2
    exit 1
  }
  printf '%s\n' "$version" >"$run_dir/gateway-version"
  echo "doctor ok: gateway $version at $base_url, gateway PID $recorded_gateway, UI PID $recorded_ui"
}

# The harness suite builds and starts its own gateway, so it needs no launched stack.
# Its source snapshot is taken here, right before the suite builds from this checkout.
# `mise activate` would revert variables an outer mise shell set, OPENROUTER_API_KEY
# included, so this calls `mise exec` and `mise run` directly.
drive_harness_integration() {
  local sources_file="$run_dir/harness-sources.json" version mise_bin
  mise_bin="$(resolve_mise)"
  mkdir -p "$evidence_dir"
  (cd "$repo_root" && OCEANS_VERIFY_EVIDENCE_DIR="$evidence_dir" "$mise_bin" exec -- node "$proof_script" snapshot-sources "$sources_file")
  version="$(awk '/^version = / { gsub(/"/, "", $3); print $3; exit }' "$repo_root/crates/gateway/Cargo.toml")"
  (cd "$repo_root" && "$mise_bin" run //harness:install)
  cd "$repo_root"
  OCEANS_VERIFY_EVIDENCE_DIR="$evidence_dir" \
    OCEANS_VERIFY_LAUNCH_SOURCES="$sources_file" \
    OCEANS_VERIFY_GATEWAY_VERSION="$version" \
    "$mise_bin" exec -- node "$repo_root/.agents/skills/verify-oceans-admin/scripts/drive-harness-integration.mjs"
}

drive() {
  local target="${1:-}" driver
  case "$target" in
    models) driver="drive-models.mjs" ;;
    observability) driver="drive-observability.mjs" ;;
    backend-gateway) driver="drive-backend-gateway.mjs" ;;
    service-tiers) driver="drive-service-tiers.mjs" ;;
    harness-integration)
      drive_harness_integration
      return
      ;;
    mcp) driver="drive-mcp.mjs" ;;
    profile) driver="drive-profile.mjs" ;;
    skills) driver="drive-skills.mjs" ;;
    *)
      echo "Supported drive targets: models, observability, backend-gateway, service-tiers, harness-integration, mcp, profile, skills" >&2
      exit 2
      ;;
  esac
  doctor
  if [[ "$target" == "skills" ]]; then
    [[ -f "$run_dir/skills-prefix" ]] || {
      echo "Skills verification requires launch with OCEANS_VERIFY_SKILLS=true." >&2
      exit 1
    }
    export OCEANS_VERIFY_SKILLS_PREFIX="$(<"$run_dir/skills-prefix")"
    export OCEANS_VERIFY_SKILLS_BUCKET="$(<"$run_dir/skills-bucket")"
    export OCEANS_VERIFY_SKILLS_ENDPOINT="$(<"$run_dir/skills-endpoint")"
    export OCEANS_VERIFY_SKILLS_SERVICE_ACCOUNT_KEY="$(<"$run_dir/skills-service-account-key")"
  fi
  activate_mise
  mise run //ui:e2e:install
  if [[ "$target" == "skills" ]]; then
    mise run //cli:build
  fi
  OCEANS_VERIFY_BASE_URL="$base_url" \
    OCEANS_VERIFY_EVIDENCE_DIR="$evidence_dir" \
    OCEANS_VERIFY_LAUNCH_SOURCES="$launch_sources_file" \
    OCEANS_VERIFY_STACK_ENV="$stack_env_file" \
    OCEANS_VERIFY_GATEWAY_VERSION="$(<"$run_dir/gateway-version")" \
    OCEANS_VERIFY_ADMIN_EMAIL="${OCEANS_VERIFY_ADMIN_EMAIL:-admin@local}" \
    OCEANS_VERIFY_ADMIN_PASSWORD="${OCEANS_VERIFY_ADMIN_PASSWORD:-admin}" \
    mise exec -- node "$repo_root/.agents/skills/verify-oceans-admin/scripts/$driver"
}

proof_cli() {
  cd "$repo_root"
  # Cleanup removes gateway-version, so record manual proofs before cleanup.
  [[ ! -f "$run_dir/gateway-version" ]] || export OCEANS_VERIFY_GATEWAY_VERSION="$(<"$run_dir/gateway-version")"
  OCEANS_VERIFY_EVIDENCE_DIR="$evidence_dir" OCEANS_VERIFY_LAUNCH_SOURCES="$launch_sources_file" \
    exec "$(resolve_mise)" exec -- node "$proof_script" "$@"
}

case "${1:-}" in
  launch) launch ;;
  doctor) doctor ;;
  drive) drive "${2:-}" ;;
  evidence | record | report) proof_cli "$@" ;;
  cleanup) cleanup ;;
  *)
    echo "Usage: $0 {plan [base-ref] [--json]|launch|doctor|drive {models|observability|backend-gateway|service-tiers|harness-integration|mcp|profile|skills}|evidence [feature...] [--require-current]|record <feature> --check id=status[:note] --artifact file|report [--plan [base-ref]]|cleanup}" >&2
    exit 2
    ;;
esac
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall