ahstn/oceans-llm / .agents/skills/verify-oceans-admin
verify-oceans-admin
VerifiedVerify 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.
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |