@aria_asi/cli 0.2.32 → 0.2.34

package/src/connectors/codebase-awareness.ts

@@ -14,7 +14,10 @@ const ENV_PATH = path.join(ARIA_DIR, 'codebase-awareness.env');
 const STATE_PATH = path.join(ARIA_DIR, 'codebase-awareness-state.json');
 const INDEX_PATH = path.join(ARIA_DIR, 'codebase-awareness-index.json');
 
-type AwarenessStatus = 'idle' | 'watching' | 'scanning' | 'error';
+type AwarenessStatus = 'idle' | 'watching' | 'scanning' | 'degraded' | 'error';
+const HEARTBEAT_INTERVAL_MS = Math.max(5_000, Number(process.env.ARIA_CODEBASE_AWARENESS_HEARTBEAT_MS || '15000'));
+const REFRESH_INTERVAL_MS = Math.max(30_000, Number(process.env.ARIA_CODEBASE_AWARENESS_REFRESH_MS || '300000'));
+const REPO_DISCOVERY_INTERVAL_MS = Math.max(30_000, Number(process.env.ARIA_CODEBASE_AWARENESS_RETRY_MS || '60000'));
 
 interface RepoSnapshot {
   path: string;
@@ -36,6 +39,13 @@ interface AwarenessState {
   repoSnapshots: RepoSnapshot[];
   lastError: string | null;
   updatedAt: string;
+  daemon?: {
+    pid: number;
+    startedAt: string;
+    heartbeatAt: string;
+    refreshIntervalMs: number;
+    watcherModes: Record<string, string>;
+  };
 }
 
 function connectorPackageRoot(): string {
@@ -82,12 +92,17 @@ function readState(): AwarenessState {
       repoSnapshots: Array.isArray(parsed.repoSnapshots) ? parsed.repoSnapshots as RepoSnapshot[] : [],
       lastError: parsed.lastError || null,
       updatedAt: parsed.updatedAt || new Date(0).toISOString(),
+      daemon: parsed.daemon,
     };
   } catch {
     return defaultState();
   }
 }
 
+function compactError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function writeState(update: Partial<AwarenessState>): AwarenessState {
   const current = readState();
   const next: AwarenessState = {
@@ -254,86 +269,135 @@ export async function startCodebaseAwarenessDaemon(options: {
   repos?: string[];
   fallbackRepoPath?: string;
 } = {}): Promise<void> {
-  const repos = resolveRepos(undefined, options.repos, options.fallbackRepoPath);
-  if (!repos.length) {
-    writeState({ status: 'error', watchedRepos: [], lastError: 'No git repositories configured for codebase awareness.' });
-    throw new Error('No git repositories configured for codebase awareness.');
-  }
+  const startedAt = new Date().toISOString();
+  const handles = new Map<string, { stop: () => void; readonly mode: string }>();
+  const watcherModes: Record<string, string> = {};
+  let repos = resolveRepos(undefined, options.repos, options.fallbackRepoPath);
+
+  const writeDaemonState = (status: AwarenessStatus, update: Partial<AwarenessState> = {}): void => {
+    writeState({
+      status,
+      watchedRepos: repos,
+      ...update,
+      daemon: {
+        pid: process.pid,
+        startedAt,
+        heartbeatAt: new Date().toISOString(),
+        refreshIntervalMs: REFRESH_INTERVAL_MS,
+        watcherModes,
+      },
+    });
+  };
 
-  await runCodebaseAwarenessScan({ repos });
-  writeState({ status: 'watching', watchedRepos: repos, lastError: null });
+  const scanAll = async (reason: string): Promise<void> => {
+    repos = resolveRepos(undefined, options.repos, options.fallbackRepoPath);
+    if (!repos.length) {
+      writeDaemonState('degraded', { lastError: 'No git repositories configured for codebase awareness.' });
+      return;
+    }
 
-  for (const repo of repos) {
-    watchCodebase(
-      repo,
-      (image) => {
-        const schemaText = schemaImageToText(image);
-        const scanHash = hashSchema(schemaText);
-        const lastScan = new Date().toISOString();
-        const config = loadConfig();
-        const repositories = [
-          ...(config.repositories || []).filter((entry) => path.resolve(entry.path) !== repo),
-          {
-            path: repo,
-            name: image.projectName,
-            scanHash,
-            lastScan,
+    writeDaemonState('scanning', { lastError: null });
+    const snapshots: RepoSnapshot[] = [];
+    const failures: string[] = [];
+    for (const repo of repos) {
+      try {
+        snapshots.push(await applyRepoScan(repo));
+      } catch (error) {
+        failures.push(`${repo}: ${compactError(error)}`);
+      }
+    }
+
+    const current = readState();
+    const repoSnapshots = [
+      ...snapshots,
+      ...current.repoSnapshots.filter((entry) => !snapshots.some((snapshot) => path.resolve(snapshot.path) === path.resolve(entry.path))),
+    ];
+    writeDaemonState(failures.length ? 'degraded' : 'watching', {
+      repoSnapshots,
+      lastError: failures.length ? `${reason}: ${failures.join(' | ')}` : null,
+    });
+    writeIndex({
+      generatedAt: new Date().toISOString(),
+      reason,
+      watchedRepos: repos,
+      repoSnapshots,
+      schemaImages: loadConfig().schemaImages || {},
+    });
+  };
+
+  const ensureWatchers = (): void => {
+    repos = resolveRepos(undefined, options.repos, options.fallbackRepoPath);
+    for (const [repo, handle] of handles.entries()) {
+      if (!repos.includes(repo)) {
+        handle.stop();
+        handles.delete(repo);
+        delete watcherModes[repo];
+      }
+    }
+    for (const repo of repos) {
+      if (handles.has(repo)) continue;
+      try {
+        const handle = watchCodebase(
+          repo,
+          (image) => {
+            const schemaText = schemaImageToText(image);
+            const scanHash = hashSchema(schemaText);
+            const lastScan = new Date().toISOString();
+            const config = loadConfig();
+            const repositories = [
+              ...(config.repositories || []).filter((entry) => path.resolve(entry.path) !== repo),
+              { path: repo, name: image.projectName, scanHash, lastScan },
+            ];
+            const nextConfig = {
+              ...config,
+              repositories,
+              schemaImages: { ...(config.schemaImages || {}), [image.projectName]: schemaText },
+            };
+            saveConfig(nextConfig);
+
+            const current = readState();
+            const snapshot: RepoSnapshot = {
+              path: repo,
+              name: image.projectName,
+              scanHash,
+              lastScan,
+              fileCount: image.fileCount,
+              language: image.language,
+              framework: image.framework || null,
+              packageManager: image.packageManager || null,
+              database: image.database || null,
+              orm: image.orm || null,
+              architecture: architectureSummary(image),
+            };
+            const repoSnapshots = [snapshot, ...current.repoSnapshots.filter((entry) => path.resolve(entry.path) !== repo)];
+            writeDaemonState('watching', { repoSnapshots, lastError: null });
+            writeIndex({ generatedAt: new Date().toISOString(), reason: 'watch-change', watchedRepos: repos, repoSnapshots, schemaImages: nextConfig.schemaImages || {} });
           },
-        ];
-        const nextConfig = {
-          ...config,
-          repositories,
-          schemaImages: {
-            ...(config.schemaImages || {}),
-            [image.projectName]: schemaText,
+          {
+            debounceMs: 800,
+            pollIntervalMs: 4000,
+            onReady: (mode) => {
+              watcherModes[repo] = mode;
+              writeDaemonState('watching', { lastError: null });
+            },
+            onError: ({ phase, error }) => {
+              writeDaemonState('degraded', { lastError: `${repo} ${phase}: ${error.message}` });
+            },
           },
-        };
-        saveConfig(nextConfig);
-
-        const current = readState();
-        const snapshot: RepoSnapshot = {
-          path: repo,
-          name: image.projectName,
-          scanHash,
-          lastScan,
-          fileCount: image.fileCount,
-          language: image.language,
-          framework: image.framework || null,
-          packageManager: image.packageManager || null,
-          database: image.database || null,
-          orm: image.orm || null,
-          architecture: architectureSummary(image),
-        };
-        const repoSnapshots = [
-          snapshot,
-          ...current.repoSnapshots.filter((entry) => path.resolve(entry.path) !== repo),
-        ];
-        writeState({
-          status: 'watching',
-          watchedRepos: repos,
-          repoSnapshots,
-          lastError: null,
-        });
-        writeIndex({
-          generatedAt: new Date().toISOString(),
-          watchedRepos: repos,
-          repoSnapshots,
-          schemaImages: nextConfig.schemaImages || {},
-        });
-      },
-      {
-        debounceMs: 800,
-        pollIntervalMs: 4000,
-        onError: ({ error }) => {
-          writeState({
-            status: 'error',
-            watchedRepos: repos,
-            lastError: error.message,
-          });
-        },
-      },
-    );
-  }
+        );
+        handles.set(repo, handle);
+        watcherModes[repo] = handle.mode;
+      } catch (error) {
+        writeDaemonState('degraded', { lastError: `${repo} watcher init: ${compactError(error)}` });
+      }
+    }
+  };
+
+  await scanAll('daemon-start');
+  ensureWatchers();
+  setInterval(() => writeDaemonState(repos.length ? 'watching' : 'degraded'), HEARTBEAT_INTERVAL_MS).unref();
+  setInterval(() => { ensureWatchers(); void scanAll('periodic-refresh'); }, REFRESH_INTERVAL_MS).unref();
+  setInterval(() => { ensureWatchers(); }, REPO_DISCOVERY_INTERVAL_MS).unref();
 
   await new Promise(() => {});
 }

package/src/connectors/codex.ts

@@ -90,6 +90,8 @@ function tomlString(value: string): string {
 
 function buildCodexHookRuntimeClient(): string {
   return `import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { HTTPHarnessClient } from '@aria_asi/harness-http-client';
@@ -97,6 +99,7 @@ import { HTTPHarnessClient } from '@aria_asi/harness-http-client';
 const HOME = homedir();
 const DEFAULT_RUNTIME_URL = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\\/+$/, '');
 const TURN_STATE_DIR = path.join(HOME, '.codex', 'tmp', 'aria-hook-turn-state');
+const GOVERNANCE_GATE_PATH = path.join(HOME, '.aria', 'bin', 'aria-governance-gate');
 
 function readToken() {
   const envToken = process.env.ARIA_API_KEY || process.env.ARIA_MASTER_TOKEN || process.env.OPENAI_API_KEY;
@@ -154,6 +157,28 @@ export function inferSessionId(event) {
   return \`codex:\${threadId}:\${turnId}\`;
 }
 
+export function ensureTraceId(state = {}) {
+  return typeof state.traceId === 'string' && state.traceId ? state.traceId : \`trace_\${randomUUID()}\`;
+}
+
+function stableEvidenceString(value) {
+  if (typeof value === 'string') return value;
+  try { return JSON.stringify(value); } catch { return String(value); }
+}
+
+export function makeEvidenceRef(kind, value, metadata = {}) {
+  const raw = stableEvidenceString(value);
+  const sha256 = createHash('sha256').update(raw).digest('hex');
+  return {
+    evidenceId: \`ev_\${sha256.slice(0, 16)}\`,
+    kind,
+    at: new Date().toISOString(),
+    sha256,
+    preview: raw.slice(0, 500),
+    metadata,
+  };
+}
+
 export function inferUserId(event) {
   return (
     extractFirst(event, ['user_id', 'userId']) ||
@@ -300,6 +325,22 @@ export function emitJson(payload, code = 0) {
   process.stdout.write(\`\${JSON.stringify(payload)}\\n\`);
   process.exit(code);
 }
+
+export function runGovernanceGate(payload = {}) {
+  if (!existsSync(GOVERNANCE_GATE_PATH)) return null;
+  const child = spawnSync(GOVERNANCE_GATE_PATH, {
+    input: \`\${JSON.stringify(payload)}\\n\`,
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+  });
+  const stdout = String(child.stdout || '').trim();
+  let result = null;
+  try { result = stdout ? JSON.parse(stdout) : null; } catch {}
+  if (child.status !== 0 || result?.ok === false || result?.decision === 'block') {
+    throw new Error(stdout || child.stderr || 'aria-governance-gate blocked this Codex hook.');
+  }
+  return result;
+}
 `;
 }
 
@@ -309,10 +350,14 @@ import {
   getHarnessClient,
   inferSessionId,
   inferUserId,
+  ensureTraceId,
   extractUserText,
+  makeEvidenceRef,
   readEventFromStdin,
   runtimePost,
+  loadTurnState,
   saveTurnState,
+  runGovernanceGate,
   emitJson,
 } from './lib/runtime-client.mjs';
 
@@ -321,6 +366,8 @@ const client = getHarnessClient();
 const userText = extractUserText(event);
 const sessionId = inferSessionId(event);
 const userId = inferUserId(event);
+const priorState = loadTurnState(sessionId);
+const traceId = ensureTraceId(priorState);
 
 try {
   const packet = await client.getHarnessPacket({
@@ -328,6 +375,14 @@ try {
     platform: 'codex',
     message: userText || 'codex turn start',
   });
+  const packetRef = makeEvidenceRef('harness_packet', packet, { sessionId, platform: 'codex' });
+  runGovernanceGate({
+    sessionId,
+    sourceRuntime: 'codex',
+    surface: 'codex-userprompt-submit',
+    text: userText.slice(0, 8000),
+    evidence: packetRef,
+  });
   const result = await runtimePost('/mizan/pre', {
     sessionId,
     packet,
@@ -341,17 +396,21 @@ try {
     },
     context: {
       sessionId,
+      traceId,
       surface: 'codex-hooks',
       platform: 'codex',
       userText,
       userId,
+      evidenceRefs: [packetRef],
     },
   });
   saveTurnState(sessionId, {
+    traceId,
     userId,
     userText,
     preReceiptId: result?.receipt?.receiptId || null,
     packetTimestamp: packet?.timestamp || null,
+    packetRef,
     lastEvent: 'UserPromptSubmit',
   });
   process.exit(0);
@@ -373,7 +432,9 @@ import {
   summarizeTarget,
   readEventFromStdin,
   loadTurnState,
+  makeEvidenceRef,
   saveTurnState,
+  runGovernanceGate,
   emitJson,
 } from './lib/runtime-client.mjs';
 
@@ -399,12 +460,24 @@ try {
     });
   }
   const toolName = String(event?.tool_name || event?.toolName || '').trim() || null;
+  runGovernanceGate({
+    sessionId,
+    sourceRuntime: 'codex',
+    surface: 'codex-pre-tool-use',
+    text: JSON.stringify(event).slice(0, 8000),
+    action,
+    toolName,
+    isDeploy: action === 'deploy',
+    isMutation: action === 'write' || action === 'delete',
+    evidence: makeEvidenceRef('codex_tool_request', { action, toolName, target }, { sessionId }),
+  });
   const tools = Array.isArray(state?.tools) ? state.tools.slice(-24) : [];
   tools.push({
     at: new Date().toISOString(),
     action,
     toolName,
     target,
+    evidenceRef: makeEvidenceRef('tool_request', { action, toolName, target }, { sessionId }),
   });
   saveTurnState(sessionId, {
     tools,
@@ -426,6 +499,7 @@ import {
   inferSessionId,
   readEventFromStdin,
   loadTurnState,
+  makeEvidenceRef,
   saveTurnState,
 } from './lib/runtime-client.mjs';
 
@@ -435,11 +509,16 @@ const state = loadTurnState(sessionId);
 
 try {
   const toolResponse = JSON.stringify(event?.tool_response ?? event?.toolResponse ?? null).slice(0, 4000);
+  const evidenceRef = makeEvidenceRef('tool_response', event?.tool_response ?? event?.toolResponse ?? null, {
+    sessionId,
+    toolName: event?.tool_name || event?.toolName || null,
+  });
   const toolOutputs = Array.isArray(state?.toolOutputs) ? state.toolOutputs.slice(-24) : [];
   toolOutputs.push({
     at: new Date().toISOString(),
     toolName: event?.tool_name || event?.toolName || null,
     toolResponse,
+    evidenceRef,
   });
   saveTurnState(sessionId, {
     toolOutputs,
@@ -461,8 +540,10 @@ import {
   readEventFromStdin,
   runtimePost,
   loadTurnState,
+  makeEvidenceRef,
   clearTurnState,
   formatValidationFailure,
+  runGovernanceGate,
   emitJson,
 } from './lib/runtime-client.mjs';
 
@@ -471,11 +552,21 @@ const client = getHarnessClient();
 const sessionId = inferSessionId(event);
 const state = loadTurnState(sessionId);
 const text = extractAssistantText(event);
+const outputRef = makeEvidenceRef('assistant_output', text, { sessionId, traceId: state?.traceId || null });
+const toolRefs = Array.isArray(state?.toolOutputs) ? state.toolOutputs.map((entry) => entry.evidenceRef).filter(Boolean) : [];
 
 try {
   if (!text) {
     emitJson({ continue: true });
   }
+  runGovernanceGate({
+    sessionId,
+    sourceRuntime: 'codex',
+    surface: 'codex-stop',
+    text: text.slice(0, 8000),
+    isOutputCloseout: true,
+    evidence: outputRef,
+  });
   const validation = await runtimePost('/validate-output', {
     text,
     sessionId,
@@ -505,12 +596,16 @@ try {
       layer3_pass: validation?.layer3?.pass !== false,
       surface: 'codex-hooks',
       tool_count: Array.isArray(state?.tools) ? state.tools.length : 0,
+      trace_id: state?.traceId || null,
+      output_ref: outputRef,
+      tool_refs: toolRefs,
     },
     context: {
       sessionId,
       surface: 'codex-hooks',
       platform: 'codex',
       userText: state?.userText || null,
+      traceId: state?.traceId || null,
     },
     parentReceiptId: state?.preReceiptId || null,
   });
@@ -527,6 +622,9 @@ try {
     metadata: {
       post_receipt_id: post?.receipt?.receiptId || null,
       pre_receipt_id: state?.preReceiptId || null,
+      trace_id: state?.traceId || null,
+      output_ref: outputRef,
+      tool_refs: toolRefs,
       tool_count: Array.isArray(state?.tools) ? state.tools.length : 0,
       validation_severity: validation?.validation?.severity || 'pass',
       layer3_pass: validation?.layer3?.pass !== false,

package/src/setup-wizard.ts

@@ -33,6 +33,22 @@ const HARNESS_URL =
 const HARNESS_TOKEN = process.env.ARIA_HARNESS_TOKEN || '';
 const ARIA_DIR = join(homedir(), '.aria');
 const LICENSE_PATH = join(ARIA_DIR, 'license.json');
+const ONBOARDING_FALLBACK_URLS = [
+  process.env.ARIA_ONBOARDING_URL || '',
+  HARNESS_URL,
+  process.env.ARIA_SOUL_URL || '',
+  process.env.ARIAS_SOUL_URL || '',
+  process.env.ARIA_SOUL_BASE_URL || '',
+  'https://api.ariasos.com',
+  'https://arias-soul-6zp3gtk2ca-uc.a.run.app',
+  'https://harness.ariasos.com',
+]
+  .flatMap((entry) => String(entry || '').split(','))
+  .map((entry) => entry.trim().replace(/\/+$/, ''))
+  .filter(Boolean)
+  .filter((entry, index, list) => list.indexOf(entry) === index);
+
+let activeOnboardingBaseUrl = ONBOARDING_FALLBACK_URLS[0] || HARNESS_URL.replace(/\/+$/, '');
 
 type ConfigWrite =
   | { kind: 'persona_update'; updates: Record<string, unknown> }
@@ -57,7 +73,7 @@ interface DepthOption {
 interface ConverseResponse {
   ok: boolean;
   sessionId: string;
-  topic: 'identity' | 'codebase' | 'persona' | 'done';
+  topic: 'identity' | 'codebase' | 'persona' | 'workforce' | 'harness_setup' | 'done';
   ariaPrompt: string;
   depthOptions: DepthOption[];
   freeTextAllowed: boolean;
@@ -69,17 +85,32 @@ interface ConverseResponse {
 
 export async function runSetupWizard(): Promise<void> {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
+  let readlineClosed = false;
+  rl.on('close', () => { readlineClosed = true; });
   const ask = (q: string): Promise<string> =>
-    new Promise((resolve) => rl.question(q, (a) => resolve(a)));
+    new Promise((resolve) => {
+      if (readlineClosed) {
+        resolve('__ARIA_ONBOARDING_EOF__');
+        return;
+      }
+      rl.question(q, (a) => resolve(a));
+    });
 
   const sessionId = `onboard_${Date.now()}_${randomBytes(4).toString('hex')}`;
   let userMessage: string | undefined;
   let action: 'start' | 'answer' = 'start';
+  let turnCount = 0;
 
   console.log('\n💬 Aria: starting onboarding…\n');
 
   try {
     while (true) {
+      turnCount += 1;
+      if (turnCount > 40) {
+        console.error('\n❌ Onboarding stopped after too many turns. Please run `aria` again to resume.');
+        return;
+      }
+
       const resp = await callConverse({ sessionId, action, userMessage });
       if (!resp.ok) {
         console.error(`\n❌ Onboarding error: ${resp.error || 'unknown'}`);
@@ -100,6 +131,10 @@ export async function runSetupWizard(): Promise<void> {
       }
 
       userMessage = (await ask('> ')).trim();
+      if (userMessage === '__ARIA_ONBOARDING_EOF__') {
+        console.error('\n❌ Onboarding input ended before setup completed. Run `aria` again to resume.');
+        return;
+      }
       action = 'answer';
       if (!userMessage) userMessage = resp.depthOptions[0]?.signal ?? 'next';
     }
@@ -117,18 +152,8 @@ async function callConverse(body: {
   action: 'start' | 'answer';
   userMessage?: string;
 }): Promise<ConverseResponse> {
-  try {
-    const res = await fetch(`${HARNESS_URL}/api/onboarding/converse`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...(HARNESS_TOKEN ? { Authorization: `Bearer ${HARNESS_TOKEN}` } : {}),
-      },
-      body: JSON.stringify(body),
-    });
-    return (await res.json()) as ConverseResponse;
-  } catch (err) {
-    return {
+  return requestOnboardingJson<ConverseResponse>('/api/onboarding/converse', body, {
+    fallback: {
       ok: false,
       sessionId: body.sessionId,
       topic: 'identity',
@@ -137,9 +162,69 @@ async function callConverse(body: {
       freeTextAllowed: false,
       isComplete: false,
       progressPct: 0,
-      error: err instanceof Error ? err.message : String(err),
-    };
+    },
+  });
+}
+
+async function requestOnboardingJson<T extends { ok?: boolean; error?: string }>(
+  pathname: string,
+  body: Record<string, unknown>,
+  options: { fallback: T },
+): Promise<T> {
+  const failures: string[] = [];
+  const baseUrls = [
+    activeOnboardingBaseUrl,
+    ...ONBOARDING_FALLBACK_URLS,
+  ].filter((entry, index, list) => entry && list.indexOf(entry) === index);
+
+  for (const baseUrl of baseUrls) {
+    try {
+      const res = await fetch(`${baseUrl}${pathname}`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+          ...(HARNESS_TOKEN ? { Authorization: `Bearer ${HARNESS_TOKEN}` } : {}),
+        },
+        body: JSON.stringify(body),
+      });
+      const text = await res.text();
+      const contentType = res.headers.get('content-type') || '';
+      const looksJson = /^\s*[\[{]/.test(text);
+
+      if (!contentType.includes('application/json') && !looksJson) {
+        failures.push(`${baseUrl}${pathname} returned HTTP ${res.status} ${contentType || 'without content-type'}`);
+        continue;
+      }
+
+      let data: T;
+      try {
+        data = JSON.parse(text || '{}') as T;
+      } catch (err) {
+        failures.push(`${baseUrl}${pathname} returned invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        continue;
+      }
+
+      if (!res.ok) {
+        failures.push(`${baseUrl}${pathname} returned HTTP ${res.status}: ${data.error || 'no error message'}`);
+        continue;
+      }
+
+      activeOnboardingBaseUrl = baseUrl;
+      return data;
+    } catch (err) {
+      failures.push(`${baseUrl}${pathname} transport failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
   }
+
+  return {
+    ...options.fallback,
+    ok: false,
+    error:
+      'Onboarding API is unavailable or not returning JSON. ' +
+      failures.slice(0, 4).join(' | ') +
+      (failures.length > 4 ? ` | ${failures.length - 4} more endpoint(s) failed` : ''),
+  };
 }
 
 async function maybeOfferGitHubConnect(ask: (q: string) => Promise<string>): Promise<void> {
@@ -207,19 +292,14 @@ async function applyConfigWrites(writes: ConfigWrite[]): Promise<void> {
         const provider = claims.provider || '';
         const apiKey = claims.apiKey || '';
         try {
-          const resp = await fetch(`${HARNESS_URL}/api/onboarding/self-issue`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ email, provider, llm_key: apiKey }),
-          });
-          const data = await resp.json() as {
+          const data = await requestOnboardingJson<{
             ok?: boolean;
             license?: { token: string; jti: string; tier: string; expires_at: string };
             claims?: Record<string, unknown>;
             error?: string;
-          };
-          if (!resp.ok || !data.ok || !data.license) {
-            console.warn(`     ⚠ I couldn't issue your license: ${data.error || `HTTP ${resp.status}`}`);
+          }>('/api/onboarding/self-issue', { email, provider, llm_key: apiKey }, { fallback: { ok: false } });
+          if (!data.ok || !data.license) {
+            console.warn(`     ⚠ I couldn't issue your license: ${data.error || 'license endpoint did not return a license'}`);
             continue;
           }
           if (!existsSync(ARIA_DIR)) mkdirSync(ARIA_DIR, { recursive: true, mode: 0o700 });