chittyos
diff --git a/‎src/index.ts‎
Lines changed: 8 additions & 7 deletions b/‎src/index.ts‎
Lines changed: 8 additions & 7 deletions
diff --git a/‎src/routes/health.ts‎
Lines changed: 173 additions & 0 deletions b/‎src/routes/health.ts‎
Lines changed: 173 additions & 0 deletions
diff --git a/‎tests/health/health-probe.spec.ts‎
Lines changed: 74 additions & 0 deletions b/‎tests/health/health-probe.spec.ts‎
Lines changed: 74 additions & 0 deletions
@@ -33,6 +33,7 @@ import { tokenManagementRoutes } from './routes/token-management';
 import { jobRoutes } from './routes/jobs';
 import { transactionRoutes } from './routes/transactions';
 import { timelineRoutes } from './routes/timeline';
+import { runHealthProbes } from './routes/health';
 
 // Re-export ActionAgent DO class so the runtime can find it
 export { ActionAgent } from './agents/action-agent';
@@ -92,13 +93,13 @@ app.notFound((c) => {
   return c.json({ error: 'Not Found' }, 404);
 });
 
-// Health endpoint (unauthenticated)
-app.get('/health', (c) => c.json({
-  status: 'ok',
-  service: 'chittycommand',
-  version: '0.1.0',
-  timestamp: new Date().toISOString(),
-}));
+// Health endpoint (unauthenticated) — real dependency probes (db, chittyconnect,
+// daemon heartbeat). See src/routes/health.ts. Returns 503 only if the DB is
+// down; chittyconnect/daemon problems surface as `degraded` with 200.
+app.get('/health', async (c) => {
+  const { body, httpStatus } = await runHealthProbes(c.env);
+  return c.json(body, httpStatus);
+});
 
 // Service status (unauthenticated) — ChittyOS standard
 app.get('/api/v1/status', (c) => c.json({
 
@@ -0,0 +1,173 @@
+/**
+ * /health — real-dependency probe handler.
+ *
+ * Extracted from src/index.ts so it can be unit/integration-tested in pure
+ * Node without dragging in `cloudflare:`-namespaced imports (Agents SDK,
+ * Durable Objects, etc.) that only resolve under wrangler/workerd.
+ *
+ * Probes (each per-dep timeout 2000ms; total ≤ ~5000ms via Promise.all):
+ *   - db            SELECT 1 via Neon HTTP driver.  Critical: failure → 503.
+ *   - chittyconnect GET ${CHITTYCONNECT_URL}/health.  Degraded if unreachable.
+ *   - daemon        max(heartbeat_at) FROM cc_node_leases.  Stale if older than
+ *                   2× daemon/loop.ts default heartbeatMs (10000ms → 20000ms).
+ *                   Missing table → not_provisioned (degraded, not down) so
+ *                   deploys against bases without #101 don't 503.
+ *
+ * Runs unauthenticated; does not touch auth middleware.
+ *
+ * @canonical-uri chittycanon://docs/architecture/chittycommand/health
+ */
+
+import { getDb } from '../lib/db';
+
+export const SERVICE_VERSION = '0.1.0';
+// daemon/loop.ts default heartbeatMs is 10000; flag stale at 2× = 20000ms.
+const DAEMON_STALE_MS = 20_000;
+
+export type HealthEnv = {
+  DATABASE_URL?: string;
+  HYPERDRIVE?: { connectionString: string };
+  CHITTYCONNECT_URL?: string;
+};
+
+export interface DbProbe {
+  status: 'ok' | 'down';
+  latency_ms: number;
+  error?: string;
+}
+export interface ChittyConnectProbe {
+  status: 'ok' | 'degraded' | 'down';
+  latency_ms: number;
+  error?: string;
+}
+export interface DaemonProbe {
+  status: 'ok' | 'stale' | 'not_provisioned';
+  newest_heartbeat_age_ms: number | null;
+  error?: string;
+}
+
+export interface HealthBody {
+  status: 'ok' | 'degraded' | 'down';
+  service: 'chittycommand';
+  version: string;
+  timestamp: string;
+  probes: { db: DbProbe; chittyconnect: ChittyConnectProbe; daemon: DaemonProbe };
+}
+
+async function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race<T>([
+      p,
+      new Promise<T>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timeout after ${ms}ms`)), ms);
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function probeDb(env: HealthEnv): Promise<DbProbe> {
+  const t0 = Date.now();
+  try {
+    // Cast: HealthEnv is a narrow subset of the worker Env type and getDb
+    // only reads DATABASE_URL / HYPERDRIVE.connectionString.
+    const sql = getDb(env as unknown as Parameters<typeof getDb>[0]);
+    await withTimeout(sql`SELECT 1 AS ok`, 2000, 'db');
+    return { status: 'ok', latency_ms: Date.now() - t0 };
+  } catch (err) {
+    return {
+      status: 'down',
+      latency_ms: Date.now() - t0,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+async function probeChittyConnect(env: HealthEnv): Promise<ChittyConnectProbe> {
+  const url = env.CHITTYCONNECT_URL;
+  const t0 = Date.now();
+  if (!url) {
+    return { status: 'degraded', latency_ms: 0, error: 'CHITTYCONNECT_URL not configured' };
+  }
+  try {
+    const r = await withTimeout(
+      fetch(`${url.replace(/\/$/, '')}/health`, { headers: { accept: 'application/json' } }),
+      2000,
+      'chittyconnect',
+    );
+    return r.ok
+      ? { status: 'ok', latency_ms: Date.now() - t0 }
+      : { status: 'degraded', latency_ms: Date.now() - t0, error: `HTTP ${r.status}` };
+  } catch (err) {
+    return {
+      status: 'degraded',
+      latency_ms: Date.now() - t0,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+async function probeDaemon(env: HealthEnv): Promise<DaemonProbe> {
+  try {
+    const sql = getDb(env as unknown as Parameters<typeof getDb>[0]);
+    const rows = (await withTimeout(
+      // NOTE: cc_node_leases has no `released_at` column. Release is
+      // represented by NULLing `heartbeat_at`/`lease_expires_at` in
+      // daemon/leader.ts::releaseLeadership. We treat any row whose
+      // heartbeat_at is non-null as a currently-held lease and take the
+      // newest heartbeat across them.
+      sql`SELECT EXTRACT(EPOCH FROM (NOW() - max(heartbeat_at))) * 1000 AS age_ms
+          FROM cc_node_leases
+          WHERE heartbeat_at IS NOT NULL`,
+      2000,
+      'daemon',
+    )) as Array<{ age_ms: number | string | null }>;
+    const raw = rows[0]?.age_ms;
+    if (raw === null || raw === undefined) {
+      return { status: 'stale', newest_heartbeat_age_ms: null };
+    }
+    const ageMs = typeof raw === 'string' ? parseFloat(raw) : Number(raw);
+    return {
+      status: ageMs > DAEMON_STALE_MS ? 'stale' : 'ok',
+      newest_heartbeat_age_ms: Math.round(ageMs),
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/cc_node_leases|relation .* does not exist|does not exist/i.test(msg)) {
+      return { status: 'not_provisioned', newest_heartbeat_age_ms: null, error: msg };
+    }
+    return { status: 'stale', newest_heartbeat_age_ms: null, error: msg };
+  }
+}
+
+export async function runHealthProbes(env: HealthEnv): Promise<{ body: HealthBody; httpStatus: 200 | 503 }> {
+  const [db, chittyconnect, daemon] = await Promise.all([
+    probeDb(env),
+    probeChittyConnect(env),
+    probeDaemon(env),
+  ]);
+
+  let status: HealthBody['status'] = 'ok';
+  if (db.status === 'down') {
+    status = 'down';
+  } else if (
+    chittyconnect.status === 'degraded' ||
+    chittyconnect.status === 'down' ||
+    daemon.status === 'stale' ||
+    daemon.status === 'not_provisioned'
+  ) {
+    status = 'degraded';
+  }
+
+  const body: HealthBody = {
+    status,
+    service: 'chittycommand',
+    version: SERVICE_VERSION,
+    timestamp: new Date().toISOString(),
+    probes: { db, chittyconnect, daemon },
+  };
+
+  return { body, httpStatus: status === 'down' ? 503 : 200 };
+}
@@ -0,0 +1,74 @@
+/**
+ * Integration test for the real-dependency /health probe handler.
+ *
+ * Runs against a REAL Neon branch (no mocks — chittyentity CLAUDE.md
+ * "No Mocks, Fake Data, or Placeholder Endpoints" rule).
+ *
+ * Usage:
+ *   DATABASE_URL='postgres://...neon...' npx vitest run tests/health/health-probe.spec.ts
+ *
+ * Skipped automatically when DATABASE_URL is absent or SKIP_INTEGRATION=1 —
+ * same pattern as tests/daemon/leader.spec.ts and tests/meta/intent-lifecycle.spec.ts.
+ *
+ * We import the probe handler directly from src/routes/health.ts (pure Node
+ * compatible). Importing src/index.ts would drag in `cloudflare:` namespaced
+ * modules (Agents SDK / Durable Objects) which only resolve under workerd.
+ *
+ * Verifies:
+ *   1. probes.db.status === 'ok' against the real Neon branch with latency_ms > 0.
+ *   2. probes.daemon.status ∈ { ok, stale, not_provisioned } — not over-asserted
+ *      because the branch may or may not have cc_node_leases provisioned or
+ *      an active node holding a lease.
+ *   3. probes.chittyconnect.status is one of { ok, degraded, down }.
+ *   4. httpStatus is 200 when db.status === 'ok'; 503 only when db is down.
+ *   5. Response shape matches the documented spec.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { runHealthProbes } from '../../src/routes/health';
+
+const DATABASE_URL = process.env.DATABASE_URL;
+const SKIP = !DATABASE_URL || process.env.SKIP_INTEGRATION === '1';
+
+describe.skipIf(SKIP)('/health real-dependency probe (real Neon)', () => {
+  it('runs all probes and reports DB ok against the real Neon branch', async () => {
+    const { body, httpStatus } = await runHealthProbes({
+      DATABASE_URL,
+      // CHITTYCONNECT_URL intentionally omitted: probe will report 'degraded'
+      // with "not configured", which is the documented behavior.
+    });
+
+    // Spec: 200 unless db is down. DB is reachable on this branch.
+    expect(httpStatus).toBe(200);
+
+    expect(body.service).toBe('chittycommand');
+    expect(typeof body.version).toBe('string');
+    expect(typeof body.timestamp).toBe('string');
+    expect(['ok', 'degraded']).toContain(body.status);
+
+    // DB probe must succeed.
+    expect(body.probes.db.status).toBe('ok');
+    expect(body.probes.db.latency_ms).toBeGreaterThan(0);
+
+    // ChittyConnect probe shape — value depends on env, just assert shape.
+    expect(['ok', 'degraded', 'down']).toContain(body.probes.chittyconnect.status);
+    expect(typeof body.probes.chittyconnect.latency_ms).toBe('number');
+
+    // Daemon probe — could be ok (active node), stale (no recent heartbeat),
+    // or not_provisioned (table missing on this branch). Don't over-assert.
+    expect(['ok', 'stale', 'not_provisioned']).toContain(body.probes.daemon.status);
+  });
+
+  it('marks status `down` and returns 503 when DB is unreachable', async () => {
+    // Real connection-refused — no mock, just an invalid host that fails fast.
+    const { body, httpStatus } = await runHealthProbes({
+      DATABASE_URL:
+        'postgresql://nobody:nobody@127.0.0.1:1/neondb?sslmode=disable',
+    });
+
+    expect(httpStatus).toBe(503);
+    expect(body.status).toBe('down');
+    expect(body.probes.db.status).toBe('down');
+    expect(typeof body.probes.db.error).toBe('string');
+  });
+});