@aria_asi/cli 0.2.35 → 0.2.37

package/src/connectors/codex.ts

@@ -24,6 +24,15 @@ function packageSdkDir(): string {
   return path.resolve(here, '..', '..', '..', 'sdk');
 }
 
+function packageTaskProjectLedgerHelperPath(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.resolve(here, '..', '..', '..', '..', 'opencode-plugins', 'harness-context', 'task-project-ledger.mjs'),
+    path.resolve(here, '..', '..', '..', 'assets', 'opencode-plugins', 'harness-context', 'task-project-ledger.mjs'),
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) || candidates[0];
+}
+
 function installSdk(codexDir: string, logs: string[]): void {
   const sdkSrc = packageSdkDir();
   if (!existsSync(sdkSrc)) {
@@ -95,6 +104,9 @@ import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { HTTPHarnessClient } from '@aria_asi/harness-http-client';
+import { updateTaskProjectLedger, evaluateTaskProjectClaim, recordBlockedTaskProjectClaim } from './task-project-ledger.mjs';
+
+export { updateTaskProjectLedger, evaluateTaskProjectClaim, recordBlockedTaskProjectClaim };
 
 const HOME = homedir();
 const DEFAULT_RUNTIME_URL = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\\/+$/, '');
@@ -102,7 +114,7 @@ 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;
+  const envToken = process.env.ARIA_HARNESS_TOKEN || process.env.ARIA_API_KEY || process.env.ARIA_MASTER_TOKEN;
   if (envToken) return envToken;
   const ownerPath = path.join(HOME, '.aria', 'owner-token');
   if (existsSync(ownerPath)) return readFileSync(ownerPath, 'utf8').trim();
@@ -264,6 +276,24 @@ export async function runtimePost(route, body = {}) {
   return response.json();
 }
 
+export async function recordCoachPhase(phase, body = {}) {
+  try {
+    return await runtimePost('/coach/phase', {
+      phase,
+      surface: 'codex-hooks',
+      lane: 'codex_native_hooks',
+      ...body,
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      permitted: true,
+      decision: 'warn_operator_only',
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 export function classifyAction(event) {
   const toolName = String(event?.tool_name || event?.toolName || '').trim();
   const toolCommand = String(
@@ -307,6 +337,23 @@ export function extractAssistantText(event) {
   );
 }
 
+function normalizeValidationIssue(issue) {
+  const raw = String(issue || '').replace(/\\s+/g, ' ').trim();
+  if (!raw) return '';
+  if (/No <cognition>/i.test(raw)) return 'missing readable cognition block';
+  if (/missing\\s+<applied_cognition>/i.test(raw)) return 'missing applied cognition contract';
+  if (/qualitative_drift/i.test(raw)) return 'qualitative drift language needs a measurable predicate';
+  if (/premature_task_closeout|feedback_no_premature_task_closeout|done\\|complete\\|completed\\|ready\\|verified\\|fixed/i.test(raw)) {
+    return 'completion/readiness claim conflicts with unresolved blocker state';
+  }
+  if (/\\(\\?:/.test(raw)) return 'doctrine matcher triggered; re-author with the named doctrine and concrete evidence';
+  return raw.slice(0, 600);
+}
+
+function uniqueStrings(values) {
+  return Array.from(new Set(values.map(normalizeValidationIssue).filter(Boolean)));
+}
+
 export function formatValidationFailure(result) {
   const parts = [];
   if (Array.isArray(result?.validation?.violations) && result.validation.violations.length) {
@@ -318,7 +365,31 @@ export function formatValidationFailure(result) {
   if (!parts.length && typeof result?.summary === 'string' && result.summary.trim()) {
     parts.push(result.summary.trim());
   }
-  return parts.join(' | ') || 'Aria validation failed.';
+  return uniqueStrings(parts).join(' | ') || 'Aria validation failed.';
+}
+
+export function isAriaControlBlock(text) {
+  return /^(?:ARIA CODEX RECOVERY CONTRACT|Aria runtime blocked final output for this Codex turn\\.|Aria stop gate blocked output:|Aria task\\/project ledger blocked output claim\\.|Aria stop hook failed closed:)/i.test(String(text || '').trim());
+}
+
+export function formatCodexRecoveryBlock({ surface = 'codex', reason = '', issues = [], next = '' } = {}) {
+  const blockers = uniqueStrings([reason, ...issues]);
+  return [
+    'ARIA CODEX RECOVERY CONTRACT',
+    'surface: ' + surface,
+    'status: output held for re-authoring',
+    '',
+    'Observed blockers:',
+    ...(blockers.length ? blockers.map((item) => '- ' + item) : ['- Aria validation failed.']),
+    '',
+    'Recovery contract:',
+    '1. Do not retry the same blocked text.',
+    '2. Re-author the answer from the user request, not from this block report.',
+    '3. Include <cognition> and <applied_cognition> when the answer is non-trivial.',
+    '4. Use bounded status language when evidence is missing; do not use completion/readiness claims without proof.',
+    '5. Name a measurable verification predicate, or explicitly state that verification has not run.',
+    next || '6. Re-submit the corrected answer; if the same blocker repeats twice, escalate with this full recovery contract.',
+  ].join('\\n');
 }
 
 export function emitJson(payload, code = 0) {
@@ -355,9 +426,12 @@ import {
   makeEvidenceRef,
   readEventFromStdin,
   runtimePost,
+  recordCoachPhase,
   loadTurnState,
   saveTurnState,
   runGovernanceGate,
+  updateTaskProjectLedger,
+  formatCodexRecoveryBlock,
   emitJson,
 } from './lib/runtime-client.mjs';
 
@@ -368,8 +442,21 @@ const sessionId = inferSessionId(event);
 const userId = inferUserId(event);
 const priorState = loadTurnState(sessionId);
 const traceId = ensureTraceId(priorState);
+const ledgerResult = updateTaskProjectLedger({
+  platform: 'codex',
+  phase: 'pre_prompt_injection',
+  source: 'codex-userprompt-hook',
+  event: { ...event, prompt: userText, sessionId, cwd: process.cwd() },
+});
 
 try {
+  await recordCoachPhase('pre_turn', {
+    requestId: traceId,
+    sessionId,
+    text: userText,
+    evidenceRefs: [makeEvidenceRef('user_input', userText, { sessionId, traceId, platform: 'codex' })],
+    metadata: { source: 'codex-userprompt-hook', userId },
+  });
   const packet = await client.getHarnessPacket({
     sessionId,
     platform: 'codex',
@@ -404,11 +491,19 @@ try {
       evidenceRefs: [packetRef],
     },
   });
+  await recordCoachPhase('post_cognition', {
+    requestId: traceId,
+    sessionId,
+    text: userText,
+    evidenceRefs: [packetRef, makeEvidenceRef('mizan_pre_receipt', result?.receipt || null, { sessionId, traceId })],
+    metadata: { source: 'codex-userprompt-hook', pre_receipt_id: result?.receipt?.receiptId || null },
+  });
   saveTurnState(sessionId, {
     traceId,
     userId,
     userText,
     preReceiptId: result?.receipt?.receiptId || null,
+    taskProjectLedgerId: ledgerResult.ledger.ledgerId,
     packetTimestamp: packet?.timestamp || null,
     packetRef,
     lastEvent: 'UserPromptSubmit',
@@ -417,7 +512,11 @@ try {
 } catch (error) {
   emitJson({
     decision: 'block',
-    reason: \`Aria cognition gate failed before turn start: \${error instanceof Error ? error.message : String(error)}\`,
+    reason: formatCodexRecoveryBlock({
+      surface: 'codex-userprompt',
+      reason: error instanceof Error ? error.message : String(error),
+      next: '6. Re-open the prompt substrate, repair the cognition gate blocker, then submit the prompt again.',
+    }),
   });
 }
 `;
@@ -426,18 +525,23 @@ try {
 function buildCodexPreToolHook(): string {
   return `#!/usr/bin/env node
 import {
+  getHarnessClient,
   inferSessionId,
   classifyAction,
   summarizeTarget,
   readEventFromStdin,
   loadTurnState,
   makeEvidenceRef,
+  recordCoachPhase,
   saveTurnState,
   runGovernanceGate,
+  updateTaskProjectLedger,
+  formatCodexRecoveryBlock,
   emitJson,
 } from './lib/runtime-client.mjs';
 
 const event = readEventFromStdin();
+const client = getHarnessClient();
 const sessionId = inferSessionId(event);
 const action = classifyAction(event);
 const target = summarizeTarget(event);
@@ -447,17 +551,52 @@ try {
   if (!state?.preReceiptId && !state?.userText) {
     emitJson({
       decision: 'block',
-      reason: 'Aria pre-tool gate blocked action because this turn has no pre-turn Mizan receipt. Re-submit the prompt so cognition is established before tool use.',
+      reason: formatCodexRecoveryBlock({
+        surface: 'codex-pre-tool',
+        reason: 'this turn has no pre-turn Mizan receipt',
+        next: '6. Re-submit the prompt so cognition is established before tool use, then request the tool again.',
+      }),
+    });
+  }
+  const toolName = String(event?.tool_name || event?.toolName || '').trim() || null;
+  const requestRef = makeEvidenceRef('codex_tool_request', { action, toolName, target }, { sessionId });
+  const coach = await recordCoachPhase('pre_tool', {
+    requestId: state?.traceId || sessionId,
+    sessionId,
+    text: target,
+    action,
+    target,
+    evidenceRefs: [requestRef],
+    metadata: { source: 'codex-pre-tool-hook', toolName, requireVerify: action === 'deploy' || action === 'delete' },
+  });
+  if (coach?.permitted === false) {
+    emitJson({
+      decision: 'block',
+      reason: formatCodexRecoveryBlock({
+        surface: 'codex-pre-tool-coach',
+        reason: coach.clientMessage || 'Coach Kernel denied ' + action,
+        next: '6. Add the required evidence/cognition contract, then request the tool again.',
+      }),
     });
   }
   const actionCheck = await client.checkAction(action, target);
   if (actionCheck?.allowed === false) {
     emitJson({
       decision: 'block',
-      reason: actionCheck?.reason || \`Aria denied \${action}\`,
+      reason: formatCodexRecoveryBlock({
+        surface: 'codex-pre-tool-action',
+        reason: actionCheck?.reason || \`Aria denied \${action}\`,
+        next: '6. Add the required verification/cognition contract for the action, then request the tool again.',
+      }),
     });
   }
-  const toolName = String(event?.tool_name || event?.toolName || '').trim() || null;
+  updateTaskProjectLedger({
+    platform: 'codex',
+    phase: 'pre_tool',
+    source: 'codex-pre-tool-hook',
+    event: { ...event, sessionId, cwd: process.cwd() },
+    evidence: { action_ref: requestRef },
+  });
   runGovernanceGate({
     sessionId,
     sourceRuntime: 'codex',
@@ -467,7 +606,7 @@ try {
     toolName,
     isDeploy: action === 'deploy',
     isMutation: action === 'write' || action === 'delete',
-    evidence: makeEvidenceRef('codex_tool_request', { action, toolName, target }, { sessionId }),
+    evidence: requestRef,
   });
   const tools = Array.isArray(state?.tools) ? state.tools.slice(-24) : [];
   tools.push({
@@ -485,7 +624,10 @@ try {
 } catch (error) {
   emitJson({
     decision: 'block',
-    reason: \`Aria pre-tool hook failed closed: \${error instanceof Error ? error.message : String(error)}\`,
+    reason: formatCodexRecoveryBlock({
+      surface: 'codex-pre-tool-hook',
+      reason: error instanceof Error ? error.message : String(error),
+    }),
   });
 }
 `;
@@ -498,7 +640,9 @@ import {
   readEventFromStdin,
   loadTurnState,
   makeEvidenceRef,
+  recordCoachPhase,
   saveTurnState,
+  updateTaskProjectLedger,
 } from './lib/runtime-client.mjs';
 
 const event = readEventFromStdin();
@@ -512,6 +656,20 @@ try {
     toolName: event?.tool_name || event?.toolName || null,
   });
   const toolOutputs = Array.isArray(state?.toolOutputs) ? state.toolOutputs.slice(-24) : [];
+  const verificationText = JSON.stringify(event).slice(0, 8000);
+  const verification = !event?.error && /\\b(?:npm\\s+run\\s+(?:check|test|build|lint|typecheck)|(?:npx\\s+)?(?:jest|vitest|tsc|eslint)|check:|test:|build:|passed|exit\\s*0|0\\s*failures?)\\b/i.test(verificationText);
+  await recordCoachPhase('post_tool', {
+    requestId: state?.traceId || sessionId,
+    sessionId,
+    text: verificationText,
+    evidenceRefs: [evidenceRef],
+    metadata: {
+      source: 'codex-post-tool-hook',
+      toolName: event?.tool_name || event?.toolName || null,
+      verification,
+      error: event?.error || null,
+    },
+  });
   toolOutputs.push({
     at: new Date().toISOString(),
     toolName: event?.tool_name || event?.toolName || null,
@@ -522,6 +680,17 @@ try {
     toolOutputs,
     lastEvent: 'PostToolUse',
   });
+  updateTaskProjectLedger({
+    platform: 'codex',
+    phase: 'post_tool',
+    source: 'codex-post-tool-hook',
+    event: { ...event, sessionId, cwd: process.cwd() },
+    evidence: {
+      outcome_ref: evidenceRef,
+      verification,
+      commandResult: verification ? 'success' : '',
+    },
+  });
   process.exit(0);
 } catch {
   process.exit(0);
@@ -536,11 +705,17 @@ import {
   extractAssistantText,
   readEventFromStdin,
   runtimePost,
+  recordCoachPhase,
   loadTurnState,
   makeEvidenceRef,
   clearTurnState,
   formatValidationFailure,
+  formatCodexRecoveryBlock,
+  isAriaControlBlock,
   runGovernanceGate,
+  updateTaskProjectLedger,
+  evaluateTaskProjectClaim,
+  recordBlockedTaskProjectClaim,
   emitJson,
 } from './lib/runtime-client.mjs';
 
@@ -550,11 +725,58 @@ 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) : [];
+const ledgerResult = updateTaskProjectLedger({
+  platform: 'codex',
+  phase: 'stop',
+  source: 'codex-stop-hook',
+  event: { ...event, text, sessionId, cwd: process.cwd() },
+});
 
 try {
   if (!text) {
     emitJson({ continue: true });
   }
+  if (isAriaControlBlock(text)) {
+    clearTurnState(sessionId);
+    emitJson({ continue: true });
+  }
+  const postGenerationCoach = await recordCoachPhase('post_generation', {
+    requestId: state?.traceId || sessionId,
+    sessionId,
+    text,
+    evidenceRefs: [outputRef],
+    metadata: { source: 'codex-stop-hook', requireCognitionBlock: false, requireAppliedCognition: false },
+  });
+  if (postGenerationCoach?.permitted === false) {
+    emitJson({
+      decision: 'block',
+      reason: formatCodexRecoveryBlock({
+        surface: 'codex-stop-coach-post-generation',
+        reason: postGenerationCoach.clientMessage || 'Coach Kernel held Codex output before validation.',
+      }),
+    });
+  }
+  const ledgerClaim = evaluateTaskProjectClaim({ text, ledger: ledgerResult.ledger });
+  if (!ledgerClaim.ok) {
+    recordBlockedTaskProjectClaim({
+      ledger: ledgerResult.ledger,
+      paths: ledgerResult.paths,
+      text,
+      evaluation: ledgerClaim,
+    });
+    emitJson({
+      decision: 'block',
+      reason: formatCodexRecoveryBlock({
+        surface: 'codex-stop-ledger',
+        reason: 'task/project ledger rejected an output claim',
+        issues: [
+          \`missing readiness gates: \${ledgerClaim.missingReadinessGates.join(', ') || 'none'}\`,
+          \`open blockers: \${ledgerClaim.openBlockers.length}\`,
+        ],
+        next: '6. Record real verification evidence or emit bounded status without completion/readiness language, then re-submit.',
+      }),
+    });
+  }
   runGovernanceGate({
     sessionId,
     sourceRuntime: 'codex',
@@ -577,10 +799,31 @@ try {
     requireCognitionBlock: false,
     runLayer3: true,
   });
+  const preOutputCoach = await recordCoachPhase('pre_output', {
+    requestId: state?.traceId || sessionId,
+    sessionId,
+    text,
+    validation: validation?.validation || null,
+    layer3: validation?.layer3 || null,
+    evidenceRefs: [outputRef, makeEvidenceRef('runtime_validation', validation, { sessionId, traceId: state?.traceId || null })],
+    metadata: { source: 'codex-stop-hook', requireCognitionBlock: false, requireAppliedCognition: false },
+  });
+  if (preOutputCoach?.permitted === false) {
+    emitJson({
+      decision: 'block',
+      reason: formatCodexRecoveryBlock({
+        surface: 'codex-stop-coach-pre-output',
+        reason: preOutputCoach.clientMessage || 'Coach Kernel held Codex output before release.',
+      }),
+    });
+  }
   if (validation?.pass === false || validation?.validation?.passed === false || validation?.layer3?.pass === false) {
     emitJson({
       decision: 'block',
-      reason: \`Aria stop gate blocked output: \${formatValidationFailure(validation)}\`,
+      reason: formatCodexRecoveryBlock({
+        surface: 'codex-stop-output',
+        reason: formatValidationFailure(validation),
+      }),
     });
   }
   const post = await runtimePost('/mizan/post', {
@@ -605,6 +848,18 @@ try {
     },
     parentReceiptId: state?.preReceiptId || null,
   });
+  await recordCoachPhase('post_output', {
+    requestId: state?.traceId || sessionId,
+    sessionId,
+    text,
+    validation: validation?.validation || null,
+    layer3: validation?.layer3 || null,
+    evidenceRefs: [
+      outputRef,
+      makeEvidenceRef('mizan_post_receipt', post?.receipt || null, { sessionId, traceId: state?.traceId || null }),
+    ],
+    metadata: { source: 'codex-stop-hook', requireCognitionBlock: false, requireAppliedCognition: false },
+  });
   await runtimePost('/decision/log', {
     session_id: sessionId,
     decision_type: 'operational',
@@ -641,12 +896,51 @@ try {
       },
     });
   }
+  updateTaskProjectLedger({
+    platform: 'codex',
+    phase: 'post_turn',
+    source: 'codex-stop-hook',
+    event: { ...event, text, sessionId, cwd: process.cwd() },
+    evidence: {
+      post_turn: true,
+      output_ref: outputRef,
+      verification: false,
+    },
+  });
+  const releaseCoach = await recordCoachPhase('claim_or_release', {
+    requestId: state?.traceId || sessionId,
+    sessionId,
+    text,
+    validation: validation?.validation || null,
+    layer3: validation?.layer3 || null,
+    evidenceRefs: [outputRef, ...toolRefs],
+    metadata: {
+      source: 'codex-stop-hook',
+      validated_output: true,
+      requireCognitionBlock: false,
+      requireAppliedCognition: false,
+      post_receipt_id: post?.receipt?.receiptId || null,
+    },
+  });
+  if (releaseCoach?.permitted === false) {
+    emitJson({
+      decision: 'block',
+      reason: formatCodexRecoveryBlock({
+        surface: 'codex-stop-coach-release',
+        reason: releaseCoach.clientMessage || 'Coach Kernel held the release claim.',
+      }),
+    });
+  }
   clearTurnState(sessionId);
   emitJson({ continue: true });
 } catch (error) {
   emitJson({
     decision: 'block',
-    reason: \`Aria stop hook failed closed: \${error instanceof Error ? error.message : String(error)}\`,
+    reason: formatCodexRecoveryBlock({
+      surface: 'codex-stop-hook',
+      reason: error instanceof Error ? error.message : String(error),
+      next: '6. Re-open the turn substrate, repair the hook/runtime blocker, and re-submit with this recovery contract if it repeats.',
+    }),
   });
 }
 `;
@@ -694,6 +988,10 @@ function installCodexHooksConfig(codexDir: string, logs: string[]): void {
 function installCodexHooks(codexDir: string, logs: string[]): void {
   const hooksDir = path.join(codexDir, 'hooks');
   mkdirSync(path.join(hooksDir, 'lib'), { recursive: true, mode: 0o755 });
+  const ledgerHelperSrc = packageTaskProjectLedgerHelperPath();
+  if (!existsSync(ledgerHelperSrc)) {
+    throw new Error(`Task/project ledger helper missing: ${ledgerHelperSrc}`);
+  }
 
   const files: Array<[string, string]> = [
     [path.join(hooksDir, 'lib', 'runtime-client.mjs'), buildCodexHookRuntimeClient()],
@@ -707,6 +1005,8 @@ function installCodexHooks(codexDir: string, logs: string[]): void {
     writeFileSync(filePath, content, { mode: 0o755 });
     try { chmodSync(filePath, 0o755); } catch {}
   }
+  copyFileSync(ledgerHelperSrc, path.join(hooksDir, 'lib', 'task-project-ledger.mjs'));
+  try { chmodSync(path.join(hooksDir, 'lib', 'task-project-ledger.mjs'), 0o755); } catch {}
 
   logs.push(`Installed Codex native hooks → ${hooksDir}`);
   installCodexHooksConfig(codexDir, logs);

package/src/connectors/opencode.ts

@@ -18,6 +18,7 @@ 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';
+import { resolveHarnessToken } from '../auth.js';
 
 // ── Bundled OpenCode plugins ────────────────────────────────────────────────
 //
@@ -33,6 +34,8 @@ import { buildMustReadGuide, mustReadIntro } from './must-read.js';
 // Both live at <pkg>/opencode-plugins/<name>/. connectOpenCode copies them
 // into ~/.opencode/plugins/<name>/ and wires the absolute paths into
 // ~/.opencode/config.json's `plugin` (singular, OpenCode v2 schema) array.
+// Shared hook helpers are also copied into ~/.opencode/hooks/ because the
+// installed plugins resolve their gate helpers from that OpenCode-owned root.
 //
 // Compiled location of THIS file (claude-code path applies the same way):
 //   <pkg>/dist/aria-connector/src/connectors/opencode.js
@@ -51,6 +54,16 @@ function packageOpenCodePluginsDir(): string {
   return found || candidates[0];
 }
 
+function packageOpenCodeHooksDir(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.resolve(here, '..', '..', '..', '..', 'hooks'),
+    path.resolve(here, '..', '..', '..', 'assets', 'hooks'),
+  ];
+  const found = candidates.find((candidate) => existsSync(candidate));
+  return found || candidates[0];
+}
+
 function copyPluginDir(srcDir: string, dstDir: string, logs: string[]): void {
   if (!existsSync(dstDir)) {
     mkdirSync(dstDir, { recursive: true, mode: 0o755 });
@@ -58,8 +71,12 @@ function copyPluginDir(srcDir: string, dstDir: string, logs: string[]): void {
   for (const name of readdirSync(srcDir)) {
     const src = path.join(srcDir, name);
     const stat = statSync(src);
-    if (!stat.isFile()) continue;
     const dst = path.join(dstDir, name);
+    if (stat.isDirectory()) {
+      copyPluginDir(src, dst, logs);
+      continue;
+    }
+    if (!stat.isFile()) continue;
     copyFileSync(src, dst);
     if (name.endsWith('.mjs') || name.endsWith('.js')) {
       try {
@@ -141,11 +158,22 @@ export async function connectOpenCode(config: AriaConfig): Promise<string[]> {
     copyPluginDir(srcDir, dstDir, logs);
     installedPaths.push(dstDir);
   }
+
+  const bundledHooksDir = packageOpenCodeHooksDir();
+  if (existsSync(bundledHooksDir)) {
+    copyPluginDir(bundledHooksDir, path.join(opencodeDir, 'hooks'), logs);
+  } else {
+    logs.push(`⚠ Bundled OpenCode hook helpers missing: ${bundledHooksDir} — gate plugins may fail to load`);
+  }
   syncDoctrineTriggerMap(logs);
 
-  // ── Wire ~/.opencode/config.json ──────────────────────────────────────────
-  const configPath = path.join(opencodeDir, 'config.json');
-  if (existsSync(configPath)) {
+  // ── Wire OpenCode config files ────────────────────────────────────────────
+  const configPaths = [
+    path.join(opencodeDir, 'config.json'),
+    path.join(homedir(), '.config', 'opencode', 'config.json'),
+  ];
+  for (const configPath of configPaths) {
+    if (!existsSync(configPath)) continue;
     try {
       const opencodeConfig: Record<string, unknown> = JSON.parse(
         readFileSync(configPath, 'utf-8'),
@@ -191,19 +219,14 @@ export async function connectOpenCode(config: AriaConfig): Promise<string[]> {
         logs.push(`Wired ${installedPaths.length} Aria plugin(s) into OpenCode config.plugin`);
       }
 
-      if (!opencodeConfig.agentsMdPath) {
-        opencodeConfig.agentsMdPath = path.join(homedir(), '.aria', 'AGENTS.md');
-        modified = true;
-        logs.push('Set OpenCode AGENTS.md path to ~/.aria/AGENTS.md');
-      }
-
       const providerMap = opencodeConfig.provider && typeof opencodeConfig.provider === 'object'
         ? opencodeConfig.provider as Record<string, unknown>
         : {};
       const currentAriaProvider = providerMap.aria && typeof providerMap.aria === 'object'
         ? providerMap.aria as Record<string, unknown>
         : {};
-      const localToken = resolveLocalRuntimeToken();
+      const resolvedLocalToken = await resolveHarnessToken({ baseUrl: LOCAL_RUNTIME_V1_URL });
+      const localToken = resolvedLocalToken.token || resolveLocalRuntimeToken();
       const nextAriaProvider = {
         npm: '@ai-sdk/openai-compatible',
         name: 'Aria Runtime',
@@ -252,7 +275,7 @@ export async function connectOpenCode(config: AriaConfig): Promise<string[]> {
         logs.push('OpenCode already configured for Aria');
       }
     } catch {
-      logs.push('Failed to parse OpenCode config.json');
+      logs.push(`Failed to parse OpenCode config.json at ${configPath}`);
     }
   }