@aria_asi/cli 0.2.25 → 0.2.29

package/dist/sdk/index.js

@@ -1,5 +1,8 @@
 import { readFile } from 'node:fs/promises';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir as _homedir } from 'node:os';
 import { resolve, isAbsolute } from 'node:path';
+import { randomUUID } from 'node:crypto';
 // ── 8-Lens Cognition Block ─────────────────────────────────────────────────
 const EIGHT_LENS_BLOCK = `[ARIA SHELL PROTOCOL — You are a controlled surface]
 
@@ -45,6 +48,197 @@ export class HTTPHarnessClient {
         this.apiKey = config.apiKey;
         this.harnessPacketUrl = config.harnessPacketUrl ?? `${this.baseUrl}/api/harness/codex`;
         this.workspaceRoot = config.workspaceRoot ?? process.cwd();
+        // Layer 3 — sub-agent disk-cache bootstrap (#84).
+        // If ARIA_HARNESS_PACKET_PATH is set (injected by aria-agent-handoff.mjs
+        // or spawnSubAgent), OR the owner-tier handoff JSON at
+        // ~/.claude/aria-agent-harness-handoff.json carries a harnessPacketPath
+        // field, pre-load the packet from disk so getHarnessPacket() returns
+        // the parent's cognition substrate without an extra HTTP call.
+        // TTL is 5 min (matches handoff TTL). Stale packets trigger normal fetch.
+        this._tryLoadDiskPacket();
+    }
+    extractHarnessText(packet) {
+        const raw = packet?.harness;
+        return typeof raw === 'string' ? raw.trim() : '';
+    }
+    normalizePlanDocs(plan) {
+        const docs = [];
+        if (plan.response !== null && plan.response !== undefined) {
+            if (!plan.response.ok) {
+                for (const d of plan.docs) {
+                    docs.push({ ...d });
+                }
+            }
+            else {
+                for (const d of plan.response.docs) {
+                    if (!d.title && !d.content && !d.path)
+                        continue;
+                    docs.push({ ...d });
+                }
+                const respTitles = new Set(plan.response.docs.map((d) => d.title).filter(Boolean));
+                for (const d of plan.docs) {
+                    if (d.title && !respTitles.has(d.title)) {
+                        docs.push({ ...d });
+                    }
+                }
+            }
+            return docs;
+        }
+        for (const d of plan.docs) {
+            if (!d.title && !d.content && !d.path)
+                continue;
+            docs.push({ ...d });
+        }
+        return docs;
+    }
+    collectPlanFilePaths(plan, docs) {
+        const filePathsToLoad = new Set();
+        if (plan.response !== null && plan.response !== undefined && plan.response.ok) {
+            for (const f of plan.response.files) {
+                filePathsToLoad.add(f);
+            }
+        }
+        for (const f of plan.files) {
+            filePathsToLoad.add(f);
+        }
+        for (const doc of docs) {
+            if (doc.path) {
+                filePathsToLoad.add(doc.path);
+            }
+            if (doc.references) {
+                for (const ref of doc.references) {
+                    filePathsToLoad.add(ref);
+                }
+            }
+            if (doc.content) {
+                const pathMatches = doc.content.match(/`([^`]+\.[a-z]{1,6})`/g);
+                if (pathMatches) {
+                    for (const match of pathMatches) {
+                        const path = match.slice(1, -1);
+                        if (path.includes('/') || path.includes('.')) {
+                            filePathsToLoad.add(path);
+                        }
+                    }
+                }
+            }
+        }
+        return filePathsToLoad;
+    }
+    async loadFilesByPath(filePaths) {
+        const files = {};
+        const loadPromises = Array.from(filePaths).map(async (filePath) => {
+            const resolved = isAbsolute(filePath) ? filePath : resolve(this.workspaceRoot, filePath);
+            try {
+                const content = await readFile(resolved, 'utf8');
+                return { path: filePath, content };
+            }
+            catch {
+                return { path: filePath, content: `[unable to load: ${filePath}]` };
+            }
+        });
+        const loadedFiles = await Promise.all(loadPromises);
+        for (const { path, content } of loadedFiles) {
+            files[path] = content;
+        }
+        return files;
+    }
+    async buildHarnessInjection(harness, plan, options) {
+        const docs = this.normalizePlanDocs(plan);
+        const files = await this.loadFilesByPath(this.collectPlanFilePaths(plan, docs));
+        const shouldLoadAegis = options?.includeAegisLearnings !== false;
+        const aegisLearnings = shouldLoadAegis ? await this.getAegisLearnings(20).catch(() => null) : null;
+        return {
+            harness,
+            docs,
+            files,
+            task: plan.task ?? plan.response?.task ?? '',
+            loadedAt: new Date().toISOString(),
+            aegisLearnings: aegisLearnings ?? undefined,
+        };
+    }
+    buildHarnessBindingBody(context) {
+        const body = {
+            message: context.message?.trim()
+                || context.currentIssue?.trim()
+                || [context.intendedAction, context.rationale].filter(Boolean).join('. ').trim()
+                || 'harness packet preflight',
+            stage: context.stage,
+            actor: context.role,
+            system: context.role,
+            platform: context.platform || 'harness-http-client',
+            roleProfile: context.roleProfile,
+            sessionId: context.sessionId,
+            userId: context.userId,
+            userName: context.userName,
+            currentIssue: context.currentIssue,
+            linearIssueId: context.linearIssueId,
+            linearIssueUrl: context.linearIssueUrl,
+            linearState: context.linearState,
+            workingDirectory: context.workingDirectory,
+            filesTouched: context.filesTouched,
+            recentProgress: context.recentProgress,
+            openRisks: context.openRisks,
+            nextActions: context.nextActions,
+            checkpoint: context.checkpoint,
+            requireGarden: context.requireGarden ?? true,
+            researchMode: context.researchMode,
+            intendedAction: context.intendedAction,
+            rationale: context.rationale,
+            correlationId: context.correlationId || randomUUID(),
+            ...context.extraBody,
+        };
+        return Object.fromEntries(Object.entries(body).filter(([, value]) => {
+            if (value == null)
+                return false;
+            if (typeof value === 'string')
+                return value.trim().length > 0;
+            if (Array.isArray(value))
+                return value.length > 0;
+            return true;
+        }));
+    }
+    _tryLoadDiskPacket() {
+        try {
+            // Path 1: direct env var (set by spawnSubAgent / Agent dispatch)
+            let packetPath = process.env.ARIA_HARNESS_PACKET_PATH || null;
+            // Path 2: owner-tier handoff JSON
+            if (!packetPath) {
+                const HOME = _homedir();
+                const handoffPath = `${HOME}/.claude/aria-agent-harness-handoff.json`;
+                if (existsSync(handoffPath)) {
+                    try {
+                        const handoff = JSON.parse(readFileSync(handoffPath, 'utf8'));
+                        const ageMs = handoff.writtenAt
+                            ? Date.now() - new Date(handoff.writtenAt).getTime()
+                            : Infinity;
+                        const ttl = handoff.ttlMs ?? (5 * 60 * 1000);
+                        if (ageMs < ttl && handoff.harnessPacketPath) {
+                            packetPath = handoff.harnessPacketPath;
+                        }
+                    }
+                    catch { /* malformed handoff — skip */ }
+                }
+            }
+            if (!packetPath)
+                return;
+            if (!existsSync(packetPath))
+                return;
+            // Check packet file age against TTL (5 min)
+            const stat = statSync(packetPath);
+            if (Date.now() - stat.mtimeMs > 5 * 60 * 1000)
+                return; // expired
+            const raw = JSON.parse(readFileSync(packetPath, 'utf8'));
+            // Packet on disk may be the raw API response (has .packet wrapper) or
+            // a bare packet object. Normalise to HarnessPacket shape.
+            const packetData = (raw.packet ?? raw);
+            this.cachedPacket = {
+                packet: packetData,
+                timestamp: new Date().toISOString(),
+                version: '1.0.0',
+            };
+            this.packetLastFetched = stat.mtimeMs; // use file mtime as origin time
+        }
+        catch { /* disk errors are non-fatal — normal HTTP fetch will run */ }
     }
     static getInstance(config) {
         if (!HTTPHarnessClient.instance && config) {
@@ -135,96 +329,98 @@ export class HTTPHarnessClient {
     // ── Inject ──────────────────────────────────────────────────────────────
     async inject(plan) {
         const harness = await this.fetchHarnessPacket();
-        const docs = [];
-        if (plan.response !== null && plan.response !== undefined) {
-            if (!plan.response.ok) {
-                for (const d of plan.docs) {
-                    docs.push({ ...d });
-                }
-            }
-            else {
-                for (const d of plan.response.docs) {
-                    if (!d.title && !d.content && !d.path)
-                        continue;
-                    docs.push({ ...d });
-                }
-                const respTitles = new Set(plan.response.docs.map((d) => d.title).filter(Boolean));
-                for (const d of plan.docs) {
-                    if (d.title && !respTitles.has(d.title)) {
-                        docs.push({ ...d });
-                    }
-                }
-            }
-        }
-        else {
-            for (const d of plan.docs) {
-                if (!d.title && !d.content && !d.path)
-                    continue;
-                docs.push({ ...d });
-            }
-        }
-        const files = {};
-        const filePathsToLoad = new Set();
-        if (plan.response !== null && plan.response !== undefined && plan.response.ok) {
-            for (const f of plan.response.files) {
-                filePathsToLoad.add(f);
-            }
-        }
-        for (const f of plan.files) {
-            filePathsToLoad.add(f);
-        }
-        for (const doc of docs) {
-            if (doc.path) {
-                filePathsToLoad.add(doc.path);
-            }
-            if (doc.references) {
-                for (const ref of doc.references) {
-                    filePathsToLoad.add(ref);
-                }
-            }
-            if (doc.content) {
-                const pathMatches = doc.content.match(/`([^`]+\.[a-z]{1,6})`/g);
-                if (pathMatches) {
-                    for (const m of pathMatches) {
-                        const p = m.slice(1, -1);
-                        if (p.includes('/') || p.includes('.')) {
-                            filePathsToLoad.add(p);
-                        }
-                    }
-                }
-            }
-        }
-        const loadPromises = Array.from(filePathsToLoad).map(async (filePath) => {
-            const resolved = isAbsolute(filePath) ? filePath : resolve(this.workspaceRoot, filePath);
-            try {
-                const content = await readFile(resolved, 'utf8');
-                return { path: filePath, content };
-            }
-            catch {
-                return { path: filePath, content: `[unable to load: ${filePath}]` };
-            }
-        });
-        const loadedFiles = await Promise.all(loadPromises);
-        for (const { path, content } of loadedFiles) {
-            files[path] = content;
-        }
-        return {
-            harness,
-            docs,
-            files,
-            task: plan.task ?? plan.response?.task ?? '',
-            loadedAt: new Date().toISOString(),
-        };
+        return this.buildHarnessInjection(harness, plan, { includeAegisLearnings: true });
     }
     async getHarnessPacket(bodyOverride) {
         return this.fetchHarnessPacket(bodyOverride);
     }
+    async getBoundHarnessAndPrompt(context, plan) {
+        const bindingBody = this.buildHarnessBindingBody(context);
+        const harness = await this.fetchHarnessPacket(bindingBody);
+        const injection = await this.buildHarnessInjection(harness, {
+            response: plan?.response ?? null,
+            docs: plan?.docs ?? [],
+            files: plan?.files ?? [],
+            task: plan?.task ?? context.intendedAction,
+        }, { includeAegisLearnings: context.includeAegisLearnings !== false });
+        return {
+            prompt: this.buildSystemPrompt(injection),
+            packet: harness,
+            harnessText: this.extractHarnessText(harness.packet),
+            bindingBody,
+        };
+    }
+    async getAegisLearnings(limit) {
+        try {
+            const params = new URLSearchParams();
+            if (limit)
+                params.set('limit', String(Math.min(limit, 50)));
+            const url = `${this.baseUrl}/api/harness/aegis-learnings${params.toString() ? '?' + params.toString() : ''}`;
+            const res = await this.fetchWithRetry(url, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (!res.ok)
+                return null;
+            const data = await res.json();
+            return {
+                avoidPatterns: data.avoidPatterns || [],
+                successPatterns: data.successPatterns || [],
+                recentPatterns: (data.recentPatterns || []).map((p) => ({
+                    name: p.name || '',
+                    category: p.category || '',
+                    outcome: p.outcome || '',
+                    lesson: p.lesson || '',
+                })),
+                decisionCount: data.decisionCount || 0,
+                reflectionCount: data.reflectionCount || 0,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
     // ── System prompt builder ───────────────────────────────────────────────
     buildSystemPrompt(injection) {
         const parts = [];
         // 8-lens cognition FIRST — controls all thinking
         parts.push(this.get8LensBlock());
         parts.push('');
+        // Aegis cognitive guardrails — quality substrate from backfill learnings
+        if (injection.aegisLearnings) {
+            const al = injection.aegisLearnings;
+            parts.push('## Aegis Cognitive Guardrails');
+            parts.push(`Backed by ${al.decisionCount.toLocaleString()} decisions, ${al.reflectionCount.toLocaleString()} reflections.`);
+            parts.push('');
+            if (al.avoidPatterns.length > 0) {
+                parts.push('### Patterns to Avoid (learned from past failures)');
+                parts.push('These are anti-patterns that led to hallucinations, errors, or rejected outputs. Reason about them through the 8 lenses and avoid producing output that matches them.');
+                for (const p of al.avoidPatterns.slice(0, 15)) {
+                    parts.push(`- ${p}`);
+                }
+                parts.push('');
+            }
+            if (al.successPatterns.length > 0) {
+                parts.push('### Patterns to Repeat (learned from successful outputs)');
+                parts.push('These patterns consistently produced high-quality output. When appropriate, structure your response using these approaches.');
+                for (const p of al.successPatterns.slice(0, 10)) {
+                    parts.push(`- ${p}`);
+                }
+                parts.push('');
+            }
+            if (al.recentPatterns.length > 0) {
+                parts.push('### Recent Learnings');
+                for (const p of al.recentPatterns.slice(0, 8)) {
+                    parts.push(`- [${p.outcome}] ${p.name}: ${p.lesson.slice(0, 200)}`);
+                }
+                parts.push('');
+            }
+            parts.push('Apply these guardrails through 8-lens cognition — do not list them, internalize them.');
+            parts.push('');
+        }
         parts.push('---');
         parts.push('name: aria-harness-injection');
         parts.push('description: Combined harness state + plan docs + loaded files');
@@ -233,11 +429,20 @@ export class HTTPHarnessClient {
         parts.push('');
         const p = injection.harness.packet;
         if (p && typeof p === 'object') {
-            parts.push('## Aria Live State');
-            parts.push('```json');
-            parts.push(JSON.stringify(p, null, 2));
-            parts.push('```');
-            parts.push('');
+            const rawHarnessText = this.extractHarnessText(p);
+            if (rawHarnessText) {
+                parts.push('## Aria Harness Substrate');
+                parts.push(rawHarnessText);
+                parts.push('');
+            }
+            const metadata = Object.fromEntries(Object.entries(p).filter(([key]) => key !== 'harness' && key !== 'chunks'));
+            if (!rawHarnessText || Object.keys(metadata).length > 0) {
+                parts.push('## Aria Live State');
+                parts.push('```json');
+                parts.push(JSON.stringify(rawHarnessText ? metadata : p, null, 2));
+                parts.push('```');
+                parts.push('');
+            }
         }
         if (injection.task) {
             parts.push('## Task');
@@ -523,6 +728,59 @@ export class HTTPHarnessClient {
             }
         }
         catch { /* non-fatal — ownerTier defaults above apply */ }
+        // ── Layer 3: fetch harness packet for sub-agent cognition bootstrap ──────
+        // Fetch the harness packet now (before writing the handoff) so the path
+        // can be embedded in the handoff JSON. Sub-agents read ARIA_HARNESS_PACKET_PATH
+        // from the environment (set by the caller after spawnSubAgent returns) OR
+        // from the handoff JSON field. Either path eliminates the extra HTTP call
+        // inside the sub-agent.
+        //
+        // Packet paths (tier-aware):
+        //   Owner: ~/.claude/aria-agent-harness-packet.json
+        //   Client: /var/lib/aria-licensee/{jti}/aria-agent-harness-packet.json
+        //
+        // Fail-soft: packet fetch failure logs a warning but does NOT block spawn.
+        const packetPath = isClientTier
+            ? `/var/lib/aria-licensee/${args.jti}/aria-agent-harness-packet.json`
+            : `${HOME}/.claude/aria-agent-harness-packet.json`;
+        let resolvedPacketPath;
+        try {
+            const packetResp = await fetch(this.harnessPacketUrl, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    stage: 'agent-spawn',
+                    actor: 'harness-http-client',
+                    system: 'claude-coding-agent',
+                    surface: 'platform:harness-http-client',
+                    isHamza: ownerTier.hamza,
+                    sessionId: args.sessionId,
+                    mode: 'subagent',
+                }),
+            });
+            if (packetResp.ok) {
+                const packetData = await packetResp.json();
+                fsMkdir(fsDirname(packetPath), { recursive: true });
+                fsWrite(packetPath, JSON.stringify(packetData, null, 2));
+                resolvedPacketPath = packetPath;
+                // Also pre-load into this SDK instance's cache so subsequent
+                // getHarnessPacket() calls are instant within this process.
+                const packetPayload = (packetData.packet ?? packetData);
+                this.cachedPacket = {
+                    packet: packetPayload,
+                    timestamp: new Date().toISOString(),
+                    version: '1.0.0',
+                };
+                this.packetLastFetched = Date.now();
+            }
+        }
+        catch (_packetErr) {
+            // Fail-soft: warn, proceed identity-only (handoff still valid without packet).
+            // Network blips should never block sub-agent spawns.
+        }
         const handoff = {
             writtenAt: new Date().toISOString(),
             parentSessionId: args.sessionId,
@@ -533,6 +791,9 @@ export class HTTPHarnessClient {
             ownerTier,
             parentLedgerPath: ledgerPath,
             ttlMs: HANDOFF_TTL_MS,
+            // harnessPacketPath is set only if packet fetch succeeded. Sub-agents
+            // should also check ARIA_HARNESS_PACKET_PATH env (set by caller post-spawn).
+            ...(resolvedPacketPath ? { harnessPacketPath: resolvedPacketPath } : {}),
         };
         fsMkdir(fsDirname(handoffPath), { recursive: true });
         fsWrite(handoffPath, JSON.stringify(handoff, null, 2));
@@ -544,12 +805,36 @@ export class HTTPHarnessClient {
             allowedActions: args.allowedActions ?? [],
             defectContext: args.defectContext ?? null,
             handoffPath,
+            harnessPacketPath: resolvedPacketPath ?? null,
         });
         fsMkdir(fsDirname(ledgerPath), { recursive: true });
         const { appendFileSync: fsAppend } = await import('node:fs');
         fsAppend(ledgerPath, spawnEntry + '\n');
         return handoff;
     }
+    /**
+     * Returns the environment variables to set for a spawned sub-agent process
+     * so it inherits the parent's harness packet without an extra HTTP call.
+     * Call after spawnSubAgent() — uses the returned handoff.harnessPacketPath.
+     *
+     * Usage:
+     *   const handoff = await sdk.spawnSubAgent(args);
+     *   const env = sdk.subAgentEnv(handoff);
+     *   // pass env to your process spawn / Agent tool env block
+     */
+    subAgentEnv(handoff) {
+        const env = {};
+        if (handoff.harnessPacketPath) {
+            env['ARIA_HARNESS_PACKET_PATH'] = handoff.harnessPacketPath;
+        }
+        if (handoff.harnessToken) {
+            env['ARIA_HARNESS_TOKEN'] = handoff.harnessToken;
+        }
+        if (handoff.harnessUrl) {
+            env['ARIA_HARNESS_URL'] = handoff.harnessUrl;
+        }
+        return env;
+    }
     /** Pulls sub-agent ledger entries newer than the handoff timestamp and appends
      * them to the parent ledger, deduplicating by `text` prefix (first 100 chars). */
     async mergeSubAgentLedger(parentSessionId, _subAgentSessionId, jti) {
@@ -655,6 +940,78 @@ export class HTTPHarnessClient {
         }
         return { merged, skipped };
     }
+    // ── recordDiscovery ──────────────────────────────────────────────────────
+    // Writes a finding row to the sub-agent's session ledger on disk so
+    // aria-agent-ledger-merge.mjs picks it up after the Agent tool completes.
+    //
+    // Tier routing (mirrors aria-discovery-record.mjs):
+    //   Owner tier (no jti) → ~/.claude/aria-discoveries-{session}.jsonl
+    //   Client tier (jti set) → /var/lib/aria-licensee/{jti}/aria-discoveries-{session}.jsonl
+    //
+    // Session ID must be the sub-agent's OWN session (not the parent's) so the
+    // ledger-merge loop finds a file that is NOT the parentLedgerPath. If no
+    // sessionId is supplied we derive one from the handoff parentSessionId + "-sub".
+    //
+    // Fail-soft: returns {ok:false, error} on write failures — never throws.
+    async recordDiscovery(args) {
+        if (!args.text || args.text.length < 4) {
+            return { ok: false, ledger: '', at: '', error: 'text too short (min 4 chars)' };
+        }
+        const { existsSync: fsExists, readFileSync: fsRead, appendFileSync: fsAppend, mkdirSync: fsMkdir } = await import('node:fs');
+        const { homedir } = await import('node:os');
+        const { dirname: fsDirname } = await import('node:path');
+        const HOME = homedir();
+        const LICENSE_PATH = `${HOME}/.aria/license.json`;
+        const HANDOFF_PATH = `${HOME}/.claude/aria-agent-harness-handoff.json`;
+        // Tier detection: caller-supplied jti wins; fall back to license file
+        let jti = args.jti ?? null;
+        let isClientTier = Boolean(jti);
+        if (!jti) {
+            try {
+                if (fsExists(LICENSE_PATH)) {
+                    const lic = JSON.parse(fsRead(LICENSE_PATH, 'utf8'));
+                    jti = lic.jti ?? null;
+                    isClientTier = Boolean(jti);
+                }
+            }
+            catch { /* non-fatal — owner tier */ }
+        }
+        // Session ID: caller-supplied wins; then handoff-derived (with "-sub" suffix)
+        let sessionId = args.sessionId ?? null;
+        if (!sessionId) {
+            try {
+                if (fsExists(HANDOFF_PATH)) {
+                    const handoff = JSON.parse(fsRead(HANDOFF_PATH, 'utf8'));
+                    sessionId = handoff.parentSessionId ? `${handoff.parentSessionId}-sub` : 'sub-unknown';
+                }
+            }
+            catch { /* non-fatal */ }
+        }
+        sessionId = sessionId || 'sub-unknown';
+        const safeSession = String(sessionId).replace(/[^a-zA-Z0-9_-]/g, '_');
+        const ledgerPath = isClientTier
+            ? `/var/lib/aria-licensee/${jti}/aria-discoveries-${safeSession}.jsonl`
+            : `${HOME}/.claude/aria-discoveries-${safeSession}.jsonl`;
+        const at = new Date().toISOString();
+        const row = {
+            at,
+            session: sessionId,
+            kind: args.kind || 'observation',
+            text: args.text,
+            refs: args.refs || [],
+            evidence: args.evidence ?? null,
+            source: args.source || 'sub-agent-sdk',
+            resolution_status: args.resolution_status || 'open',
+        };
+        try {
+            fsMkdir(fsDirname(ledgerPath), { recursive: true });
+            fsAppend(ledgerPath, JSON.stringify(row) + '\n');
+            return { ok: true, ledger: ledgerPath, at };
+        }
+        catch (err) {
+            return { ok: false, ledger: ledgerPath, at, error: err.message };
+        }
+    }
     // ── verifyClaim ──────────────────────────────────────────────────────────
     // POST /api/harness/verify-claim — persists a claim/evidence pair to
     // aria_cognition_corpus and returns a verdict. Fail-soft: if the server-side
@@ -694,6 +1051,376 @@ export class HTTPHarnessClient {
             };
         }
     }
+    // ── postJson — generic SDK-routed JSON POST ────────────────────────────
+    // Hamza 2026-04-27 directive: "use the SDK - use it, enforce it all". The
+    // typed primitives above (consult, validateOutput, gardenTurn) cover Aria's
+    // own control-plane endpoints. This method is the canonical primitive for
+    // bridge POSTs (e.g., Telegram → /chat) so internal bridges inherit the
+    // SDK's retry-with-backoff (250/500/1000ms) and audit-log discipline
+    // instead of using raw fetch().
+    //
+    // Returns:
+    //   - { ok: true, status, data } on 2xx
+    //   - { ok: false, status, errorBody } on non-2xx (does NOT throw — caller
+    //     decides whether to fall back, retry semantically, or surface to user)
+    //   - throws on network errors after retries exhausted (real fetch failures)
+    //
+    // Headers are merged with Authorization (if apiKey is set) and
+    // Content-Type: application/json. Caller can override either.
+    async postJson(url, body, extraHeaders = {}) {
+        const headers = {
+            'Content-Type': 'application/json',
+            ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+            ...extraHeaders,
+        };
+        const res = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const errorBody = await res.text().catch(() => '');
+            return { ok: false, status: res.status, errorBody };
+        }
+        const data = (await res.json());
+        return { ok: true, status: res.status, data };
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    //  ARISTOTLE 3-PHASE COGNITIVE PRIMITIVES
+    //  Dispatches to POST /api/harness/aristotle-noor with a `phase` field.
+    //  The harness route delegates to runAristotleNoorPipeline in aria-soul.
+    //
+    //  Transport contract (per doctrine):
+    //  - NO deadline-based timeouts — fetchWithRetry uses 3 error-count retries
+    //    with 250ms / 500ms / 1000ms backoff. Real network faults (ECONNREFUSED,
+    //    EHOSTUNREACH) reject immediately; slow-but-alive endpoints get a chance.
+    //  - LOUD failure — non-2xx responses throw, never fail-open silently.
+    //    Callers decide whether to surface or recover (per feedback_non_blocking_errors_unacceptable.md).
+    //  - Tier-gating — owner-tier callers set `aristotleEnabled: true` by default;
+    //    client-tier callers receive it as opt-in via the `enabled` config field.
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * ARISTOTLE PRE-PHASE
+     * Fires before an LLM call or tool action. Runs: Fitrah hard-gate,
+     * wisdom pull (principles + decisions), research pull, DeepSoulBridge,
+     * and CleanCognition substrate check.
+     *
+     * Throws on transport-level failures per feedback_non_blocking_errors_unacceptable.md.
+     * If Fitrah vetoes, result.fitrahVetoed === true — caller MUST emit a refusal,
+     * not silently continue.
+     *
+     * @param message   The user message or intent string being processed.
+     * @param sessionId Session ID for telemetry + hive routing.
+     * @param context   Optional context overrides (userId, isHamza, tier, etc.).
+     */
+    async aristotlePre(message, sessionId, context) {
+        const t0 = Date.now();
+        const url = `${this.baseUrl}/api/harness/aristotle-noor`;
+        const res = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                phase: 'pre',
+                message,
+                sessionId,
+                userId: context?.userId,
+                isHamza: context?.isHamza,
+                isGroupChat: context?.isGroupChat,
+                tier: context?.tier,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`[aristotlePre] harness route responded ${res.status} ${res.statusText}: ${body}`);
+        }
+        const data = (await res.json());
+        return {
+            fired: data.fired ?? [],
+            fitrahVetoed: data.fitrahVetoed ?? false,
+            fitrahAlignment: data.fitrahAlignment ?? 1.0,
+            qualityScore: data.qualityScore ?? 100,
+            reAuthorSignal: data.reAuthorSignal ?? false,
+            notes: data.notes ?? [],
+            soulCharge: data.soulCharge ?? null,
+            soulManifoldStatus: data.soulManifoldStatus ?? null,
+            ghazaliVerdict: data.ghazaliVerdict ?? null,
+            latencyMs: data.latencyMs ?? Date.now() - t0,
+            dispatched: true,
+        };
+    }
+    /**
+     * ARISTOTLE MID-PHASE
+     * Fires after context is built but before the LLM call. Runs: MetaCognitive
+     * confidence snapshot and ethical keyword check on the planned approach.
+     *
+     * @param message         Original user message.
+     * @param sessionId       Session ID.
+     * @param plannedApproach The drafted approach / plan string for mid-flight check.
+     * @param context         Optional context overrides.
+     */
+    async aristotleMid(message, sessionId, plannedApproach, context) {
+        const t0 = Date.now();
+        const url = `${this.baseUrl}/api/harness/aristotle-noor`;
+        const res = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                phase: 'mid',
+                message,
+                sessionId,
+                plannedApproach,
+                userId: context?.userId,
+                tier: context?.tier,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`[aristotleMid] harness route responded ${res.status} ${res.statusText}: ${body}`);
+        }
+        const data = (await res.json());
+        return {
+            fired: data.fired ?? [],
+            fitrahVetoed: data.fitrahVetoed ?? false,
+            fitrahAlignment: data.fitrahAlignment ?? 1.0,
+            qualityScore: data.qualityScore ?? 100,
+            reAuthorSignal: data.reAuthorSignal ?? false,
+            notes: data.notes ?? [],
+            soulCharge: data.soulCharge ?? null,
+            soulManifoldStatus: data.soulManifoldStatus ?? null,
+            ghazaliVerdict: data.ghazaliVerdict ?? null,
+            latencyMs: data.latencyMs ?? Date.now() - t0,
+            dispatched: true,
+        };
+    }
+    /**
+     * ARISTOTLE POST-PHASE
+     * Fires after the LLM response, before emission. Runs: 8-Lens Detector,
+     * Predictor, SelfReflection (on high-stakes turns), and quality scoring.
+     *
+     * If result.reAuthorSignal === true, the response has 8-lens violations —
+     * per doctrine the caller MUST surface the signal, never silently strip.
+     *
+     * @param message   Original user message.
+     * @param response  The LLM-generated response to gate.
+     * @param sessionId Session ID.
+     * @param context   Optional context overrides (tier, isFirstOfSession).
+     */
+    async aristotlePost(message, response, sessionId, context) {
+        const t0 = Date.now();
+        const url = `${this.baseUrl}/api/harness/aristotle-noor`;
+        const res = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                phase: 'post',
+                message,
+                draft: response,
+                sessionId,
+                userId: context?.userId,
+                tier: context?.tier,
+                isFirstOfSession: context?.isFirstOfSession,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`[aristotlePost] harness route responded ${res.status} ${res.statusText}: ${body}`);
+        }
+        const data = (await res.json());
+        return {
+            fired: data.fired ?? [],
+            fitrahVetoed: data.fitrahVetoed ?? false,
+            fitrahAlignment: data.fitrahAlignment ?? 1.0,
+            qualityScore: data.qualityScore ?? 100,
+            reAuthorSignal: data.reAuthorSignal ?? false,
+            notes: data.notes ?? [],
+            soulCharge: data.soulCharge ?? null,
+            soulManifoldStatus: data.soulManifoldStatus ?? null,
+            ghazaliVerdict: data.ghazaliVerdict ?? null,
+            latencyMs: data.latencyMs ?? Date.now() - t0,
+            dispatched: true,
+        };
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    //  NOOR COGNITIVE PRIMITIVES
+    //  Dispatches to POST /api/harness/noor with an `operation` discriminator.
+    //  noor-core.ts is NOT modified — these are HTTP wrappers that call its
+    //  exposed surface via the harness route.
+    //
+    //  noor-core.ts banner: "ONLY ARIA CAN CODE ARIA. No councils. No subagents.
+    //  No other LLMs." — complied. We call, never modify.
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * NOOR RECOGNIZE (Kashf — eigenspace recognition, not generation)
+     * Projects the query string (via harness-side embedding) onto Aria's
+     * eigenspace manifold and returns the nearest recognized response + soul
+     * distance + ethical membrane status + Ghazali 8-lens verdict.
+     *
+     * The harness routes the query through the manifold service (gRPC) if
+     * NOOR_EIGENSPACE_SOURCE=manifold, otherwise uses local eigenspace.
+     *
+     * @param query   The input string to recognize on the manifold.
+     * @param context Optional context (sessionId, userId) for telemetry.
+     */
+    async noorRecognize(query, context) {
+        const t0 = Date.now();
+        const url = `${this.baseUrl}/api/harness/noor`;
+        const res = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                operation: 'recognize',
+                query,
+                sessionId: context?.sessionId,
+                userId: context?.userId,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`[noorRecognize] harness route responded ${res.status} ${res.statusText}: ${body}`);
+        }
+        const data = (await res.json());
+        return {
+            nearestText: data.nearestText ?? '',
+            soulDistance: data.soulDistance ?? 0,
+            confidence: data.confidence ?? 0,
+            withinMembrane: data.withinMembrane ?? true,
+            soulCharge: data.soulCharge ?? 0,
+            projectionComponents: data.projectionComponents ?? [],
+            ghazaliVerdict: data.ghazaliVerdict ?? null,
+            manifoldHealth: data.manifoldHealth ?? null,
+            dispatched: true,
+            latencyMs: data.latencyMs ?? Date.now() - t0,
+        };
+    }
+    /**
+     * NOOR FORGE — self-generated tool invocation via 5 primitives
+     * Composes a named primitive chain (http, sql, file_read, file_write, pub_sub)
+     * and executes it through the harness-side NoorForge engine. The harness
+     * applies the ethical membrane check (checkEthicalAlignment) before any
+     * primitive fires — rejected intents return success=false, ethicallyApproved=false.
+     *
+     * @param intent      Description of what the forged tool should accomplish.
+     * @param primitives  Ordered list of primitive descriptors to execute in sequence.
+     * @param context     Optional context for telemetry.
+     */
+    async noorForge(intent, primitives, context) {
+        const t0 = Date.now();
+        const url = `${this.baseUrl}/api/harness/noor`;
+        const res = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                operation: 'forge',
+                intent,
+                primitives,
+                sessionId: context?.sessionId,
+                userId: context?.userId,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`[noorForge] harness route responded ${res.status} ${res.statusText}: ${body}`);
+        }
+        const data = (await res.json());
+        return {
+            success: data.success ?? false,
+            toolName: data.toolName ?? `forged_${Date.now()}`,
+            ethicallyApproved: data.ethicallyApproved ?? false,
+            totalDurationMs: data.totalDurationMs ?? Date.now() - t0,
+            results: data.results ?? [],
+            dispatched: true,
+        };
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    //  HARNESS CONSULT WITH ARISTOTLE — opt-in 3-phase wrapping
+    //
+    //  Wraps getBoundHarnessAndPrompt() with pre + post Aristotle phases.
+    //  Per the harness packet cognition_runtime_rule: "Aristotle/Taddabur are
+    //  primary cognition. Do not replace contemplation with a dashboard state."
+    //  Aristotle fires EVERY consult for owner-tier; client-tier requires
+    //  explicit `aristotleEnabled: true` in options (default: false).
+    //
+    //  Mid-phase is optional — pass `plannedApproach` to activate it between
+    //  packet fetch and the LLM call. Most callers omit mid-phase.
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * Harness consult with Aristotle 3-phase wrapping.
+     *
+     * Flow:
+     *   1. aristotlePre()  — Fitrah gate, wisdom, research, soul state
+     *   2. getBoundHarnessAndPrompt() — packet + system prompt
+     *   3. aristotleMid()  — MetaCognitive + ethical check (if plannedApproach provided)
+     *   4. [caller calls LLM with the returned prompt]
+     *   5. Call aristotlePost() from the caller with the LLM response
+     *      (post-phase is caller-side because the SDK doesn't own the LLM call)
+     *
+     * Returns the BoundHarnessPromptResult augmented with the pre-phase result.
+     * If Fitrah vetoes, throws — the caller must handle the veto (emit refusal).
+     *
+     * @param context          HarnessBindingContext (same shape as getBoundHarnessAndPrompt).
+     * @param plan             Optional plan docs / files (same shape as getBoundHarnessAndPrompt).
+     * @param options          Aristotle control options.
+     * @param options.aristotleEnabled  Whether Aristotle fires. Default true for this method.
+     * @param options.plannedApproach   Optional planned approach string — activates mid-phase.
+     * @param options.tier              Tier hint for Aristotle ('owner'|'client'|etc.).
+     */
+    async getBoundHarnessAndPromptWithAristotle(context, plan, options) {
+        const enabled = options?.aristotleEnabled !== false; // default ON
+        let preResult = null;
+        let midResult = null;
+        const message = context.message ?? context.intendedAction ?? 'harness consult';
+        // ── Phase 1: PRE ────────────────────────────────────────────────────────
+        if (enabled) {
+            try {
+                preResult = await this.aristotlePre(message, context.sessionId, {
+                    userId: context.userId,
+                    tier: options?.tier,
+                });
+                if (preResult.fitrahVetoed) {
+                    throw new Error(`[aristotlePre] Fitrah veto — alignment=${preResult.fitrahAlignment.toFixed(2)}. Caller must emit honest refusal.`);
+                }
+            }
+            catch (err) {
+                // Re-throw Fitrah veto (named Error pattern). Log transport faults.
+                if (err.message.includes('Fitrah veto'))
+                    throw err;
+                console.error('[getBoundHarnessAndPromptWithAristotle] aristotlePre transport fault:', err.message);
+                // Transport faults are LOUD but non-blocking for the consult itself.
+                // The pre-phase result stays null so callers know Aristotle didn't fire.
+            }
+        }
+        // ── Phase 2: Harness packet + system prompt ─────────────────────────────
+        const bound = await this.getBoundHarnessAndPrompt(context, plan);
+        // ── Phase 3: MID (optional — only when plannedApproach is provided) ─────
+        if (enabled && options?.plannedApproach) {
+            try {
+                midResult = await this.aristotleMid(message, context.sessionId, options.plannedApproach, {
+                    userId: context.userId,
+                    tier: options?.tier,
+                });
+            }
+            catch (err) {
+                console.error('[getBoundHarnessAndPromptWithAristotle] aristotleMid transport fault:', err.message);
+                // Non-blocking — mid-phase unavailability doesn't stop the LLM call.
+            }
+        }
+        return { ...bound, aristotlePre: preResult, aristotleMid: midResult };
+    }
     // ── Retry + exponential backoff helper ──────────────────────────────────
     // Hamza 2026-04-27: "YES ADD RETRY AND BACKOFF BUT FUCK UR CIRCUIT BREAKER
     // THAT NUST LEAVES HER BROKEN WE NEED SELF HEAL!!!" — every fetch retries
@@ -724,4 +1451,19 @@ export const harness = {
     getInstance: HTTPHarnessClient.getInstance.bind(HTTPHarnessClient),
     resetInstance: HTTPHarnessClient.resetInstance.bind(HTTPHarnessClient),
 };
+export function bindingContext(role, sessionId, stage, intendedAction, rationale) {
+    return {
+        role,
+        sessionId,
+        stage,
+        intendedAction,
+        rationale,
+        correlationId: randomUUID(),
+    };
+}
+export async function getBoundHarnessAndPrompt(context, plan, client) {
+    const sdk = client ?? HTTPHarnessClient.getInstance();
+    return sdk.getBoundHarnessAndPrompt(context, plan);
+}
+export * from './runWithCognition.js';
 //# sourceMappingURL=index.js.map