# Sentinel AI Path — Operational Checklists

> **For AI agents.** Run these checklists programmatically before, during, and after VPN operations. Every check includes the exact code, expected result, and failure response. Assume the wallet has sufficient P2P for bandwidth consumption.

---

## How to Use

```javascript
import {
  setup, getEnvironment, createWallet, importWallet, getBalance,
  discoverNodes, getNodeInfo, getNetworkStats,
  estimateCost, PRICING, recommend,
  connect, disconnect, status, isVpnActive, verify, onEvent,
} from './index.js'; // or 'sentinel-ai-connect' when published to npm
```

Each checklist item has:
- **Check**: what to verify
- **Code**: exact call
- **Pass**: expected result
- **Fail**: what the failure means and what to do

Run all checks in order. Stop at the first `CRITICAL` failure. `WARNING` items can be bypassed with degraded capability.

---

## Checklist 1: Pre-Flight (Before Any Connection)

Run once per session. Verifies the machine can operate.

### 1.1 Node.js Version

```javascript
const [major] = process.versions.node.split('.').map(Number);
```

| | |
|---|---|
| **Pass** | `major >= 20` |
| **Fail** | CRITICAL. Node.js 20+ required for stable ESM, `crypto.randomUUID`, and `AbortSignal.timeout`. Upgrade Node.js. |

### 1.2 Environment Detection

```javascript
const env = getEnvironment();
```

| Check | Pass | Fail |
|-------|------|------|
| `env.v2ray.available` | `true` | WARNING. Run `setup()` to download V2Ray 5.2.1. Without V2Ray, only WireGuard nodes work. |
| `env.v2ray.version` | Starts with `'5.2'` | WARNING. V2Ray 5.44.1+ has observatory bugs that break VMess. Delete and redownload 5.2.1. |
| `env.wireguard.available` | `true` | WARNING. WireGuard not installed. Limited to V2Ray nodes (~70% of network). |
| `env.admin` | `true` | WARNING. Not admin. WireGuard tunnel installation will be blocked. V2Ray still works. |
| `env.capabilities.length` | `> 0` | CRITICAL. No tunnel protocol available. Install V2Ray or WireGuard before proceeding. |

### 1.3 Full System Check

```javascript
const check = await setup();
```

| Check | Pass | Fail |
|-------|------|------|
| `check.ready` | `true` | See `check.issues` array for specific problems. |
| `check.issues.length` | `0` | Review each issue: `issue.severity`, `issue.message`, `issue.action`. Fix `error` severity items. `warning` items are non-blocking. |
| `check.preflight.ok` | `true` | Preflight found blockers. Check `check.preflight.issues` for details. |
| `check.preflight.ready.anyProtocol` | `true` | CRITICAL. Neither WireGuard nor V2Ray is operational. |

### 1.4 Orphan Detection

```javascript
const pf = check.preflight;
const orphans = pf.issues.filter(i => i.component === 'wireguard' && i.message.includes('orphan'));
const conflicts = pf.issues.filter(i => i.component === 'system');
```

| Check | Pass | Fail |
|-------|------|------|
| `orphans.length` | `0` | WARNING. Leftover WireGuard tunnels from a previous crash. Run `setup()` with autoClean or manually uninstall: `wireguard.exe /uninstalltunnelservice wgsent0` |
| `conflicts.length` | `0` | WARNING. Conflicting VPN software detected (NordVPN, ExpressVPN, etc.). May interfere with tunnel routing. |

### 1.5 Axios Adapter

```javascript
const axios = (await import('axios')).default;
const adapterOk = axios.defaults.adapter === 'http';
if (!adapterOk) axios.defaults.adapter = 'http';
```

| Check | Pass | Fail |
|-------|------|------|
| Adapter is `'http'` | `true` | Auto-fixed above. Without this, Node.js 20+ uses fetch adapter which silently fails on self-signed node certificates. The `connect()` function handles this automatically, but verify if making direct SDK calls. |

---

## Checklist 2: Wallet & Funding

Run before every connection attempt.

### 2.1 Wallet Valid

```javascript
const bal = await getBalance(process.env.MNEMONIC);
```

| Check | Pass | Fail |
|-------|------|------|
| No exception thrown | Call succeeds | CRITICAL. If `INVALID_MNEMONIC`: check word count (must be 12 or 24), check for typos, verify BIP39 English wordlist. If network error: LCD endpoints may be down — retry in 30s. |
| `bal.address` starts with `'sent1'` | `true` | CRITICAL. Wrong address prefix means wrong chain derivation. |
| `bal.address.length >= 43 && bal.address.length <= 46` | `true` | CRITICAL. Malformed address — expected 43-46 characters. |

### 2.2 Balance Sufficient

```javascript
const { funded, udvpn, p2p } = bal;
```

| Check | Pass | Fail |
|-------|------|------|
| `funded` | `true` | CRITICAL. Balance below 1.0 P2P. Fund wallet at `bal.address`. Prices vary — use `estimateCost()` to check if current balance covers at least one session. |
| `udvpn > 0` | `true` | CRITICAL. Wallet is empty. Send P2P tokens to `bal.address`. |

### 2.3 Cost Estimation

```javascript
const cost = await estimateCost({ gigabytes: 1 });
const canAfford = bal.udvpn >= cost.grandTotal.udvpn;
```

| Check | Pass | Fail |
|-------|------|------|
| `canAfford` | `true` | CRITICAL. Balance `${bal.p2p}` insufficient for 1 GB session costing ~`${cost.grandTotal.p2p}`. Fund wallet with at least `${cost.grandTotal.p2p}`. |
| `cost.mode` | Any value returned | If exception: network issue querying node prices. Proceed with `funded: true` as a fallback estimate. |

---

## Checklist 3: Network Reachability

Run before connection to verify chain infrastructure is accessible.

### 3.1 LCD Endpoint

```javascript
const res = await fetch('https://lcd.sentinel.co/cosmos/bank/v1beta1/balances/' + bal.address, {
  signal: AbortSignal.timeout(10000),
});
```

| Check | Pass | Fail |
|-------|------|------|
| `res.ok` | `true` | WARNING. Primary LCD down. The SDK has 4 failover endpoints and handles this automatically. If all 4 fail, check your internet connection. |

### 3.2 Node Discovery

```javascript
const nodes = await discoverNodes({ quick: true });
```

| Check | Pass | Fail |
|-------|------|------|
| `nodes.length > 0` | `true` | CRITICAL. Zero nodes returned. Chain may be down or LCD endpoints unreachable. Retry in 60s. |
| `nodes.length > 100` | `true` | WARNING. Unusually few nodes. Possible pagination issue or chain maintenance. Connection may still work. |

### 3.3 Network Health

```javascript
const stats = await getNetworkStats();
```

| Check | Pass | Fail |
|-------|------|------|
| `stats.totalNodes > 0` | `true` | CRITICAL. Network appears empty. |
| `stats.byProtocol.v2ray > 0` or `stats.byProtocol.wireguard > 0` | At least one `> 0` | CRITICAL. No nodes available for any protocol. |

---

## Checklist 4: Connection

Run during the `connect()` call. Use `onProgress` to track each phase.

### 4.1 Progress Monitoring

```javascript
const phases = new Set();
let lastPhase = null;
let lastError = null;

const vpn = await connect({
  mnemonic: process.env.MNEMONIC,
  // fullTunnel: true (default) for privacy, or protocol: 'v2ray' for per-app split tunnel
  onProgress: (step, detail) => {
    phases.add(step);
    lastPhase = step;
    // Log for diagnostics: console.log(`[${step}] ${detail}`);
  },
});
```

### 4.2 Phase Completion Verification

After `connect()` returns successfully, verify all critical phases were reached:

| Phase | Expected in `phases` | If Missing |
|-------|---------------------|------------|
| `'wallet'` | Yes | CRITICAL. Wallet derivation never started. Check mnemonic. |
| `'session'` | Yes | CRITICAL. Node selection or payment never started. Check balance, check node availability. |
| `'handshake'` | Yes | CRITICAL. Handshake phase never reached. Payment may have failed — check `lastError`. Session may exist on-chain (tokens spent). |
| `'tunnel'` | Yes | CRITICAL. Tunnel installation never started. Handshake may have failed. |
| `'verify'` | Yes | WARNING. Verification phase was skipped. Tunnel may still work — proceed to manual verification (Checklist 5). |

### 4.3 Connect Result Validation

```javascript
const { sessionId, protocol, nodeAddress, socksPort, ip } = vpn;
```

| Check | Pass | Fail |
|-------|------|------|
| `sessionId` defined and non-empty | `true` | CRITICAL. No session ID means the blockchain TX may have failed. Check wallet balance — if it decreased, the session exists but ID extraction failed. |
| `protocol` is `'wireguard'` or `'v2ray'` | `true` | WARNING. Unknown protocol `'${protocol}'`. Connection may still work. |
| `nodeAddress` starts with `'sentnode1'` | `true` | WARNING. Node address missing or malformed. Connection may still work if sessionId is valid. |
| If V2Ray: `socksPort` is a number > 0 | `true` | WARNING. No SOCKS5 port. V2Ray may not be routing traffic. Verify manually. |
| `ip !== null` | `true` | WARNING. IP verification failed (ipify.org may be unreachable through this node). Tunnel may still work. Run Checklist 5 to confirm. |
| `ip !== yourOriginalIp` | `true` | WARNING. IP didn't change. Possible split tunnel mode or full tunnel not installed. May be expected if `fullTunnel: false`. |

---

## Checklist 5: Post-Connection Verification

Run immediately after `connect()` succeeds. Confirms the tunnel is actually working.

### 5.1 Connection State

```javascript
const active = isVpnActive();
const st = status();
```

| Check | Pass | Fail |
|-------|------|------|
| `active` | `true` | CRITICAL. `isVpnActive()` returns false immediately after connect. Tunnel may have collapsed. Disconnect and retry with a different node. |
| `st.connected` | `true` | CRITICAL. Same as above — status shows disconnected. |
| `st.sessionId` matches `vpn.sessionId` | `true` | WARNING. Session ID mismatch. State may be stale. |
| `st.protocol` matches `vpn.protocol` | `true` | WARNING. Protocol mismatch. Likely a state tracking issue — tunnel may still work. |

### 5.2 Traffic Verification

```javascript
const v = await verify();
```

| Check | Pass | Fail |
|-------|------|------|
| `v.connected` | `true` | CRITICAL. Tunnel down during verification. |
| `v.verified` | `true` | CRITICAL. Cannot confirm traffic flows through the tunnel. The tunnel may be installed but not routing. Disconnect and try a different node. |
| `v.ip !== null` | `true` | WARNING. IP check failed but `verified` may still be true from SDK verification. If both `ip === null` and `verified === false`, the tunnel is dead. |

### 5.3 Data Transfer Test

```javascript
let testRes;
if (vpn.socksPort) {
  // V2Ray: test through SOCKS5 proxy
  const axios = (await import('axios')).default;
  const { SocksProxyAgent } = await import('socks-proxy-agent');
  const agent = new SocksProxyAgent(`socks5h://127.0.0.1:${vpn.socksPort}`);
  testRes = await axios.get('https://api.ipify.org?format=json', {
    httpAgent: agent, httpsAgent: agent, timeout: 15000, adapter: 'http',
  });
} else {
  // WireGuard: traffic routes automatically through the tunnel
  const axios = (await import('axios')).default;
  testRes = await axios.get('https://api.ipify.org?format=json', {
    timeout: 15000, adapter: 'http',
  });
}
```

| Check | Pass | Fail |
|-------|------|------|
| Response received within timeout | `true` | WARNING. Tunnel may be slow or congested. Increase timeout to 30s and retry once. If still fails, try a different node. |
| `testRes.data.ip` is not your real IP | `true` | CRITICAL (WireGuard full tunnel). Traffic is not routing through the VPN. NORMAL (V2Ray split tunnel) — only SOCKS5-proxied traffic routes through the tunnel. |
| `testRes.status === 200` | `true` | WARNING. Non-200 response. The test endpoint may be down. Try `https://ifconfig.me` as fallback. |

### 5.4 DNS Leak Check

```javascript
// Verify DNS resolves through the tunnel, not your ISP
const dnsRes = await axios.get('https://1.1.1.1/cdn-cgi/trace', {
  httpAgent: agent, httpsAgent: agent, timeout: 10000, adapter: 'http', // V2Ray
  // For WireGuard: omit agents, DNS is enforced by tunnel config
});
```

| Check | Pass | Fail |
|-------|------|------|
| Response received | `true` | WARNING. Cloudflare trace endpoint unreachable. DNS may still be correct — this is a secondary check. |
| Response does not contain your real ISP IP | `true` | WARNING. Possible DNS leak. If using WireGuard, check that `DNS = 10.8.0.1` is in the config. If using V2Ray, verify SOCKS5 proxy is routing DNS queries. |

---

## Checklist 6: Runtime Health Monitoring

Run periodically while connected (every 30-60 seconds).

### 6.1 Connection Still Active

```javascript
const alive = isVpnActive();
const st = status();
```

| Check | Pass | Fail |
|-------|------|------|
| `alive` | `true` | CRITICAL. Connection lost. Begin reconnection (Checklist 8). |
| `st.connected` | `true` | CRITICAL. Same — status shows disconnected. |
| `st.uptimeMs > previousUptimeMs` | `true` | WARNING. Uptime not advancing. State may be stale. Verify with `verify()`. |

### 6.2 Traffic Still Flows

```javascript
const v = await verify();
```

| Check | Pass | Fail |
|-------|------|------|
| `v.verified` | `true` | CRITICAL. Tunnel is up but traffic has stopped flowing. Disconnect and reconnect. |
| Time since last successful verify < 120s | `true` | WARNING. Verification hasn't succeeded in 2+ minutes. Network may be degrading. |

### 6.3 Balance Monitor (Every 5 Minutes)

```javascript
const bal = await getBalance(process.env.MNEMONIC);
```

| Check | Pass | Fail |
|-------|------|------|
| `bal.funded` | `true` | WARNING. Balance dropping below threshold. Plan for disconnection or top-up. Session continues until data allocation is consumed, but new sessions cannot be created. |
| `bal.udvpn > previousBalance - expectedConsumption` | `true` | INFO. Track spend rate. If balance is dropping faster than expected, session may have an issue. |

---

## Checklist 7: Disconnection

Run when work is complete or on shutdown.

### 7.1 Graceful Disconnect

```javascript
const result = await disconnect();
```

| Check | Pass | Fail |
|-------|------|------|
| `result.disconnected` | `true` | WARNING. Disconnect reported failure, but tunnel is likely down. Proceed to verification. |
| No exception thrown | `true` | WARNING. Best-effort — the tunnel was probably torn down. Continue to post-disconnect verification. |

### 7.2 Post-Disconnect Verification

```javascript
const active = isVpnActive();
const st = status();
```

| Check | Pass | Fail |
|-------|------|------|
| `active` | `false` | CRITICAL. Tunnel still active after disconnect. Orphaned tunnel. Attempt: `await disconnect()` again. If still active, escalate to manual cleanup (7.3). |
| `st.connected` | `false` | CRITICAL. Same — state still shows connected. |

### 7.3 Orphan Cleanup (If 7.2 Fails)

```javascript
import { emergencyCleanupSync } from 'sentinel-dvpn-sdk';
emergencyCleanupSync();
```

| Check | Pass | Fail |
|-------|------|------|
| After cleanup: `isVpnActive() === false` | `true` | CRITICAL. Orphaned tunnel survived emergency cleanup. Manual intervention required: `wireguard.exe /uninstalltunnelservice wgsent0` (WireGuard) or kill V2Ray process by PID (NOT `taskkill /F /IM node.exe` — that kills your own process). |

### 7.4 System State Clean

```javascript
// Verify no system proxy left behind (V2Ray)
// On Windows, check registry or run:
// netsh winhttp show proxy
```

| Check | Pass | Fail |
|-------|------|------|
| No system proxy pointing to dead SOCKS5 port | `true` | WARNING. Orphaned system proxy will break system HTTP traffic. Clear it: `netsh winhttp reset proxy` |

---

## Checklist 8: Error Recovery

Run when any connection attempt fails or when runtime health check fails.

### 8.1 Classify the Error

```javascript
try {
  await connect(opts);
} catch (err) {
  const code = err.code || 'UNKNOWN';
  const msg = err.message;
}
```

| Error Code | Severity | Recovery Action |
|------------|----------|----------------|
| `INVALID_MNEMONIC` | Fatal | Fix mnemonic. Do not retry. |
| `INSUFFICIENT_BALANCE` | Fatal | Fund wallet. Do not retry until funded. |
| `ALREADY_CONNECTED` | Fatal | Call `disconnect()` first, then retry. |
| `ABORTED` | Fatal | Timeout or cancellation. Increase `timeout` or check network. |
| `SESSION_POISONED` | Fatal | Previous session is corrupted. Do not reuse. Fresh connection needed. |
| `NODE_OFFLINE` | Retryable | Try a different node. |
| `NODE_CLOCK_DRIFT` | Retryable | Skip this node. Try another. |
| `V2RAY_ALL_FAILED` | Retryable | All transports failed. Try a WireGuard node or different V2Ray node. |
| `WG_NO_CONNECTIVITY` | Retryable | Tunnel installed but dead. Try a different node. |
| `BROADCAST_FAILED` | Retryable | Chain TX failed. Wait 30s, retry. |
| `ALL_NODES_FAILED` | Retryable | Every candidate failed. Wait 60s, retry with different country or protocol. |
| `ALL_ENDPOINTS_FAILED` | Retryable | LCD/RPC all down. Check internet. Wait 60s, retry. |
| `V2RAY_NOT_FOUND` | Setup | Run `setup()` to install V2Ray binary. |
| `WG_NOT_AVAILABLE` | Setup | Install WireGuard or retry with `protocol: 'v2ray'`. |
| `SESSION_EXISTS` | Recoverable | Active session found. SDK reuses it automatically. If it keeps failing, wait for session expiry. |
| `PARTIAL_CONNECTION_FAILED` | Recoverable | Payment succeeded but tunnel failed. Session exists on-chain. Retry connection to same node — session will be reused (no double payment). |

### 8.2 Retry Strategy

```javascript
const MAX_RETRIES = 3;
const BACKOFF = [5000, 10000, 20000]; // ms

for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
  try {
    const vpn = await connect(opts);
    // Run Checklist 4 + 5
    break; // Success
  } catch (err) {
    if (['INVALID_MNEMONIC', 'INSUFFICIENT_BALANCE', 'ABORTED'].includes(err.code)) {
      throw err; // Fatal — do not retry
    }
    if (attempt < MAX_RETRIES - 1) {
      await new Promise(r => setTimeout(r, BACKOFF[attempt]));
    } else {
      throw err; // Exhausted retries
    }
  }
}
```

### 8.3 Post-Failure Cleanup

After any failed connection attempt:

```javascript
// Always verify no orphaned state
try { await disconnect(); } catch { /* best effort */ }
const stillActive = isVpnActive();
if (stillActive) {
  const { emergencyCleanupSync } = await import('sentinel-dvpn-sdk');
  emergencyCleanupSync();
}
```

| Check | Pass | Fail |
|-------|------|------|
| `isVpnActive() === false` after cleanup | `true` | Orphaned tunnel exists. See Checklist 7.3. |

---

## Checklist 9: Full End-to-End Validation

Run this as a single script to verify the entire pipeline works. This is the definitive test.

```javascript
// Load mnemonic from .env (use dotenv or manual parsing)
// import 'dotenv/config';  // Requires: npm install dotenv
import {
  setup, getEnvironment, getBalance, estimateCost, recommend,
  connect, disconnect, status, isVpnActive, verify,
} from './index.js'; // or 'sentinel-ai-connect' when published to npm

const results = {
  preflight: false,
  wallet: false,
  balance: false,
  costEstimate: false,
  recommendation: false,
  connection: false,
  stateConsistent: false,
  trafficVerified: false,
  disconnection: false,
  cleanState: false,
};

try {
  // ── Preflight ──
  const env = getEnvironment();
  if (env.capabilities.length === 0) throw new Error('No tunnel protocol available');
  const check = await setup();
  if (!check.ready) throw new Error(`Setup issues: ${check.issues.join(', ')}`);
  results.preflight = true;

  // ── Wallet ──
  const bal = await getBalance(process.env.MNEMONIC);
  if (!bal.address.startsWith('sent1')) throw new Error('Bad address');
  results.wallet = true;

  // ── Balance ──
  if (!bal.funded) throw new Error(`Underfunded: ${bal.p2p}`);
  results.balance = true;

  // ── Cost Estimate ──
  const cost = await estimateCost({ gigabytes: 1 });
  if (bal.udvpn < cost.grandTotal.udvpn) throw new Error(`Need ${cost.grandTotal.p2p}, have ${bal.p2p}`);
  results.costEstimate = true;

  // ── Recommendation ──
  const rec = await recommend({ priority: 'reliability' });
  if (rec.action === 'cannot-connect') throw new Error('No nodes available');
  results.recommendation = true;

  // ── Connection ──
  const phases = new Set();
  const vpn = await connect({
    mnemonic: process.env.MNEMONIC,
    fullTunnel: false,
    onProgress: (step) => phases.add(step),
    timeout: 120000,
  });
  if (!vpn.sessionId) throw new Error('No session ID');
  if (!phases.has('wallet')) throw new Error('Wallet phase missing');
  if (!phases.has('session')) throw new Error('Session phase missing');
  if (!phases.has('handshake')) throw new Error('Handshake phase missing');
  if (!phases.has('tunnel')) throw new Error('Tunnel phase missing');
  results.connection = true;

  // ── State Consistency ──
  const st = status();
  if (!st.connected) throw new Error('Status says disconnected after connect');
  if (!isVpnActive()) throw new Error('isVpnActive false after connect');
  if (st.sessionId !== vpn.sessionId) throw new Error('Session ID mismatch');
  results.stateConsistent = true;

  // ── Traffic Verification ──
  const v = await verify();
  if (!v.verified) throw new Error('Traffic verification failed');
  results.trafficVerified = true;

  // ── Disconnection ──
  await disconnect();
  results.disconnection = true;

  // ── Clean State ──
  if (isVpnActive()) throw new Error('Still active after disconnect');
  if (status().connected) throw new Error('Status still connected after disconnect');
  results.cleanState = true;

} catch (err) {
  console.error(`FAILED: ${err.message} (code: ${err.code || 'none'})`);
} finally {
  // Ensure cleanup even on failure
  try { await disconnect(); } catch {}
}

// ── Report ──
console.log('\n═══ End-to-End Checklist Results ═══');
const entries = Object.entries(results);
const passed = entries.filter(([, v]) => v).length;
const total = entries.length;

for (const [name, ok] of entries) {
  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}`);
}

console.log(`\n  ${passed}/${total} checks passed.`);
if (passed === total) {
  console.log('  All systems operational. AI Path is fully functional.');
} else {
  const firstFail = entries.find(([, v]) => !v)?.[0];
  console.log(`  First failure: ${firstFail}. Fix this before retrying.`);
}
```

### Expected Output (All Pass)

```
═══ End-to-End Checklist Results ═══
  PASS  preflight
  PASS  wallet
  PASS  balance
  PASS  costEstimate
  PASS  recommendation
  PASS  connection
  PASS  stateConsistent
  PASS  trafficVerified
  PASS  disconnection
  PASS  cleanState

  10/10 checks passed.
  All systems operational. AI Path is fully functional.
```

---

## Quick Reference: Which Checklist When

| Situation | Run |
|-----------|-----|
| First time using AI Path | Checklist 1 (preflight) → 2 (wallet) → 3 (network) → 9 (full E2E) |
| Before each connection | Checklist 2.2 (balance) → 4 (connection) → 5 (post-connect) |
| While connected (every 30-60s) | Checklist 6 (health) |
| Connection fails | Checklist 8 (error recovery) |
| Shutting down | Checklist 7 (disconnection) |
| After crash or unexpected restart | Checklist 1.4 (orphan detection) → 7.3 (orphan cleanup) |
| Validating a new environment | Checklist 9 (full E2E) |