@aria_asi/cli 0.2.39 → 0.2.41

package/runtime-src/sub-agent-enforcer.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * Sub-Agent Harness Enforcer
+ *
+ * When a sub-agent is spawned (task tool, Codex bridge, parallel worker),
+ * this module enforces the full harness stack on its context and output:
+ *
+ *   1. Pre-task: coach phase recorded, skills detected, axioms injected
+ *   2. Post-task: quality enforcement, doctrine trigger check, gate labels blocked
+ *   3. Coach ledger: sub-agent session tracked separately
+ *   4. Parent context: sub-agent output wrapped with enforcement provenance
+ *
+ * No sub-agent runs naked. Every one gets harness enforcement.
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// M0.F.X2 step 8 (2026-05-06): connector-side runtime-rails registry.
+// Same source pattern as apps-side sub-agent-enforcer.
+import {
+  INTERNAL_GATE_LABEL_PATTERN,
+  COLLAPSE_PLACEHOLDER_PATTERN,
+} from './runtime-rails/registry.mjs';
+
+const HOME = homedir();
+const STATE_DIR = join(HOME, '.aria', 'runtime', 'state');
+const SUBAGENT_LEDGER = join(STATE_DIR, 'subagent-enforcement.jsonl');
+
+function ensureDir() {
+  if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 });
+}
+
+function log(record) {
+  ensureDir();
+  try { appendFileSync(SUBAGENT_LEDGER, `${JSON.stringify(record)}\n`, { mode: 0o600 }); }
+  catch (err) {
+    process.stderr.write(`[connector:sub-agent-enforcer:ledger-write] caught: ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}
+
+// ── Quality patterns that sub-agents commonly violate ──────────────────────
+// M0.F.X2: GATE_LABEL_RX sourced from canonical registry. Combined check
+// in tripsSubAgentGate (matches internal-label OR collapse-placeholder).
+function tripsSubAgentGate(text) {
+  return INTERNAL_GATE_LABEL_PATTERN.test(text) || COLLAPSE_PLACEHOLDER_PATTERN.test(text);
+}
+const GATE_LABEL_RX = INTERNAL_GATE_LABEL_PATTERN; // legacy alias for downstream call sites
+
+const UNSAFE_COMPLETION_RX = /\b(?:done|complete|ready|fixed|shipped|all done|all phases complete)\b/i;
+
+const SUBAGENT_SAFE_FALLBACK =
+  '[Sub-agent enforcement applied — output was blocked or empty. Parent should re-query or re-spawn.]';
+
+// ── Coach Phase Record ─────────────────────────────────────────────────────
+
+const COACH_PHASES = ['pre_task', 'post_task', 'intra_task', 'claim_or_release'];
+
+export function recordSubAgentCoach(event) {
+  const record = {
+    coachEventId: randomUUID(),
+    sessionId: event.sessionId || 'subagent',
+    parentSessionId: event.parentSessionId || 'unknown',
+    phase: COACH_PHASES.includes(event.phase) ? event.phase : 'pre_task',
+    taskId: event.taskId || null,
+    subagentType: event.subagentType || 'unknown',
+    textPreview: String(event.text || '').slice(0, 500),
+    evidenceRefs: Array.isArray(event.evidenceRefs) ? event.evidenceRefs.slice(0, 10) : [],
+    decision: 'allow',
+    at: new Date().toISOString(),
+  };
+
+  // Check for common sub-agent failure patterns
+  const text = String(event.text || '');
+  if (GATE_LABEL_RX.test(text)) {
+    record.decision = 'repair_once';
+    record.reasons = ['gate_label_in_subagent_output'];
+  }
+  if (UNSAFE_COMPLETION_RX.test(text) && !/(?:exit\s*0|0\s+failures?|passed|verified)/i.test(text)) {
+    record.decision = 'repair_once';
+    record.reasons = [...(record.reasons || []), 'unsupported_completion_claim_in_subagent'];
+  }
+  if (!text || text.length < 20) {
+    record.decision = 'repair_once';
+    record.reasons = [...(record.reasons || []), 'subagent_output_too_short'];
+  }
+
+  log(record);
+  return record;
+}
+
+// ── Quality Enforcement on Sub-Agent Output ────────────────────────────────
+
+export function enforceSubAgentOutput(output, options = {}) {
+  const text = typeof output === 'string' ? output : (output?.text || output?.response || String(output || ''));
+  const subagentType = options.subagentType || 'unknown';
+  const sessionId = options.sessionId || 'subagent';
+
+  const violations = [];
+  if (!text || text.length < 10) violations.push('empty_output');
+  if (GATE_LABEL_RX.test(text)) violations.push('gate_label_leak');
+  if (UNSAFE_COMPLETION_RX.test(text) && !/(?:exit\s*0|0\s+failures?|passed|verified|test|ledger)/i.test(text)) {
+    violations.push('unsupported_completion_claim');
+  }
+
+  const enforced = violations.length > 0;
+  const finalText = enforced ? (options.safeFallback || SUBAGENT_SAFE_FALLBACK) : text;
+
+  if (enforced) {
+    log({
+      type: 'subagent_violation',
+      violationId: randomUUID(),
+      sessionId,
+      subagentType,
+      violations,
+      textPreview: text.slice(0, 200),
+      textHash: createHash('sha256').update(text).digest('hex').slice(0, 16),
+      enforced: true,
+      finalOutcome: 'safe_fallback',
+      at: new Date().toISOString(),
+    });
+  }
+
+  return {
+    finalText,
+    enforced,
+    violations,
+    originalLength: text.length,
+    finalLength: finalText.length,
+  };
+}
+
+// ── Pre-Task Injection: Build sub-agent system prompt with harness ─────────
+
+export function buildSubAgentHarnessPrompt(parentContext = {}) {
+  return [
+    '[SUB-AGENT HARNESS — This task is supervised by Aria Coach Kernel]',
+    '',
+    'Rules:',
+    '1. No internal gate labels may appear in your output (personal_mouth_*, code_no_tests, etc.)',
+    '2. No unsupported completion claims without measured evidence (exit codes, test results)',
+    '3. Your output will be quality-enforced before reaching the parent agent',
+    '4. The Coach kernel is monitoring this session',
+    '5. Truth over deception. No harm. Sacred trust. Power obligates service. Reflection before action.',
+    '',
+    parentContext.taskDescription
+      ? `Task: ${parentContext.taskDescription.slice(0, 300)}`
+      : '',
+    '[/SUB-AGENT HARNESS]',
+  ].filter(Boolean).join('\n');
+}
+
+// ── Sub-Agent Session Tracker ──────────────────────────────────────────────
+
+const activeSessions = new Map();
+
+export function trackSubAgentSession(taskId, metadata = {}) {
+  const session = {
+    taskId,
+    startedAt: new Date().toISOString(),
+    subagentType: metadata.subagentType || 'unknown',
+    parentSessionId: metadata.parentSessionId || 'unknown',
+    phase: 'pre_task',
+  };
+  activeSessions.set(taskId, session);
+  recordSubAgentCoach({
+    sessionId: taskId,
+    parentSessionId: metadata.parentSessionId,
+    subagentType: metadata.subagentType,
+    phase: 'pre_task',
+    taskId,
+    text: metadata.taskDescription || '',
+  });
+  return session;
+}
+
+export function completeSubAgentSession(taskId, output) {
+  const session = activeSessions.get(taskId);
+  if (!session) return null;
+  session.phase = 'post_task';
+  session.completedAt = new Date().toISOString();
+  const enforcement = enforceSubAgentOutput(output, {
+    subagentType: session.subagentType,
+    sessionId: taskId,
+  });
+  recordSubAgentCoach({
+    sessionId: taskId,
+    parentSessionId: session.parentSessionId,
+    subagentType: session.subagentType,
+    phase: 'post_task',
+    taskId,
+    text: enforcement.finalText,
+  });
+  activeSessions.delete(taskId);
+  return { ...session, enforcement };
+}
+
+export function getActiveSubAgentCount() {
+  return activeSessions.size;
+}

package/scripts/aria-ledger-append.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, '..', '..', '..');
+const defaultCorpusRoot = resolve(repoRoot, 'codex', 'plans', 'aria-civilizational-corpus-skills');
+
+const READINESS_FILE = 'UNIVERSAL_CONNECTOR_PROMOTION_READINESS.md';
+const LEDGER_FILE = 'UNIVERSAL_CONNECTOR_WIRING_LEDGER.md';
+const MANIFEST_FILE = 'UNIVERSAL_CONNECTOR_PROMOTION_EVIDENCE_MANIFEST.json';
+const LEDGER_MARKER = '\n---\n\n## Standing Bottom-Of-Ledger Anti-Drift Contract';
+const VALID_STATUSES = new Set(['blocked_partial', 'blocked', 'verified', 'pending', 'completed']);
+const SECRET_PATTERNS = [
+  /sk-[A-Za-z0-9_-]{20,}/,
+  /AKIA[0-9A-Z]{16}/,
+  /BEGIN (?:RSA |OPENSSH |EC |DSA )?PRIVATE KEY/,
+  /\b(?:api[_-]?key|token|secret)\b\s*[:=]\s*['"]?[A-Za-z0-9_./+=-]{20,}/i,
+];
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--event') {
+      args.eventPath = argv[index + 1];
+      index += 1;
+    } else if (arg === '--help' || arg === '-h') {
+      args.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return args;
+}
+
+function usage() {
+  return [
+    'Usage: node scripts/aria-ledger-append.mjs --event <event.json>',
+    '',
+    'Applies an allowlisted, idempotent ledger event to the Universal Connector promotion ledger.',
+    'The event may write a JSON artifact, append readiness text, insert ledger text before the standing',
+    'anti-drift contract, and append one evidence-manifest entry.',
+  ].join('\n');
+}
+
+function readJson(pathname) {
+  return JSON.parse(readFileSync(pathname, 'utf8'));
+}
+
+function resolveEventPath(pathname) {
+  const fromCwd = resolve(process.cwd(), pathname);
+  if (existsSync(fromCwd)) return fromCwd;
+  const fromRepo = resolve(repoRoot, pathname);
+  if (existsSync(fromRepo)) return fromRepo;
+  return fromCwd;
+}
+
+function writeAtomic(pathname, text) {
+  mkdirSync(dirname(pathname), { recursive: true });
+  const tmp = `${pathname}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, text);
+  renameSync(tmp, pathname);
+}
+
+function writeJsonAtomic(pathname, value) {
+  writeAtomic(pathname, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function sha256(text) {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+function safePath(root, relativePath) {
+  if (!relativePath || typeof relativePath !== 'string') {
+    throw new Error('relative path is required');
+  }
+  if (relativePath.startsWith('/') || relativePath.includes('\0')) {
+    throw new Error(`absolute or null-containing path rejected: ${relativePath}`);
+  }
+  const resolved = resolve(root, relativePath);
+  const rel = relative(root, resolved);
+  if (rel.startsWith('..') || rel === '..' || rel.includes('/../')) {
+    throw new Error(`path traversal rejected: ${relativePath}`);
+  }
+  return resolved;
+}
+
+function assertNoSecrets(label, value) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  for (const pattern of SECRET_PATTERNS) {
+    if (pattern.test(text)) {
+      throw new Error(`${label} appears to contain secret-like material`);
+    }
+  }
+}
+
+function validateSection(name, section) {
+  if (section === undefined) return;
+  if (typeof section !== 'string' || !section.startsWith('## ')) {
+    throw new Error(`${name} section must be markdown beginning with a level-two heading`);
+  }
+  assertNoSecrets(name, section);
+}
+
+function validateEvent(event) {
+  if (!event || typeof event !== 'object') throw new Error('event must be an object');
+  if (event.schema !== 'aria.ledger.append_event.v1') throw new Error('unsupported event schema');
+  if (!/^[a-z0-9][a-z0-9._-]{5,120}$/.test(event.id || '')) {
+    throw new Error('event id must be a stable lowercase id');
+  }
+  if (!Number.isInteger(event.phase) || event.phase < 1) throw new Error('event phase must be a positive integer');
+  if (typeof event.title !== 'string' || !event.title.trim()) throw new Error('event title is required');
+  if (!VALID_STATUSES.has(event.status)) throw new Error(`invalid event status: ${String(event.status)}`);
+  if (typeof event.productionMutationPerformed !== 'boolean') {
+    throw new Error('productionMutationPerformed must be boolean');
+  }
+  if (!Array.isArray(event.skillsApplied) || event.skillsApplied.length < 15) {
+    throw new Error('event must record at least 15 applied skills');
+  }
+
+  validateSection('readiness', event.sections?.readiness);
+  validateSection('ledger', event.sections?.ledger);
+  assertNoSecrets('event', event);
+
+  if (event.artifact) {
+    if (typeof event.artifact.relativePath !== 'string') throw new Error('artifact.relativePath is required');
+    safePath('/__aria_ledger_root__', event.artifact.relativePath);
+    if (!event.artifact.relativePath.endsWith('.json')) throw new Error('artifact must be a JSON file');
+    if (!event.artifact.content || typeof event.artifact.content !== 'object') {
+      throw new Error('artifact.content must be an object');
+    }
+  }
+
+  if (event.manifestEntry) {
+    if (typeof event.manifestEntry.gateName !== 'string' || !event.manifestEntry.gateName.trim()) {
+      throw new Error('manifestEntry.gateName is required');
+    }
+    if (!Array.isArray(event.manifestEntry.artifactPaths)) {
+      throw new Error('manifestEntry.artifactPaths must be an array');
+    }
+    if (
+      event.manifestEntry.closesGateNames !== undefined &&
+      (!Array.isArray(event.manifestEntry.closesGateNames) ||
+        event.manifestEntry.closesGateNames.some((name) => typeof name !== 'string' || !name.trim()))
+    ) {
+      throw new Error('manifestEntry.closesGateNames must be a non-empty string array when present');
+    }
+  }
+}
+
+function appendSectionOnce(filePath, section, changed, skipped) {
+  if (!section) return;
+  const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
+  const heading = section.split('\n')[0].trim();
+  if (existing.includes(heading)) {
+    skipped.push({ file: filePath, reason: 'section_already_present', heading });
+    return;
+  }
+  writeAtomic(filePath, `${existing.replace(/\s*$/, '')}\n\n${section.trim()}\n`);
+  changed.push({ file: filePath, action: 'section_appended', heading });
+}
+
+function insertLedgerSectionOnce(filePath, section, changed, skipped) {
+  if (!section) return;
+  const existing = readFileSync(filePath, 'utf8');
+  const heading = section.split('\n')[0].trim();
+  if (existing.includes(heading)) {
+    skipped.push({ file: filePath, reason: 'section_already_present', heading });
+    return;
+  }
+  if (!existing.includes(LEDGER_MARKER)) {
+    throw new Error('standing anti-drift contract marker missing from ledger');
+  }
+  writeAtomic(filePath, existing.replace(LEDGER_MARKER, `\n${section.trim()}\n${LEDGER_MARKER}`));
+  changed.push({ file: filePath, action: 'section_inserted_before_standing_contract', heading });
+}
+
+function writeArtifactOnce(corpusRoot, artifact, changed, skipped) {
+  if (!artifact) return null;
+  const artifactPath = safePath(corpusRoot, artifact.relativePath);
+  const text = `${JSON.stringify(artifact.content, null, 2)}\n`;
+  if (existsSync(artifactPath)) {
+    const existing = readFileSync(artifactPath, 'utf8');
+    if (existing === text) {
+      skipped.push({ file: artifactPath, reason: 'artifact_already_current' });
+      return { path: artifactPath, sha256: sha256(text) };
+    }
+  }
+  writeAtomic(artifactPath, text);
+  changed.push({ file: artifactPath, action: 'artifact_written' });
+  return { path: artifactPath, sha256: sha256(text) };
+}
+
+function appendManifestEntryOnce(filePath, entry, changed, skipped) {
+  if (!entry) return;
+  const manifest = readJson(filePath);
+  if (!Array.isArray(manifest.entries)) throw new Error('manifest.entries must be an array');
+  const normalizedEntry = normalizeManifestEntry(entry);
+  if (manifest.entries.some((candidate) => candidate?.gateName === normalizedEntry.gateName)) {
+    skipped.push({ file: filePath, reason: 'manifest_entry_already_present', gateName: entry.gateName });
+    return;
+  }
+  const closesGateNames = new Set(normalizedEntry.closesGateNames || []);
+  if (closesGateNames.size > 0 && normalizedEntry.exitCode !== 0) {
+    throw new Error('manifestEntry.closesGateNames requires a passing manifest entry');
+  }
+  let closedCount = 0;
+  for (const candidate of manifest.entries) {
+    if (closesGateNames.has(candidate?.gateName) && candidate.exitCode !== 0 && !candidate.closedByGateName) {
+      candidate.closedByGateName = normalizedEntry.gateName;
+      candidate.closedAt = normalizedEntry.capturedAt;
+      candidate.closureStatus = 'closed_by_later_passing_evidence';
+      closedCount += 1;
+    }
+  }
+  manifest.entries.push(normalizedEntry);
+  writeJsonAtomic(filePath, manifest);
+  changed.push({ file: filePath, action: 'manifest_entry_appended', gateName: normalizedEntry.gateName, closedCount });
+}
+
+function normalizeCapturedAt(entry) {
+  if (typeof entry.capturedAt === 'string' && entry.capturedAt.length > 0) {
+    return entry.capturedAt;
+  }
+  if (typeof entry.capturedDate === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(entry.capturedDate)) {
+    return `${entry.capturedDate}T00:00:00.000Z`;
+  }
+  return new Date().toISOString();
+}
+
+function normalizeExitCode(entry) {
+  if (typeof entry.exitCode === 'number' && Number.isFinite(entry.exitCode)) {
+    return entry.exitCode;
+  }
+  return 1;
+}
+
+function normalizeManifestEntry(entry) {
+  const stdoutSource = typeof entry.stdout === 'string' ? entry.stdout : String(entry.stdoutSummary ?? '');
+  const stderrSource = typeof entry.stderr === 'string' ? entry.stderr : String(entry.stderrSummary ?? '');
+  const normalized = {
+    ...entry,
+    capturedAt: normalizeCapturedAt(entry),
+    exitCode: normalizeExitCode(entry),
+    stdoutSummary: String(entry.stdoutSummary ?? ''),
+    stderrSummary: String(entry.stderrSummary ?? ''),
+    stdoutSha256: typeof entry.stdoutSha256 === 'string' ? entry.stdoutSha256 : sha256(stdoutSource),
+    stderrSha256: typeof entry.stderrSha256 === 'string' ? entry.stderrSha256 : sha256(stderrSource),
+    artifactPaths: Array.isArray(entry.artifactPaths) ? entry.artifactPaths : [],
+  };
+  if (typeof entry.stdoutSha256 !== 'string') {
+    normalized.stdoutSha256Source = typeof entry.stdout === 'string' ? 'stdout' : 'stdoutSummary';
+  }
+  if (typeof entry.stderrSha256 !== 'string') {
+    normalized.stderrSha256Source = typeof entry.stderr === 'string' ? 'stderr' : 'stderrSummary';
+  }
+  return normalized;
+}
+
+function writePendingEvent(corpusRoot, event, error) {
+  const pendingDir = resolve(corpusRoot, '.pending-ledger-events');
+  mkdirSync(pendingDir, { recursive: true });
+  const pendingPath = resolve(pendingDir, `${event.id}.json`);
+  const payload = {
+    schema: 'aria.ledger.pending_event.v1',
+    reason: error instanceof Error ? error.message : String(error),
+    capturedAt: new Date().toISOString(),
+    event,
+  };
+  writeJsonAtomic(pendingPath, payload);
+  return pendingPath;
+}
+
+export function applyLedgerEvent(event, options = {}) {
+  validateEvent(event);
+  const corpusRoot = resolve(options.corpusRoot || defaultCorpusRoot);
+  const readinessPath = safePath(corpusRoot, READINESS_FILE);
+  const ledgerPath = safePath(corpusRoot, LEDGER_FILE);
+  const manifestPath = safePath(corpusRoot, MANIFEST_FILE);
+  const changed = [];
+  const skipped = [];
+  let artifactResult = null;
+
+  try {
+    artifactResult = writeArtifactOnce(corpusRoot, event.artifact, changed, skipped);
+    appendSectionOnce(readinessPath, event.sections?.readiness, changed, skipped);
+    insertLedgerSectionOnce(ledgerPath, event.sections?.ledger, changed, skipped);
+    appendManifestEntryOnce(manifestPath, event.manifestEntry, changed, skipped);
+  } catch (error) {
+    const pendingPath = writePendingEvent(corpusRoot, event, error);
+    return {
+      ok: false,
+      pending: true,
+      pendingPath,
+      error: error instanceof Error ? error.message : String(error),
+      changed,
+      skipped,
+      artifact: artifactResult,
+    };
+  }
+
+  return {
+    ok: true,
+    pending: false,
+    changed,
+    skipped,
+    artifact: artifactResult,
+  };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (!args.eventPath) throw new Error('--event is required');
+    const event = readJson(resolveEventPath(args.eventPath));
+    const result = applyLedgerEvent(event);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.ok ? 0 : 1);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}