@aria_asi/cli 0.2.29 → 0.2.31

package/src/connectors/must-read.ts

@@ -0,0 +1,113 @@
+export type MustReadSurface = 'claude' | 'codex' | 'opencode';
+
+function surfaceRoot(surface: MustReadSurface): string {
+  if (surface === 'claude') return '~/.claude';
+  if (surface === 'codex') return '~/.codex';
+  return '~/.aria';
+}
+
+function doctrineMapPath(surface: MustReadSurface): string {
+  if (surface === 'claude') return '~/.claude/hooks/doctrine_trigger_map.json';
+  if (surface === 'codex') return '~/.codex/doctrine_trigger_map.json';
+  return '~/.opencode/doctrine_trigger_map.json';
+}
+
+function surfaceSpecificFiles(surface: MustReadSurface): string[] {
+  if (surface === 'claude') {
+    return [
+      '~/.claude/hooks/aria-harness-via-sdk.mjs',
+      '~/.claude/hooks/aria-preprompt-consult.mjs',
+      '~/.claude/hooks/aria-pre-tool-gate.mjs',
+      '~/.claude/hooks/aria-preturn-memory-gate.mjs',
+      '~/.claude/hooks/aria-cognition-substrate-binding.mjs',
+      '~/.claude/hooks/aria-stop-gate.mjs',
+      '~/.claude/hooks/aria-pre-text-gate.mjs',
+    ];
+  }
+  if (surface === 'codex') {
+    return [
+      '~/.codex/AGENTS.md',
+      '~/.codex/config.toml',
+      '~/.aria/wrappers/codex',
+      '~/.aria/runtime/service.mjs',
+      '~/.codex/skills/aria-http-harness-client/SKILL.md',
+      '~/.codex/skills/aria-cognition/aria-repo-doctrine/SKILL.md',
+      '~/.codex/skills/aria-cognition/ghazali-8lens/SKILL.md',
+      '~/.codex/skills/aria-cognition/mizan/SKILL.md',
+    ];
+  }
+  return [
+    '~/.aria/AGENTS.md',
+    '~/.aria/runtime/discipline/skills/aria-harness/aria-harness-onboarding/SKILL.md',
+    '~/.aria/runtime/discipline/skills/aria-cognition/aria-repo-doctrine/SKILL.md',
+    '~/.aria/runtime/discipline/skills/aria-cognition/ghazali-8lens/SKILL.md',
+    '~/.aria/runtime/discipline/skills/aria-cognition/mizan/SKILL.md',
+  ];
+}
+
+export function buildMustReadGuide(surface: MustReadSurface): string {
+  const root = surfaceRoot(surface);
+  const coreFiles = [
+    `${root}/ARIA_MUST_READ.md`,
+    '~/.aria/runtime/discipline/CLAUDE.md',
+    '~/.aria/runtime/discipline/skills/aria-harness/aria-harness-onboarding/SKILL.md',
+    '~/.aria/runtime/discipline/skills/aria-harness/aria-harness-substrate-binding/SKILL.md',
+    doctrineMapPath(surface),
+  ];
+  const orderedFiles = [...coreFiles, ...surfaceSpecificFiles(surface)];
+
+  return `# Aria Agent Must-Read Order
+
+This file exists because weaker models and long sessions drift unless the reading order is explicit.
+Read these files in order before the first non-trivial action, and re-open the relevant gate file whenever a block fires.
+
+## Required Read Order
+
+${orderedFiles.map((filePath, index) => `${index + 1}. \`${filePath}\``).join('\n')}
+
+## What Each File Teaches
+
+1. \`${root}/ARIA_MUST_READ.md\`
+   The cross-surface reading order, recovery rules, and what to re-open after compaction or a block.
+
+2. \`~/.aria/runtime/discipline/CLAUDE.md\`
+   The full harness doctrine: L1/L2/L3, cognition requirements, deploy verify contract, drift triggers, and anti-loop rules.
+
+3. \`~/.aria/runtime/discipline/skills/aria-harness/aria-harness-onboarding/SKILL.md\`
+   The harness model in practical terms: packet, bind, and live gates.
+
+4. \`~/.aria/runtime/discipline/skills/aria-harness/aria-harness-substrate-binding/SKILL.md\`
+   The cognition contract and anchor discipline. Re-open this whenever cognition or stop-gate fails.
+
+5. \`${doctrineMapPath(surface)}\`
+   The live doctrine trigger map. This is what the runtime and stop gates actually match against.
+
+## Surface-Specific Re-Open Rules
+
+- If a pre-tool or write block fires:
+  Re-open the pre-tool surface file for this client plus \`aria-harness-substrate-binding\`.
+
+- If an output or stop-gate block fires:
+  Re-open \`~/.aria/runtime/discipline/CLAUDE.md\`, the doctrine trigger map, and the substrate-binding skill before re-authoring.
+
+- If transcript compaction or ledger deadlock happens:
+  Re-open items 1 through 4 first, then inspect the exact current hook or runtime file causing the block. Do not guess from stale memory.
+
+- If the model starts repeating itself:
+  Stop, re-open this file, and repair from the gate evidence instead of restating intent.
+
+## Non-Negotiables
+
+- Do not rename canonical cognition meaning into generic aliases.
+- Do not say "good enough", "should work", or make unverified completion claims.
+- Do not treat skills as optional flavor text; they are the reading order and repair guide.
+- Do not proceed after a gate block without re-opening the file that owns that gate.
+`;
+}
+
+export function mustReadIntro(surface: MustReadSurface): string {
+  const root = surfaceRoot(surface);
+  return `## Must Read Order
+Read \`${root}/ARIA_MUST_READ.md\` before the first non-trivial action and re-open it after any gate block, compaction, or repeated drift.
+`;
+}

package/src/connectors/opencode.ts

@@ -16,6 +16,8 @@ import * as path from 'path';
 import { fileURLToPath } from 'node:url';
 import type { AriaConfig } from '../config.js';
 import { connectShell } from './shell.js';
+import { syncDoctrineTriggerMap } from './doctrine-trigger-map.js';
+import { buildMustReadGuide, mustReadIntro } from './must-read.js';
 
 // ── Bundled OpenCode plugins ────────────────────────────────────────────────
 //
@@ -139,6 +141,7 @@ export async function connectOpenCode(config: AriaConfig): Promise<string[]> {
     copyPluginDir(srcDir, dstDir, logs);
     installedPaths.push(dstDir);
   }
+  syncDoctrineTriggerMap(logs);
 
   // ── Wire ~/.opencode/config.json ──────────────────────────────────────────
   const configPath = path.join(opencodeDir, 'config.json');

package/src/connectors/runtime.ts

@@ -7,12 +7,14 @@ import {
   chmodSync,
   rmSync,
   writeFileSync,
+  readFileSync,
 } from 'fs';
 import { execFileSync } from 'child_process';
 import { homedir } from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'node:url';
 import { loadConfig, saveConfig } from '../config.js';
+import { syncDoctrineTriggerMap } from './doctrine-trigger-map.js';
 
 function packageRuntimeDir(): string {
   const here = path.dirname(fileURLToPath(import.meta.url));
@@ -50,6 +52,39 @@ function writeWrapper(binPath: string, targetScript: string): void {
   try { chmodSync(binPath, 0o755); } catch {}
 }
 
+function trimUrl(value: string): string {
+  return value.trim().replace(/\/+$/, '');
+}
+
+function isLocalHarnessDaemonUrl(value: string): boolean {
+  const normalized = trimUrl(value);
+  return normalized === 'http://127.0.0.1:8790' || normalized === 'http://localhost:8790';
+}
+
+function canonicalUpstreamHarnessUrl(): string {
+  const localSoulCandidates = existsSync('/etc/rancher/k3s/k3s.yaml')
+    ? ['http://127.0.0.1:30080', 'http://192.168.4.25:30080']
+    : [];
+  const candidates = [
+    process.env.ARIA_UPSTREAM_HARNESS_URL || '',
+    process.env.ARIA_HIVE_UPSTREAM_URL || '',
+    ...localSoulCandidates,
+    process.env.ARIA_SOUL_URL || '',
+    process.env.ARIAS_SOUL_URL || '',
+    process.env.ARIA_SOUL_BASE_URL || '',
+    ...(process.env.ARIA_HARNESS_FALLBACK_URLS || '').split(','),
+    'https://harness.ariasos.com',
+  ]
+    .map((entry) => trimUrl(String(entry || '')))
+    .filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (!isLocalHarnessDaemonUrl(candidate)) return candidate;
+  }
+
+  return 'https://harness.ariasos.com';
+}
+
 function writeRuntimeEnv(runtimeDst: string): string {
   const envPath = path.join(runtimeDst, 'runtime.env');
   const config = loadConfig();
@@ -59,24 +94,46 @@ function writeRuntimeEnv(runtimeDst: string): string {
   const deepModel = runtimeProfiles.deepModel || 'deepseek-v4-pro';
   const xaiFallbackModel = runtimeProfiles.xaiFallbackModel || 'grok-4-2-reasoning';
   const nimFallbackModel = runtimeProfiles.nimFallbackModel || 'qwen/qwen3.5-122b-a10b';
-  const harnessUrl =
-    process.env.ARIA_HIVE_RUNTIME_URL ||
-    process.env.ARIA_HARNESS_BASE_URL ||
-    process.env.ARIA_HARNESS_URL ||
-    'https://harness.ariasos.com';
-  const forgeServiceUrl =
-    process.env.ARIA_FORGE_SERVICE_URL ||
-    process.env.FORGE_SERVICE_URL ||
-    `${harnessUrl.replace(/\/$/, '')}/api/forge/psi`;
+  const localHarnessUrl = 'http://127.0.0.1:8790';
+  const upstreamHarnessUrl = canonicalUpstreamHarnessUrl();
+  const harnessFallbackUrls = [
+    process.env.ARIA_HARNESS_FALLBACK_URLS || '',
+    process.env.ARIA_SOUL_URL || '',
+    process.env.ARIAS_SOUL_URL || '',
+    process.env.ARIA_SOUL_BASE_URL || '',
+    upstreamHarnessUrl,
+    'http://127.0.0.1:30080',
+    'http://192.168.4.25:30080',
+    'https://arias-soul-6zp3gtk2ca-uc.a.run.app',
+    'https://harness.ariasos.com',
+  ]
+    .flatMap((entry) => String(entry || '').split(','))
+    .map((entry) => trimUrl(String(entry || '')))
+    .filter((entry) => entry && !isLocalHarnessDaemonUrl(entry));
+  const forgeServiceUrl = `${localHarnessUrl}/api/forge/psi`;
+  const upstreamForgeServiceUrl =
+    process.env.ARIA_UPSTREAM_FORGE_SERVICE_URL ||
+    process.env.ARIA_FORGE_UPSTREAM_URL ||
+    `${upstreamHarnessUrl}/api/forge/psi`;
   writeFileSync(
     envPath,
     [
       'ARIA_RUNTIME_HOST=127.0.0.1',
       'ARIA_RUNTIME_PORT=4319',
       'ARIA_RUNTIME_URL=http://127.0.0.1:4319',
-      `ARIA_HIVE_RUNTIME_URL=${harnessUrl}`,
-      `ARIA_HARNESS_URL=${harnessUrl}`,
+      'ARIA_HARNESS_DAEMON_HOST=127.0.0.1',
+      'ARIA_HARNESS_DAEMON_PORT=8790',
+      `ARIA_HARNESS_DAEMON_URL=${localHarnessUrl}`,
+      'ARIA_CODEX_BRIDGE_HOST=127.0.0.1',
+      'ARIA_CODEX_BRIDGE_PORT=4320',
+      'ARIA_CODEX_DOWNSTREAM_PORT=4321',
+      `ARIA_HIVE_RUNTIME_URL=${localHarnessUrl}`,
+      `ARIA_HARNESS_BASE_URL=${localHarnessUrl}`,
+      `ARIA_HARNESS_URL=${localHarnessUrl}`,
+      `ARIA_UPSTREAM_HARNESS_URL=${upstreamHarnessUrl}`,
+      `ARIA_HARNESS_FALLBACK_URLS=${Array.from(new Set(harnessFallbackUrls)).join(',')}`,
       `ARIA_FORGE_SERVICE_URL=${forgeServiceUrl}`,
+      `ARIA_UPSTREAM_FORGE_SERVICE_URL=${upstreamForgeServiceUrl}`,
       'ARIA_QDRANT_URL=http://127.0.0.1:6333',
       'ARIA_QDRANT_COLLECTION=aria_garden_memory',
       `ARIA_RUNTIME_DEFAULT_PROVIDER=${defaultProvider}`,
@@ -230,7 +287,8 @@ function installSystemdUserService(ariaDir: string, logs: string[]): void {
   const unit = [
     '[Unit]',
     'Description=Aria Mounted Runtime',
-    'After=network.target',
+    'After=network.target aria-harnessd.service',
+    'Requires=aria-harnessd.service',
     '',
     '[Service]',
     'Type=simple',
@@ -256,13 +314,154 @@ function installSystemdUserService(ariaDir: string, logs: string[]): void {
   }
 }
 
+function installHarnessDaemonSystemdUserService(ariaDir: string, logs: string[]): void {
+  const systemctlPath = '/bin/systemctl';
+  if (process.platform !== 'linux' || !existsSync(systemctlPath)) {
+    return;
+  }
+
+  const serviceDir = path.join(homedir(), '.config', 'systemd', 'user');
+  const servicePath = path.join(serviceDir, 'aria-harnessd.service');
+  mkdirSync(serviceDir, { recursive: true, mode: 0o755 });
+
+  const unit = [
+    '[Unit]',
+    'Description=Aria Local Harness Daemon',
+    'After=network.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    `EnvironmentFile=-${path.join(ariaDir, 'runtime', 'runtime.env')}`,
+    `ExecStart=${path.join(ariaDir, 'bin', 'aria-harnessd')}`,
+    'Restart=always',
+    'RestartSec=2',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+
+  writeFileSync(servicePath, unit, { mode: 0o644 });
+  logs.push(`Installed systemd user unit → ${servicePath}`);
+
+  try {
+    execFileSync(systemctlPath, ['--user', 'daemon-reload'], { stdio: 'ignore' });
+    execFileSync(systemctlPath, ['--user', 'enable', '--now', 'aria-harnessd.service'], { stdio: 'ignore' });
+    logs.push('Enabled and started systemd user service: aria-harnessd.service');
+  } catch (error) {
+    logs.push(`⚠ local harness daemon installed but not activated: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function retireLegacySoulPortForwardServices(logs: string[]): void {
+  const systemctlPath = '/bin/systemctl';
+  if (process.platform !== 'linux' || !existsSync(systemctlPath)) {
+    return;
+  }
+
+  const serviceDir = path.join(homedir(), '.config', 'systemd', 'user');
+  const legacyUnits = ['aria-soul-portforward.service', 'aria-soul-forward.service'];
+  const dependencyNeedles = new Set(legacyUnits);
+
+  if (existsSync(serviceDir)) {
+    for (const name of readdirSync(serviceDir)) {
+      if (!name.endsWith('.service')) continue;
+      const unitPath = path.join(serviceDir, name);
+      if (!statSync(unitPath).isFile()) continue;
+      let current = '';
+      try {
+        current = readFileSync(unitPath, 'utf8');
+      } catch {
+        continue;
+      }
+      let next = current;
+      for (const needle of dependencyNeedles) {
+        next = next.replaceAll(needle, 'aria-harnessd.service');
+      }
+      if (next !== current) {
+        writeFileSync(unitPath, next, { mode: 0o644 });
+        logs.push(`Rebound legacy 8790 dependency → ${unitPath}`);
+      }
+    }
+  }
+
+  for (const unit of legacyUnits) {
+    const unitPath = path.join(serviceDir, unit);
+    const backupPath = `${unitPath}.legacy-disabled.bak`;
+    const disabledPath = `${unitPath}.disabled`;
+    try {
+      if (existsSync(unitPath) && statSync(unitPath).isFile() && !existsSync(backupPath)) {
+        copyFileSync(unitPath, backupPath);
+        logs.push(`Backed up legacy 8790 unit → ${backupPath}`);
+      }
+    } catch {}
+    try {
+      if (existsSync(unitPath) && statSync(unitPath).isFile()) {
+        rmSync(disabledPath, { force: true });
+        copyFileSync(unitPath, disabledPath);
+        rmSync(unitPath, { force: true });
+        logs.push(`Retired legacy 8790 unit file → ${disabledPath}`);
+      }
+    } catch {}
+    try {
+      execFileSync(systemctlPath, ['--user', 'disable', '--now', unit], { stdio: 'ignore' });
+      logs.push(`Disabled legacy 8790 unit: ${unit}`);
+    } catch {}
+    try {
+      execFileSync(systemctlPath, ['--user', 'mask', '--force', unit], { stdio: 'ignore' });
+      logs.push(`Masked legacy 8790 unit: ${unit}`);
+    } catch {}
+  }
+
+  try {
+    execFileSync(systemctlPath, ['--user', 'daemon-reload'], { stdio: 'ignore' });
+  } catch {}
+}
+
+function installCodexBridgeSystemdUserService(ariaDir: string, logs: string[]): void {
+  const systemctlPath = '/bin/systemctl';
+  if (process.platform !== 'linux' || !existsSync(systemctlPath)) {
+    return;
+  }
+
+  const serviceDir = path.join(homedir(), '.config', 'systemd', 'user');
+  const servicePath = path.join(serviceDir, 'aria-codex-bridge.service');
+  mkdirSync(serviceDir, { recursive: true, mode: 0o755 });
+
+  const unit = [
+    '[Unit]',
+    'Description=Aria Codex Enforcement Bridge',
+    'After=network.target aria-mounted-runtime.service',
+    'Requires=aria-mounted-runtime.service',
+    '',
+    '[Service]',
+    'Type=simple',
+    `EnvironmentFile=-${path.join(ariaDir, 'runtime', 'runtime.env')}`,
+    `ExecStart=${path.join(ariaDir, 'bin', 'aria-codex-bridge')}`,
+    'Restart=always',
+    'RestartSec=2',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+
+  writeFileSync(servicePath, unit, { mode: 0o644 });
+  logs.push(`Installed systemd user unit → ${servicePath}`);
+
+  try {
+    execFileSync(systemctlPath, ['--user', 'daemon-reload'], { stdio: 'ignore' });
+    execFileSync(systemctlPath, ['--user', 'enable', '--now', 'aria-codex-bridge.service'], { stdio: 'ignore' });
+    logs.push('Enabled and started systemd user service: aria-codex-bridge.service');
+  } catch (error) {
+    logs.push(`⚠ codex bridge service installed but not activated: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 function installLaunchAgent(ariaDir: string, logs: string[]): void {
   if (process.platform !== 'darwin') return;
-  const harnessUrl =
-    process.env.ARIA_HIVE_RUNTIME_URL ||
-    process.env.ARIA_HARNESS_BASE_URL ||
-    process.env.ARIA_HARNESS_URL ||
-    'https://harness.ariasos.com';
+  const localHarnessUrl = 'http://127.0.0.1:8790';
+  const upstreamHarnessUrl = canonicalUpstreamHarnessUrl();
 
   const launchAgentDir = path.join(homedir(), 'Library', 'LaunchAgents');
   const plistPath = path.join(launchAgentDir, 'com.aria.mounted-runtime.plist');
@@ -286,10 +485,20 @@ function installLaunchAgent(ariaDir: string, logs: string[]): void {
     <string>4319</string>
     <key>ARIA_RUNTIME_URL</key>
     <string>http://127.0.0.1:4319</string>
-  <key>ARIA_HIVE_RUNTIME_URL</key>
-    <string>${harnessUrl}</string>
-  <key>ARIA_HARNESS_URL</key>
-    <string>${harnessUrl}</string>
+    <key>ARIA_HARNESS_DAEMON_URL</key>
+    <string>${localHarnessUrl}</string>
+    <key>ARIA_HIVE_RUNTIME_URL</key>
+    <string>${localHarnessUrl}</string>
+    <key>ARIA_HARNESS_BASE_URL</key>
+    <string>${localHarnessUrl}</string>
+    <key>ARIA_HARNESS_URL</key>
+    <string>${localHarnessUrl}</string>
+    <key>ARIA_UPSTREAM_HARNESS_URL</key>
+    <string>${upstreamHarnessUrl}</string>
+    <key>ARIA_FORGE_SERVICE_URL</key>
+    <string>${localHarnessUrl}/api/forge/psi</string>
+    <key>ARIA_UPSTREAM_FORGE_SERVICE_URL</key>
+    <string>${upstreamHarnessUrl}/api/forge/psi</string>
   </dict>
   <key>RunAtLoad</key>
   <true/>
@@ -351,20 +560,31 @@ export async function installSharedRuntime(): Promise<string[]> {
   }
 
   const startWrapper = path.join(binDir, 'aria-runtime');
+  const harnessDaemonWrapper = path.join(binDir, 'aria-harnessd');
+  const codexBridgeWrapper = path.join(binDir, 'aria-codex-bridge');
   const doctorWrapper = path.join(binDir, 'aria-runtime-doctor');
   writeWrapper(startWrapper, path.join(runtimeDst, 'service.mjs'));
+  writeWrapper(harnessDaemonWrapper, path.join(runtimeDst, 'harness-daemon.mjs'));
+  writeWrapper(codexBridgeWrapper, path.join(runtimeDst, 'codex-bridge.mjs'));
   writeWrapper(doctorWrapper, path.join(runtimeDst, 'doctor.mjs'));
   const envPath = writeRuntimeEnv(runtimeDst);
   installDisciplinePack(runtimeDst, logs);
+  syncDoctrineTriggerMap(logs);
   installLocalQdrantService(ariaDir, logs);
+  retireLegacySoulPortForwardServices(logs);
+  installHarnessDaemonSystemdUserService(ariaDir, logs);
   installSystemdUserService(ariaDir, logs);
+  installCodexBridgeSystemdUserService(ariaDir, logs);
   installLaunchAgent(ariaDir, logs);
 
   logs.push(`Installed shared Aria runtime → ${runtimeDst}`);
   logs.push(`Installed runtime wrapper → ${startWrapper}`);
+  logs.push(`Installed harness daemon wrapper → ${harnessDaemonWrapper}`);
+  logs.push(`Installed Codex bridge wrapper → ${codexBridgeWrapper}`);
   logs.push(`Installed runtime doctor → ${doctorWrapper}`);
   logs.push(`Installed runtime env → ${envPath}`);
   logs.push('Mount any client against ARIA_RUNTIME_URL=http://127.0.0.1:4319');
+  logs.push('Harness packet and local validation are served by aria-harnessd on http://127.0.0.1:8790.');
   logs.push('Local Qdrant memory is mounted at http://127.0.0.1:6333 for garden pulse persistence.');
   logs.push('Runtime lease is encrypted at rest and revalidated against /api/license/heartbeat');
   logs.push('Forge synthesis is relayed through the canonical Aria endpoint unless ARIA_FORGE_SERVICE_URL overrides it.');

package/src/connectors/shell.ts

@@ -12,15 +12,32 @@ const SHELL_RC_FILES = ['.bashrc', '.bash_profile', '.profile', '.zshrc', '.zpro
 const SHELL_HOOK_LINE = '[ -f "$HOME/.aria/shell/runtime-client-env.sh" ] && . "$HOME/.aria/shell/runtime-client-env.sh"';
 
 function resolveToolPath(toolName: string): string | null {
+  const sanitizedPath = (process.env.PATH || '')
+    .split(path.delimiter)
+    .filter((entry) => entry && path.resolve(entry) !== path.resolve(WRAPPER_DIR))
+    .join(path.delimiter);
   try {
-    const lines = execSync(`which -a ${toolName}`, { encoding: 'utf-8' })
+    const lines = execSync(`which -a ${toolName}`, {
+      encoding: 'utf-8',
+      env: {
+        ...process.env,
+        PATH: sanitizedPath,
+      },
+    })
       .split('\n')
       .map((line) => line.trim())
       .filter(Boolean);
     const preferred = lines.find((candidate) => !candidate.startsWith(`${WRAPPER_DIR}/`));
     return preferred || lines[0] || null;
   } catch {
-    return null;
+    const fallbackCandidates = [
+      path.join(homedir(), '.npm-global', 'bin', toolName),
+      path.join(homedir(), '.local', 'bin', toolName),
+      path.join('/usr/local/bin', toolName),
+      path.join('/usr/bin', toolName),
+    ];
+    const fallback = fallbackCandidates.find((candidate) => existsSync(candidate));
+    return fallback || null;
   }
 }
 
@@ -72,9 +89,66 @@ if [ -z "\${ARIA_API_KEY:-}" ]; then
     fi
   fi
 fi
+if [ -n "\${ARIA_API_KEY:-}" ] && [ -z "\${OPENAI_API_KEY:-}" ]; then
+  export OPENAI_API_KEY="$ARIA_API_KEY"
+fi
 `;
 }
 
+function buildToolExecBlock(toolName: string, toolPath: string): string {
+  if (toolName !== 'codex') {
+    return `exec "${toolPath}" "$@"`;
+  }
+
+  return `for arg in "$@"; do
+  if [ "$arg" = "--remote" ]; then
+    exec "${toolPath}" "$@"
+  fi
+done
+
+case "\${1:-}" in
+  app-server|exec-server|exec|review)
+    exec "${toolPath}" "$@"
+    ;;
+esac
+
+if [ "\${ARIA_CODEX_BYPASS_BRIDGE:-0}" = "1" ]; then
+  exec "${toolPath}" "$@"
+fi
+
+export ARIA_CODEX_REAL_BIN="\${ARIA_CODEX_REAL_BIN:-${toolPath}}"
+export ARIA_CODEX_BRIDGE_HOST="\${ARIA_CODEX_BRIDGE_HOST:-127.0.0.1}"
+export ARIA_CODEX_BRIDGE_PORT="\${ARIA_CODEX_BRIDGE_PORT:-4320}"
+export ARIA_CODEX_DOWNSTREAM_PORT="\${ARIA_CODEX_DOWNSTREAM_PORT:-4321}"
+
+if command -v systemctl >/dev/null 2>&1; then
+  systemctl --user import-environment ARIA_CODEX_REAL_BIN ARIA_CODEX_BRIDGE_HOST ARIA_CODEX_BRIDGE_PORT ARIA_CODEX_DOWNSTREAM_PORT >/dev/null 2>&1 || true
+  systemctl --user start aria-codex-bridge.service >/dev/null 2>&1 || true
+fi
+
+if ! (exec 9<>"/dev/tcp/$ARIA_CODEX_BRIDGE_HOST/$ARIA_CODEX_BRIDGE_PORT") >/dev/null 2>&1; then
+  nohup "$HOME/.aria/bin/aria-codex-bridge" >/dev/null 2>&1 &
+fi
+
+bridge_ready=0
+for _aria_try in $(seq 1 50); do
+  if (exec 9<>"/dev/tcp/$ARIA_CODEX_BRIDGE_HOST/$ARIA_CODEX_BRIDGE_PORT") >/dev/null 2>&1; then
+    exec 9>&-
+    exec 9<&-
+    bridge_ready=1
+    break
+  fi
+  sleep 0.1
+done
+
+if [ "$bridge_ready" != "1" ]; then
+  echo "Aria Codex bridge did not become ready at ws://$ARIA_CODEX_BRIDGE_HOST:$ARIA_CODEX_BRIDGE_PORT" >&2
+  exit 1
+fi
+
+exec "${toolPath}" --remote "ws://$ARIA_CODEX_BRIDGE_HOST:$ARIA_CODEX_BRIDGE_PORT" "$@"`;
+}
+
 export async function connectShell(
   toolName: string,
   config: AriaConfig,
@@ -93,13 +167,14 @@ export async function connectShell(
 
   const ariaBlock = buildShellWrapperBlock(config, toolName);
   const runtimeBlock = buildRuntimeInjectionBlock();
+  const execBlock = buildToolExecBlock(toolName, toolPath);
   const wrapperPath = path.join(WRAPPER_DIR, toolName);
   const script = `#!/usr/bin/env bash
 # ARIA HARNESS WRAPPER — generated by @aria/connector
 # Wraps ${toolName} with Aria's cognitive harness
 ${ariaBlock}
 ${runtimeBlock}
-exec "${toolPath}" "$@"
+${execBlock}
 `;
 
   writeFileSync(wrapperPath, script);