@aria_asi/cli 0.2.40 → 0.2.41

package/src/connectors/cursor.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import * as path from 'path';
 import type { AriaConfig } from '../config.js';
+import { requireGovernedConnectorMutation } from './governed-adapter.js';
 
 const CURSOR_RULES_HEADER = `// ARIA HARNESS — injected by @aria/connector
 // Aria provides: schema image awareness + garden memory + 8-lens cognition
@@ -32,6 +33,13 @@ export async function connectCursor(config: AriaConfig, repoPath?: string): Prom
   const targetPath = repoPath || process.cwd();
   const rulesPath = path.join(targetPath, '.cursorrules');
 
+  await requireGovernedConnectorMutation({
+    surfaceId: 'cursor',
+    action: 'install',
+    targetPath: rulesPath,
+    reason: 'install Cursor harness rules',
+  });
+
   const ariaBlock = buildCursorRules(config);
 
   if (existsSync(rulesPath)) {

package/src/connectors/governed-adapter.ts

@@ -0,0 +1,174 @@
+import { homedir } from 'node:os';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import {
+  DEFAULT_SANDBOX_NAMESPACE,
+  DEFAULT_SANDBOX_ROOT,
+  GovernedSurfaceRunner,
+  type GovernedSurfaceAction,
+  type GovernedSurfaceId,
+  type GovernedSurfacePolicy,
+  type GovernedSurfaceVerdict,
+  governedPathIsUnder,
+} from '../governed-surface-runner.js';
+
+export interface ConnectorGovernanceOptions {
+  namespace?: string;
+  sandboxRoot?: string;
+  allowedTargetRoots?: string[];
+  approvalFile?: string;
+  productionApproved?: boolean;
+  receipt?: string;
+  sessionId?: string;
+  runtimeUrl?: string;
+}
+
+export interface ConnectorProductionApproval {
+  approved: boolean;
+  receipt: string;
+  allowedTargetRoots: string[];
+  surfaceIds?: GovernedSurfaceId[];
+  expiresAt?: string;
+  issuedBy?: string;
+  reason?: string;
+}
+
+function envFlag(name: string): boolean {
+  const value = process.env[name];
+  return value === '1' || value === 'true' || value === 'yes';
+}
+
+function envList(name: string): string[] {
+  const value = process.env[name];
+  if (!value) return [];
+  return value.split(path.delimiter).map((item) => item.trim()).filter(Boolean);
+}
+
+function loadApprovalFile(filePath: string | undefined): ConnectorProductionApproval | null {
+  if (!filePath || !existsSync(filePath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf8')) as Partial<ConnectorProductionApproval>;
+    if (parsed.approved !== true) return null;
+    if (typeof parsed.receipt !== 'string' || !parsed.receipt.trim()) return null;
+    if (!Array.isArray(parsed.allowedTargetRoots) || parsed.allowedTargetRoots.length === 0) return null;
+    const allowedTargetRoots = parsed.allowedTargetRoots
+      .filter((root): root is string => typeof root === 'string' && root.trim().length > 0)
+      .map((root) => path.resolve(root));
+    if (allowedTargetRoots.length === 0) return null;
+    if (typeof parsed.expiresAt === 'string' && parsed.expiresAt) {
+      const expires = Date.parse(parsed.expiresAt);
+      if (!Number.isFinite(expires) || expires <= Date.now()) return null;
+    }
+    const surfaceIds = Array.isArray(parsed.surfaceIds)
+      ? parsed.surfaceIds.filter((surface): surface is GovernedSurfaceId => typeof surface === 'string')
+      : undefined;
+    return {
+      approved: true,
+      receipt: parsed.receipt.trim(),
+      allowedTargetRoots,
+      surfaceIds,
+      expiresAt: parsed.expiresAt,
+      issuedBy: parsed.issuedBy,
+      reason: parsed.reason,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function readConnectorProductionApproval(opts: ConnectorGovernanceOptions = {}): ConnectorProductionApproval | null {
+  return loadApprovalFile(opts.approvalFile ?? process.env.ARIA_CONNECTOR_APPROVAL_FILE);
+}
+
+function targetRootForProduction(targetPath: string): string {
+  const resolved = path.resolve(targetPath);
+  const home = homedir();
+  const activeRoots = [
+    path.join(home, '.codex'),
+    path.join(home, '.claude'),
+    path.join(home, '.opencode'),
+    path.join(home, '.aria'),
+  ];
+  return activeRoots.find((root) => governedPathIsUnder(resolved, root)) ?? resolved;
+}
+
+export function buildConnectorGovernancePolicy(
+  targetPath: string,
+  opts: ConnectorGovernanceOptions = {},
+): GovernedSurfacePolicy {
+  const sandboxRoot = opts.sandboxRoot ?? process.env.ARIA_CONNECTOR_SANDBOX_ROOT ?? DEFAULT_SANDBOX_ROOT;
+  const fileApproval = readConnectorProductionApproval(opts);
+  const directApproval = opts.productionApproved === true && typeof opts.receipt === 'string' && opts.receipt.trim().length > 0;
+  const productionApproved = directApproval || fileApproval?.approved === true;
+  const envAllowedRoots = envList('ARIA_CONNECTOR_ALLOWED_TARGET_ROOTS');
+  const allowedTargetRoots = [
+    sandboxRoot,
+    ...envAllowedRoots,
+    ...(opts.allowedTargetRoots ?? []),
+    ...(fileApproval?.allowedTargetRoots ?? []),
+  ];
+
+  if (productionApproved) {
+    allowedTargetRoots.push(targetRootForProduction(targetPath));
+  }
+
+  return {
+    runtimeUrl: opts.runtimeUrl,
+    sandboxRoot,
+    allowedNamespaces: [opts.namespace ?? process.env.ARIA_CONNECTOR_NAMESPACE ?? DEFAULT_SANDBOX_NAMESPACE],
+    allowedTargetRoots,
+    allowActiveLocalProductionTargets: productionApproved,
+    sessionId: opts.sessionId ?? 'connector-adapter',
+  };
+}
+
+export async function requireGovernedConnectorMutation(args: {
+  surfaceId: GovernedSurfaceId;
+  action?: GovernedSurfaceAction;
+  targetPath: string;
+  reason: string;
+  opts?: ConnectorGovernanceOptions;
+}): Promise<GovernedSurfaceVerdict> {
+  const namespace = args.opts?.namespace ?? process.env.ARIA_CONNECTOR_NAMESPACE ?? DEFAULT_SANDBOX_NAMESPACE;
+  const fileApproval = readConnectorProductionApproval(args.opts);
+  const directApproval = args.opts?.productionApproved === true && typeof args.opts.receipt === 'string' && args.opts.receipt.trim().length > 0;
+  const envRequestedProduction = envFlag('ARIA_CONNECTOR_PRODUCTION_APPROVED') || Boolean(process.env.ARIA_CONNECTOR_GOVERNANCE_RECEIPT);
+  const fileAllowsSurface = fileApproval?.surfaceIds ? fileApproval.surfaceIds.includes(args.surfaceId) : true;
+  const fileAllowsTarget = fileApproval?.allowedTargetRoots.some((root) => governedPathIsUnder(path.resolve(args.targetPath), root)) === true;
+  const fileApprovalUsable = fileApproval?.approved === true && fileAllowsSurface && fileAllowsTarget;
+  const productionApproved = directApproval || fileApprovalUsable;
+  const receipt = directApproval
+    ? args.opts?.receipt
+    : fileApprovalUsable
+      ? fileApproval?.receipt
+      : undefined;
+  if (envRequestedProduction && !productionApproved) {
+    throw new Error(`Aria connector governance blocked ${args.surfaceId} ${args.action ?? 'install'}: production_approval_file_required`);
+  }
+  const runner = new GovernedSurfaceRunner(buildConnectorGovernancePolicy(args.targetPath, args.opts));
+  const verdict = await runner.checkAction({
+    surfaceId: args.surfaceId,
+    action: args.action ?? 'install',
+    target: {
+      path: args.targetPath,
+      namespace,
+      description: args.reason,
+    },
+    sandbox: {
+      namespace,
+      root: args.opts?.sandboxRoot ?? process.env.ARIA_CONNECTOR_SANDBOX_ROOT ?? DEFAULT_SANDBOX_ROOT,
+    },
+    reason: args.reason,
+    verify: receipt
+      ? { verified: true, receipt, productionApproved }
+      : undefined,
+  });
+
+  if (!verdict.ok || verdict.blocked) {
+    const reason = verdict.reason ?? 'unknown';
+    throw new Error(`Aria connector governance blocked ${args.surfaceId} ${args.action ?? 'install'}: ${reason}`);
+  }
+
+  return verdict;
+}

package/src/connectors/opencode.ts

@@ -19,6 +19,7 @@ import { connectShell } from './shell.js';
 import { syncDoctrineTriggerMap } from './doctrine-trigger-map.js';
 import { buildMustReadGuide, mustReadIntro } from './must-read.js';
 import { resolveHarnessToken } from '../auth.js';
+import { requireGovernedConnectorMutation } from './governed-adapter.js';
 
 // ── Bundled OpenCode plugins ────────────────────────────────────────────────
 //
@@ -113,10 +114,17 @@ function resolveLocalRuntimeToken(): string {
   return '';
 }
 
-export async function connectOpenCode(config: AriaConfig): Promise<string[]> {
+export async function connectOpenCode(config: AriaConfig, opts: { installWrapper?: boolean } = {}): Promise<string[]> {
   const logs: string[] = [];
   const opencodeDir = path.join(homedir(), '.opencode');
 
+  await requireGovernedConnectorMutation({
+    surfaceId: 'opencode',
+    action: 'install',
+    targetPath: opencodeDir,
+    reason: 'install OpenCode harness surface',
+  });
+
   if (!existsSync(opencodeDir)) {
     logs.push('No ~/.opencode directory found — OpenCode may not be installed');
     return logs;
@@ -160,7 +168,11 @@ export async function connectOpenCode(config: AriaConfig): Promise<string[]> {
   }
 
   const bundledHooksDir = packageOpenCodeHooksDir();
+  const universalTurnPacketHookPath = path.join(bundledHooksDir, 'aria-universal-turn-packet.mjs');
   if (existsSync(bundledHooksDir)) {
+    if (!existsSync(universalTurnPacketHookPath)) {
+      throw new Error(`Bundled OpenCode universal turn packet hook missing: ${universalTurnPacketHookPath}`);
+    }
     copyPluginDir(bundledHooksDir, path.join(opencodeDir, 'hooks'), logs);
   } else {
     logs.push(`⚠ Bundled OpenCode hook helpers missing: ${bundledHooksDir} — gate plugins may fail to load`);
@@ -288,7 +300,11 @@ export async function connectOpenCode(config: AriaConfig): Promise<string[]> {
   const agentsContent = buildOpenCodeAgentsMd(config);
   writeFileSync(ariaAgentsPath, agentsContent);
   logs.push(`Wrote Aria harness AGENTS.md to ${ariaAgentsPath}`);
-  logs.push(...await connectShell('opencode', config));
+  if (opts.installWrapper === true) {
+    logs.push(...await connectShell('opencode', config));
+  } else {
+    logs.push('Skipped OpenCode shell wrapper install; OpenCode provider path remains untouched. Use aria connect --with-wrappers only when explicitly desired.');
+  }
 
   return logs;
 }

package/src/connectors/repo-guard.ts

@@ -13,7 +13,8 @@ import { fileURLToPath } from 'node:url';
 import type { AriaConfig } from '../config.js';
 import { loadConfig } from '../config.js';
 
-const ARIA_DIR = path.join(homedir(), '.aria');
+const HOME = process.env.ARIA_HOME || process.env.HOME || homedir();
+const ARIA_DIR = path.join(HOME, '.aria');
 const BIN_DIR = path.join(ARIA_DIR, 'bin');
 const ENV_PATH = path.join(ARIA_DIR, 'repo-guard.env');
 const STATE_PATH = path.join(ARIA_DIR, 'repo-guard-state.json');
@@ -197,27 +198,37 @@ function findRepoRoot(startDir: string): string | null {
   }
 }
 
+function uniqueRepoRoots(repos: Array<string | null | undefined>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const repo of repos) {
+    if (!repo) continue;
+    const resolved = findRepoRoot(repo);
+    if (!resolved || resolved === homedir() || seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
 function resolveRepos(config?: AriaConfig, explicit?: string[], fallbackRepoPath?: string): string[] {
-  if (explicit?.length) return explicit.map((repo) => path.resolve(repo)).filter(looksLikeRepoRoot);
+  if (explicit?.length) return uniqueRepoRoots(explicit);
 
   const envRepos = process.env.ARIA_REPO_GUARD_REPOS?.split(path.delimiter)
     .map((repo) => repo.trim())
     .filter(Boolean) || [];
-  if (envRepos.length) return envRepos.map((repo) => path.resolve(repo)).filter(looksLikeRepoRoot);
 
   const loaded = config || loadConfig();
   const configured = (loaded.repositories || [])
-    .map((repo) => path.resolve(repo.path))
-    .filter(looksLikeRepoRoot);
-  if (configured.length) return configured;
-
-  if (fallbackRepoPath) {
-    const resolvedFallback = findRepoRoot(fallbackRepoPath);
-    if (resolvedFallback) return [resolvedFallback];
-  }
+    .map((repo) => path.resolve(repo.path));
 
   const cwd = findRepoRoot(process.cwd());
-  return cwd ? [cwd] : [];
+  return uniqueRepoRoots([
+    ...envRepos,
+    ...configured,
+    fallbackRepoPath ? findRepoRoot(fallbackRepoPath) : null,
+    cwd,
+  ]);
 }
 
 export function isRepoGuardedPath(relPath: string): boolean {
@@ -507,6 +518,7 @@ function installSystemdUserService(logs: string[]): void {
   try {
     execFileSync(systemctlPath, ['--user', 'daemon-reload'], { stdio: 'ignore' });
     execFileSync(systemctlPath, ['--user', 'enable', '--now', 'aria-repo-guard.service'], { stdio: 'ignore' });
+    execFileSync(systemctlPath, ['--user', 'restart', 'aria-repo-guard.service'], { stdio: 'ignore' });
     logs.push('Enabled and started systemd user service: aria-repo-guard.service');
   } catch (error) {
     logs.push(`⚠ repo guard service installed but not activated: ${error instanceof Error ? error.message : String(error)}`);

package/src/connectors/runtime.ts

@@ -56,6 +56,51 @@ function trimUrl(value: string): string {
   return value.trim().replace(/\/+$/, '');
 }
 
+function parseEnvFile(text: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const index = line.indexOf('=');
+    if (index <= 0) continue;
+    const key = line.slice(0, index).trim();
+    const value = line.slice(index + 1);
+    env[key] = value;
+  }
+  return env;
+}
+
+function readProcessEnv(pid: string): Record<string, string> {
+  if (!pid || pid === '0') return {};
+  try {
+    return parseEnvFile(readFileSync(`/proc/${pid}/environ`, 'utf8').replace(/\0/g, '\n'));
+  } catch {
+    return {};
+  }
+}
+
+function redactPostgresUrl(value: string): string {
+  return value.replace(/(postgres(?:ql)?:\/\/[^:@/]+:)[^@/]+@/i, '$1<redacted>@');
+}
+
+function isLocalPostgresUrl(value: string): boolean {
+  try {
+    const parsed = new URL(value);
+    const host = parsed.hostname || 'localhost';
+    return /^postgres(?:ql)?:$/i.test(parsed.protocol) && ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(host);
+  } catch {
+    return false;
+  }
+}
+
+function firstLocalPostgresUrl(...values: Array<string | undefined>): string | null {
+  for (const value of values) {
+    const text = String(value || '').trim();
+    if (text && isLocalPostgresUrl(text)) return text;
+  }
+  return null;
+}
+
 function isLocalHarnessDaemonUrl(value: string): boolean {
   const normalized = trimUrl(value);
   return normalized === 'http://127.0.0.1:8790' || normalized === 'http://localhost:8790';
@@ -118,6 +163,12 @@ function writeRuntimeEnv(runtimeDst: string): string {
     process.env.ARIA_UPSTREAM_FORGE_SERVICE_URL ||
     process.env.ARIA_FORGE_UPSTREAM_URL ||
     `${upstreamHarnessUrl}/api/forge/psi`;
+  const fallbackHivePostgresUrl = firstLocalPostgresUrl(process.env.DATABASE_URL, process.env.POSTGRES_URL, process.env.PG_URL);
+  const hivePostgresUrl =
+    firstLocalPostgresUrl(process.env.ARIA_HIVE_POSTGRES_URL, process.env.ARIA_LOCAL_POSTGRES_URL) ||
+    fallbackHivePostgresUrl ||
+    'postgresql://127.0.0.1:5432/aria_hive';
+  const hiveStorageMode = process.env.ARIA_HIVE_STORAGE || (fallbackHivePostgresUrl ? 'postgres' : 'file');
   writeFileSync(
     envPath,
     [
@@ -139,6 +190,8 @@ function writeRuntimeEnv(runtimeDst: string): string {
       `ARIA_UPSTREAM_FORGE_SERVICE_URL=${upstreamForgeServiceUrl}`,
       'ARIA_QDRANT_URL=http://127.0.0.1:6333',
       'ARIA_QDRANT_COLLECTION=aria_garden_memory',
+      `ARIA_HIVE_STORAGE=${hiveStorageMode}`,
+      `ARIA_HIVE_POSTGRES_URL=${hivePostgresUrl}`,
       `ARIA_RUNTIME_DEFAULT_PROVIDER=${defaultProvider}`,
       `ARIA_CHAT_MODEL=${chatModel}`,
       `ARIA_DEEP_MODEL=${deepModel}`,
@@ -147,8 +200,6 @@ function writeRuntimeEnv(runtimeDst: string): string {
       `ARIA_DEEPSEEK_FALLBACK_MODEL=${deepModel}`,
       `ARIA_LOCAL_FALLBACK_MODEL=${localFallbackModel}`,
       `ARIA_LOCAL_FALLBACK_BASE_URL=${localFallbackBaseUrl}`,
-      'OPENAI_BASE_URL=http://127.0.0.1:4319/v1',
-      'ANTHROPIC_BASE_URL=http://127.0.0.1:4319',
       '',
     ].join('\n'),
     { mode: 0o600 },
@@ -534,6 +585,51 @@ function installLaunchAgent(ariaDir: string, logs: string[]): void {
   }
 }
 
+function verifyMountedRuntimeEnvPostcondition(envPath: string, logs: string[]): void {
+  const systemctlPath = '/bin/systemctl';
+  if (process.platform !== 'linux' || !existsSync(systemctlPath)) {
+    logs.push('Skipped mounted runtime env postcondition: requires Linux systemd user services.');
+    return;
+  }
+
+  const expected = parseEnvFile(readFileSync(envPath, 'utf8'));
+  const expectedStorage = expected.ARIA_HIVE_STORAGE || '';
+  const expectedPostgresUrl = expected.ARIA_HIVE_POSTGRES_URL || '';
+
+  execFileSync(systemctlPath, ['--user', 'restart', 'aria-mounted-runtime.service'], { stdio: 'ignore' });
+  logs.push('Restarted aria-mounted-runtime.service to reload runtime.env');
+
+  let pid = '';
+  let runtimeEnv: Record<string, string> = {};
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    try {
+      pid = execFileSync(systemctlPath, ['--user', 'show', 'aria-mounted-runtime.service', '-p', 'MainPID', '--value'], { encoding: 'utf8' }).trim();
+      runtimeEnv = readProcessEnv(pid);
+      if (
+        runtimeEnv.ARIA_HIVE_STORAGE === expectedStorage &&
+        runtimeEnv.ARIA_HIVE_POSTGRES_URL === expectedPostgresUrl
+      ) {
+        logs.push(`Verified mounted runtime env postcondition: ARIA_HIVE_STORAGE=${expectedStorage}, ARIA_HIVE_POSTGRES_URL=${redactPostgresUrl(expectedPostgresUrl)}`);
+        return;
+      }
+    } catch {}
+    try {
+      execFileSync('/bin/sleep', ['0.25'], { stdio: 'ignore' });
+    } catch {}
+  }
+
+  throw new Error(
+    [
+      'Mounted runtime env postcondition failed after restart.',
+      `expected ARIA_HIVE_STORAGE=${expectedStorage}`,
+      `actual ARIA_HIVE_STORAGE=${runtimeEnv.ARIA_HIVE_STORAGE || '<missing>'}`,
+      `expected ARIA_HIVE_POSTGRES_URL=${redactPostgresUrl(expectedPostgresUrl)}`,
+      `actual ARIA_HIVE_POSTGRES_URL=${redactPostgresUrl(runtimeEnv.ARIA_HIVE_POSTGRES_URL || '<missing>')}`,
+      `pid=${pid || '<missing>'}`,
+    ].join(' '),
+  );
+}
+
 export async function installSharedRuntime(): Promise<string[]> {
   const logs: string[] = [];
   const runtimeSrc = packageRuntimeDir();
@@ -588,6 +684,7 @@ export async function installSharedRuntime(): Promise<string[]> {
   installSystemdUserService(ariaDir, logs);
   installCodexBridgeSystemdUserService(ariaDir, logs);
   installLaunchAgent(ariaDir, logs);
+  verifyMountedRuntimeEnvPostcondition(envPath, logs);
 
   logs.push(`Installed shared Aria runtime → ${runtimeDst}`);
   logs.push(`Installed runtime wrapper → ${startWrapper}`);

package/src/connectors/shell.ts

@@ -3,6 +3,7 @@ import { execSync } from 'child_process';
 import { homedir } from 'os';
 import * as path from 'path';
 import type { AriaConfig } from '../config.js';
+import { requireGovernedConnectorMutation } from './governed-adapter.js';
 
 const ARIA_DIR = path.join(homedir(), '.aria');
 const WRAPPER_DIR = path.join(ARIA_DIR, 'wrappers');
@@ -68,7 +69,35 @@ fi
   }
 }
 
-function buildRuntimeInjectionBlock(): string {
+function buildRuntimeInjectionBlock(toolName: string): string {
+  const anthropicRouting = toolName === 'claude'
+    ? `if [ "\${ARIA_CLAUDE_USE_API_KEY:-0}" != "1" ]; then
+  unset ANTHROPIC_API_KEY
+  unset ANTHROPIC_AUTH_TOKEN
+  unset ANTHROPIC_CUSTOM_HEADERS
+fi
+if [ "\${ARIA_CLAUDE_USE_ARIA_RUNTIME:-0}" = "1" ]; then
+  export ANTHROPIC_BASE_URL="\${ANTHROPIC_BASE_URL:-$ARIA_RUNTIME_URL}"
+elif [ "\${ARIA_CLAUDE_USE_API_KEY:-0}" != "1" ]; then
+  unset ANTHROPIC_BASE_URL
+elif [ "\${ANTHROPIC_BASE_URL:-}" = "$ARIA_RUNTIME_URL" ] || [ "\${ANTHROPIC_BASE_URL:-}" = "\${ARIA_RUNTIME_URL%/}/" ]; then
+  unset ANTHROPIC_BASE_URL
+fi`
+    : toolName === 'codex'
+      ? 'unset ANTHROPIC_BASE_URL'
+    : `export ANTHROPIC_BASE_URL="\${ANTHROPIC_BASE_URL:-$ARIA_RUNTIME_URL}"`;
+  const openaiRouting = toolName === 'codex'
+    ? `if [ "\${ARIA_CODEX_USE_API_KEY:-0}" != "1" ]; then
+  unset OPENAI_API_KEY
+  unset OPENAI_BASE_URL
+  unset OPENAI_ORG_ID
+  unset OPENAI_ORGANIZATION
+  unset OPENAI_PROJECT
+fi
+if [ "\${ARIA_CODEX_USE_ARIA_RUNTIME:-0}" = "1" ] || [ "\${ARIA_CODEX_USE_BRIDGE:-0}" = "1" ]; then
+  export OPENAI_BASE_URL="\${OPENAI_BASE_URL:-$ARIA_RUNTIME_URL/v1}"
+fi`
+    : `export OPENAI_BASE_URL="\${OPENAI_BASE_URL:-$ARIA_RUNTIME_URL/v1}"`;
   return `
 RUNTIME_ENV="$HOME/.aria/runtime/runtime.env"
 if [ -f "$RUNTIME_ENV" ]; then
@@ -81,8 +110,8 @@ if [ -f "$ARIA_SECRETS_SH" ]; then
   . "$ARIA_SECRETS_SH"
 fi
 export ARIA_RUNTIME_URL="\${ARIA_RUNTIME_URL:-http://127.0.0.1:4319}"
-export OPENAI_BASE_URL="\${OPENAI_BASE_URL:-$ARIA_RUNTIME_URL/v1}"
-export ANTHROPIC_BASE_URL="\${ANTHROPIC_BASE_URL:-$ARIA_RUNTIME_URL}"
+${anthropicRouting}
+${openaiRouting}
 if [ -z "\${ARIA_HARNESS_TOKEN:-}" ]; then
   if [ -f "$HOME/.aria/owner-token" ]; then
     export ARIA_HARNESS_TOKEN="$(tr -d '\\n' < "$HOME/.aria/owner-token")"
@@ -100,11 +129,14 @@ fi
 }
 
 function buildToolExecBlock(toolName: string, toolPath: string): string {
+  const universalPacketBlock = buildUniversalTurnPacketExecBlock(toolName);
   if (toolName !== 'codex') {
-    return `exec "${toolPath}" "$@"`;
+    return `${universalPacketBlock}
+exec "${toolPath}" "$@"`;
   }
 
-  return `for arg in "$@"; do
+  return `${universalPacketBlock}
+for arg in "$@"; do
   if [ "$arg" = "--remote" ]; then
     exec "${toolPath}" "$@"
   fi
@@ -112,6 +144,8 @@ done
 
 case "\${1:-}" in
   app-server|exec-server|exec|review)
+    # ARIA_CODEX_EXEC_LOCAL_PROMPT_INJECTION: codex exec/review do not support --remote.
+    # Aria task runner injects the runtime-built skill packet into stdin for these modes.
     exec "${toolPath}" "$@"
     ;;
 esac
@@ -120,6 +154,11 @@ if [ "\${ARIA_CODEX_BYPASS_BRIDGE:-0}" = "1" ]; then
   exec "${toolPath}" "$@"
 fi
 
+if [ "\${ARIA_CODEX_USE_ARIA_RUNTIME:-0}" != "1" ] && [ "\${ARIA_CODEX_USE_BRIDGE:-0}" != "1" ]; then
+  exec "${toolPath}" "$@"
+fi
+
+export OPENAI_BASE_URL="\${OPENAI_BASE_URL:-$ARIA_RUNTIME_URL/v1}"
 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}"
@@ -153,6 +192,72 @@ fi
 exec "${toolPath}" --remote "ws://$ARIA_CODEX_BRIDGE_HOST:$ARIA_CODEX_BRIDGE_PORT" "$@"`;
 }
 
+function surfaceIdForTool(toolName: string): string {
+  if (toolName === 'claude') return 'claude-code';
+  if (toolName === 'codex') return 'codex';
+  if (toolName === 'opencode') return 'opencode';
+  return 'shell';
+}
+
+function buildUniversalTurnPacketExecBlock(toolName: string): string {
+  const surfaceId = surfaceIdForTool(toolName);
+  if (toolName === 'codex') {
+    return `
+ARIA_UNIVERSAL_TURN_PACKET_SCRIPT="$HOME/.aria/runtime/hooks/aria-universal-turn-packet.mjs"
+if [ ! -f "$ARIA_UNIVERSAL_TURN_PACKET_SCRIPT" ]; then
+  echo "Aria universal turn packet script missing at $ARIA_UNIVERSAL_TURN_PACKET_SCRIPT" >&2
+  exit 1
+fi
+
+aria_codex_skip_async_bootstrap() {
+  case "\${1:-}" in
+    --version|-V|version|help|-h|--help|app-server|exec-server)
+      return 0
+      ;;
+  esac
+  for _aria_arg in "$@"; do
+    if [ "$_aria_arg" = "--remote" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+aria_codex_start_async_bootstrap() {
+  if [ "\${ARIA_CODEX_DISABLE_ASYNC_BOOTSTRAP:-0}" = "1" ]; then
+    return 0
+  fi
+  _aria_bootstrap_dir="$HOME/.aria/codex-readiness"
+  mkdir -p "$_aria_bootstrap_dir" >/dev/null 2>&1 || return 0
+  _aria_bootstrap_id="codex-$USER-$$-$(date +%s)"
+  _aria_bootstrap_log="$_aria_bootstrap_dir/$_aria_bootstrap_id.log"
+  _aria_bootstrap_pid="$_aria_bootstrap_dir/$_aria_bootstrap_id.pid"
+  ARIA_SURFACE_ID="codex" \\
+    ARIA_SESSION_ID="$_aria_bootstrap_id" \\
+    ARIA_TURN_USER_TEXT="$*" \\
+    ARIA_CODEX_READINESS_SILENT=1 \\
+    nohup node "$ARIA_UNIVERSAL_TURN_PACKET_SCRIPT" >"$_aria_bootstrap_log" 2>&1 &
+  _aria_pid=$!
+  printf '%s\\n' "$_aria_pid" >"$_aria_bootstrap_pid" 2>/dev/null || true
+  export ARIA_CODEX_ASYNC_BOOTSTRAP_ID="$_aria_bootstrap_id"
+  export ARIA_CODEX_ASYNC_BOOTSTRAP_LOG="$_aria_bootstrap_log"
+}
+
+if ! aria_codex_skip_async_bootstrap "$@"; then
+  aria_codex_start_async_bootstrap "$@"
+fi
+`;
+  }
+  return `
+ARIA_UNIVERSAL_TURN_PACKET_SCRIPT="$HOME/.aria/runtime/hooks/aria-universal-turn-packet.mjs"
+if [ ! -f "$ARIA_UNIVERSAL_TURN_PACKET_SCRIPT" ]; then
+  echo "Aria universal turn packet script missing at $ARIA_UNIVERSAL_TURN_PACKET_SCRIPT" >&2
+  exit 1
+fi
+ARIA_SURFACE_ID="${surfaceId}" ARIA_TURN_USER_TEXT="$*" node "$ARIA_UNIVERSAL_TURN_PACKET_SCRIPT" >/dev/null
+`;
+}
+
 export async function connectShell(
   toolName: string,
   config: AriaConfig,
@@ -165,12 +270,19 @@ export async function connectShell(
     return logs;
   }
 
+  await requireGovernedConnectorMutation({
+    surfaceId: 'shell',
+    action: 'install',
+    targetPath: WRAPPER_DIR,
+    reason: `install shell wrapper for ${toolName}`,
+  });
+
   if (!existsSync(WRAPPER_DIR)) {
     mkdirSync(WRAPPER_DIR, { recursive: true });
   }
 
   const ariaBlock = buildShellWrapperBlock(config, toolName);
-  const runtimeBlock = buildRuntimeInjectionBlock();
+  const runtimeBlock = buildRuntimeInjectionBlock(toolName);
   const execBlock = buildToolExecBlock(toolName, toolPath);
   const wrapperPath = path.join(WRAPPER_DIR, toolName);
   const script = `#!/usr/bin/env bash
@@ -185,7 +297,13 @@ ${execBlock}
   chmodSync(wrapperPath, 0o755);
   ensureWrapperShellHook(logs);
   logs.push(`Created wrapper: ${wrapperPath}`);
-  logs.push(`${toolName} will route through the mounted Aria runtime on new shell sessions.`);
+  logs.push(
+    toolName === 'claude'
+      ? 'claude will use direct Anthropic login by default; set ARIA_CLAUDE_USE_API_KEY=1 or ARIA_CLAUDE_USE_ARIA_RUNTIME=1 only when explicitly desired.'
+      : toolName === 'codex'
+        ? 'codex will use direct login/default provider by default; set ARIA_CODEX_USE_API_KEY=1, ARIA_CODEX_USE_ARIA_RUNTIME=1, or ARIA_CODEX_USE_BRIDGE=1 only when explicitly desired.'
+      : `${toolName} will route through the mounted Aria runtime on new shell sessions.`,
+  );
 
   return logs;
 }