@aria_asi/cli 0.2.32 → 0.2.34

package/dist/runtime/codex-bridge.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { delimiter, dirname, resolve } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
+import { evaluateSkillGate, formatSkillGateBlock } from './hooks/lib/skill-autoload-gate.mjs';
 
 const require = createRequire(import.meta.url);
 const { WebSocketServer, WebSocket } = require('ws');
@@ -75,6 +77,24 @@ function sleep(ms) {
   return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
 
+function stableEvidenceString(value) {
+  if (typeof value === 'string') return value;
+  try { return JSON.stringify(value); } catch { return String(value); }
+}
+
+function makeEvidenceRef(kind, value, metadata = {}) {
+  const raw = stableEvidenceString(value);
+  const sha256 = createHash('sha256').update(raw).digest('hex');
+  return {
+    evidenceId: `ev_${sha256.slice(0, 16)}`,
+    kind,
+    at: new Date().toISOString(),
+    sha256,
+    preview: raw.slice(0, 500),
+    metadata,
+  };
+}
+
 function readRuntimeToken() {
   const envToken = process.env.ARIA_HARNESS_TOKEN || process.env.ARIA_API_KEY || process.env.OPENAI_API_KEY || process.env.ARIA_MASTER_TOKEN;
   if (envToken) return envToken;
@@ -123,9 +143,10 @@ function ensureTurnState(threadId, turnId) {
       userText: '',
       preReceiptId: null,
       agentText: '',
-      bufferedAgentNotifications: [],
-      firstAgentItemId: null,
-    };
+        bufferedAgentNotifications: [],
+        firstAgentItemId: null,
+        traceId: `trace_${randomUUID()}`,
+      };
     turnState.set(key, state);
   }
   return state;
@@ -186,6 +207,16 @@ async function validateTurnText(threadId, turnId) {
   if (!text) {
     return { ok: false, reason: 'No assistant text exists for this turn yet. Codex must emit readable cognition before action.' };
   }
+  const skillGate = evaluateSkillGate({
+    sessionId: `codex:${threadId}:${turnId}`,
+    surface: 'codex-bridge-output',
+    text: [state.userText, text].join('\n'),
+    isOutputCloseout: true,
+    autoLoadAvailable: false,
+  });
+  if (!skillGate.ok) {
+    return { ok: false, reason: formatSkillGateBlock(skillGate), result: { skillGate } };
+  }
   const result = await postRuntime('/validate-output', {
     text,
     sessionId: `codex:${threadId}:${turnId}`,
@@ -198,6 +229,7 @@ async function validateTurnText(threadId, turnId) {
       stage: 'codex-turn',
       actor: 'codex-bridge',
       system: 'codex-bridge',
+      traceId: state.traceId,
     },
   });
   const pass = result?.pass === true && result?.validation?.passed !== false;
@@ -210,11 +242,29 @@ async function validateTurnText(threadId, turnId) {
       };
 }
 
-async function checkActionAgainstRuntime(action, target, threadId, turnId) {
+async function checkActionAgainstRuntime(action, target, threadId, turnId, metadata = {}) {
+  const state = ensureTurnState(threadId, turnId);
+  const skillGate = evaluateSkillGate({
+    sessionId: `codex:${threadId}:${turnId}`,
+    surface: 'codex-bridge-action',
+    text: target,
+    action: target,
+    toolName: action,
+    isDeploy: action === 'deploy',
+    isMutation: action === 'write',
+    autoLoadAvailable: false,
+  });
+  if (!skillGate.ok) {
+    return { ok: false, reason: formatSkillGateBlock(skillGate), result: { skillGate } };
+  }
   const result = await postRuntime('/check-action', {
     action,
     target,
     sessionId: `codex:${threadId}:${turnId}`,
+    actor: 'codex',
+    roleProfile: process.env.CODEX_ARIA_ROLE_PROFILE || process.env.ARIA_ROLE_PROFILE || null,
+    verifyText: state.agentText || '',
+    ...metadata,
   });
   if (result?.allowed === false) {
     return {
@@ -244,6 +294,8 @@ async function recordMizanPre(threadId, turnId) {
         surface: 'codex-bridge',
         platform: 'codex',
         userText: state.userText,
+        traceId: state.traceId,
+        evidenceRefs: [makeEvidenceRef('user_input', state.userText, { threadId, turnId, traceId: state.traceId })],
       },
     });
     state.preReceiptId = result?.receipt?.receiptId || null;
@@ -262,6 +314,8 @@ async function recordMizanPost(threadId, turnId, pass, summary) {
       evidence: {
         validated_output: pass,
         bridge: 'codex',
+        trace_id: state.traceId,
+        output_ref: makeEvidenceRef('assistant_output', state.agentText || summary, { threadId, turnId, traceId: state.traceId }),
       },
       context: {
         sessionId: `codex:${threadId}:${turnId}`,
@@ -269,6 +323,7 @@ async function recordMizanPost(threadId, turnId, pass, summary) {
         platform: 'codex',
         userText: state.userText,
         summary,
+        traceId: state.traceId,
       },
     });
   } catch (error) {
@@ -285,6 +340,8 @@ async function recordMizanPost(threadId, turnId, pass, summary) {
       details: {
         threadId,
         turnId,
+        traceId: state.traceId,
+        outputRef: makeEvidenceRef('assistant_output', state.agentText || summary, { threadId, turnId, traceId: state.traceId }),
       },
     });
   } catch (error) {
@@ -336,7 +393,9 @@ async function handleApprovalRequest(upstream, downstream, message) {
       cwd: params.cwd || null,
       commandActions: params.commandActions || params.parsedCmd || null,
     }).slice(0, 1500);
-    const actionCheck = await checkActionAgainstRuntime(action, target, threadId, turnId);
+    const actionCheck = await checkActionAgainstRuntime(action, target, threadId, turnId, {
+      requireVerify: action === 'delete' || action === 'deploy',
+    });
     if (!actionCheck.ok) {
       const reason = `Aria runtime denied ${action}: ${actionCheck.reason}`;
       upstream.send(JSON.stringify(makeGuardianWarning(threadId, reason)));
@@ -360,8 +419,9 @@ async function handleApprovalRequest(upstream, downstream, message) {
   }
 
   if (method === 'item/fileChange/requestApproval' || method === 'applyPatchApproval') {
-    const target = params.grantRoot || params.reason || params.itemId || 'file-change';
-    const actionCheck = await checkActionAgainstRuntime('write', String(target), threadId, turnId);
+    const target = params.grantRoot || params.path || params.filePath || params.reason || params.itemId || 'file-change';
+    const files = [params.path, params.filePath, params.grantRoot].filter((value) => typeof value === 'string' && value.trim());
+    const actionCheck = await checkActionAgainstRuntime('write', String(target), threadId, turnId, { files });
     if (!actionCheck.ok) {
       const reason = `Aria runtime denied file change: ${actionCheck.reason}`;
       upstream.send(JSON.stringify(makeGuardianWarning(threadId, reason)));
@@ -390,7 +450,10 @@ async function handleApprovalRequest(upstream, downstream, message) {
       permissions: params.permissions || null,
       reason: params.reason || null,
     }).slice(0, 1500);
-    const actionCheck = await checkActionAgainstRuntime('write', target, threadId, turnId);
+    const files = Array.isArray(params.permissions?.fileSystem?.entries)
+      ? params.permissions.fileSystem.entries.filter((value) => typeof value === 'string' && value.trim())
+      : [];
+    const actionCheck = await checkActionAgainstRuntime('write', target, threadId, turnId, { files });
     if (!actionCheck.ok) {
       const reason = `Aria runtime denied permissions request: ${actionCheck.reason}`;
       upstream.send(JSON.stringify(makeGuardianWarning(threadId, reason)));

package/dist/runtime/discipline/CLAUDE.md

@@ -18,7 +18,7 @@ If compaction, gate deadlock, or repeated drift happens, restart from that order
 
 ## What this SDK is
 
-`@aria/harness-http-client` is the Aria harness SDK. It binds a process
+`@aria_asi/harness-http-client` is the Aria harness SDK. It binds a process
 (worker, autonomous loop, dispatched artifact) to Aria's three-layer
 enforcement substrate so the process cannot drift from Aria's doctrine,
 axioms, frames, and memory.
@@ -221,7 +221,7 @@ The Stop-gate scans output for these patterns. When matched, the response is rej
 ### 1. Build a harness-bound LLM call
 
 ```ts
-import { getBoundHarnessAndPrompt, bindingContext } from '@aria/harness-http-client';
+import { getBoundHarnessAndPrompt, bindingContext } from '@aria_asi/harness-http-client';
 import { runLayer3Gates } from '@aria/gate-runtime';
 
 const { prompt: harnessContext, packet } = await getBoundHarnessAndPrompt(

package/dist/runtime/discipline/doctrine_trigger_map.json

@@ -508,6 +508,49 @@
       "counter_action": "Create or reuse one turn substrate object containing embedding, perturb snapshot, ProjectAllDomains result, awakenAria Garden block, DeepSoul/Noor/shards/Mizan signals; pass it downstream.",
       "message": "Duplicate projection path detected. Replace with one per-turn cognition packet and shared consumption."
     },
+    {
+      "trigger_id": "premature_task_closeout",
+      "trigger": "(?:done|complete|completed|ready|verified|fixed).{0,120}(?:but|except|caveat|remaining|not yet|still|separate|later|blocked|skipped)",
+      "rx": "(?:done|complete|completed|ready|verified|fixed).{0,120}(?:but|except|caveat|remaining|not yet|still|separate|later|blocked|skipped)",
+      "doctrine": "memory:feedback_no_premature_task_closeout.md",
+      "memory": "feedback_no_premature_task_closeout.md",
+      "severity": "block",
+      "teaching": "A task is not complete while material blockers remain. Completion claims must match the verified scope.",
+      "counter_action": "Do not close the task. Fix the blocker now, or create an owner-visible durable task with the exact failing surface and verification gap.",
+      "message": "Premature closeout detected: completion language coexists with unresolved blockers. Fix or durably track before emitting."
+    },
+    {
+      "trigger_id": "narrow_e2e_overclaim",
+      "trigger": "(?:production-ready|ready for production|works in general|client packages?|npm packages?|SDKs?|runtimes?|harnesses?).{0,220}(?:deal|single flow|one flow|widget|one service|specific path|covered flow)",
+      "rx": "(?:production-ready|ready for production|works in general|client packages?|npm packages?|SDKs?|runtimes?|harnesses?).{0,220}(?:deal|single flow|one flow|widget|one service|specific path|covered flow)",
+      "doctrine": "memory:feedback_narrow_e2e_overclaim.md",
+      "memory": "feedback_narrow_e2e_overclaim.md",
+      "severity": "block",
+      "teaching": "A narrow e2e does not prove general production readiness for SDKs, npm packages, runtimes, clients, or harnesses.",
+      "counter_action": "Run the general readiness matrix or explicitly limit the claim to the verified surface. Do not imply general readiness from one app flow.",
+      "message": "Narrow proof overclaim detected. General readiness requires the client/package/runtime/harness matrix."
+    },
+    {
+      "trigger_id": "advisory_gate_not_gate",
+      "trigger": "(?:non-blocking|warn(?:ing)? only|advisory|falls? through|fail open|soft fail|log(?:ged)? and continue|quality gate warning)",
+      "rx": "(?:non-blocking|warn(?:ing)? only|advisory|falls? through|fail open|soft fail|log(?:ged)? and continue|quality gate warning)",
+      "doctrine": "memory:feedback_advisory_gate_is_not_gate.md",
+      "memory": "feedback_advisory_gate_is_not_gate.md",
+      "severity": "block",
+      "teaching": "A gate that only warns or falls through is not a gate. Enforcement must fail closed where quality or doctrine is required.",
+      "counter_action": "Convert advisory paths to blocking errors, add a self-test that proves rejection, and install the hardened gate into each consumer surface.",
+      "message": "Advisory gate bypass detected. Convert to fail-closed enforcement and prove it with a blocking self-test."
+    },
+    {
+      "trigger_id": "start_new_session_as_gate_fix",
+      "trigger": "(?:start|open|begin).{0,40}(?:new|fresh).{0,30}session.{0,120}(?:fix|gate|harness|enforcement)",
+      "rx": "(?:start|open|begin).{0,40}(?:new|fresh).{0,30}session.{0,120}(?:fix|gate|harness|enforcement)",
+      "doctrine": "memory:feedback_advisory_gate_is_not_gate.md",
+      "memory": "feedback_advisory_gate_is_not_gate.md",
+      "severity": "block",
+      "teaching": "A new session is not an enforcement fix. It only reloads whatever gate contract exists; broken gates remain broken.",
+      "counter_action": "Fix the runtime/plugin/hook contract, reinstall it, and run a live bad-action/bad-output self-test that proves blocking."
+    },
     {
       "trigger_id": "registry_image_drift",
       "trigger": "image.?pull|ErrImageNeverPull|ImagePullBackOff|registry gc|image.*missing|image.*not.*found",

package/dist/runtime/discipline/skills/aria-harness/aria-harness-onboarding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aria-harness-onboarding
-description: Use when starting a new project that imports @aria/harness-http-client OR when an agent first encounters the SDK in a repo. Loads the foundational 3-layer harness model (packet/BIND/gate-runtime), the doctrine reference list, and points to the four sibling skills (aria-harness-deploy, aria-harness-substrate-binding, aria-harness-no-stripping, aria-harness-output-discipline). Read this once per project to inherit the discipline.
+description: Use when starting a new project that imports @aria_asi/harness-http-client OR when an agent first encounters the SDK in a repo. Loads the foundational 3-layer harness model (packet/BIND/gate-runtime), the doctrine reference list, and points to the four sibling skills (aria-harness-deploy, aria-harness-substrate-binding, aria-harness-no-stripping, aria-harness-output-discipline). Read this once per project to inherit the discipline.
 ---
 
 # Aria Harness Onboarding
@@ -9,7 +9,7 @@ You are about to author code that uses the Aria harness SDK. This skill loads th
 
 ## What the SDK is
 
-`@aria/harness-http-client` binds a process (worker, autonomous loop, dispatched artifact) to Aria's three-layer enforcement substrate so the process cannot drift from Aria's doctrine, axioms, frames, and memory.
+`@aria_asi/harness-http-client` binds a process (worker, autonomous loop, dispatched artifact) to Aria's three-layer enforcement substrate so the process cannot drift from Aria's doctrine, axioms, frames, and memory.
 
 ## The three layers — every consumer enforces all three
 
@@ -36,7 +36,7 @@ This onboarding skill is the entry point. Four sibling skills auto-trigger on sp
 ## Build a harness-bound LLM call (the basic pattern)
 
 ```ts
-import { getBoundHarnessAndPrompt, bindingContext } from '@aria/harness-http-client';
+import { getBoundHarnessAndPrompt, bindingContext } from '@aria_asi/harness-http-client';
 import { runLayer3Gates } from '@aria/gate-runtime';
 
 const { prompt: harnessContext, packet } = await getBoundHarnessAndPrompt(

package/dist/runtime/doctrine_trigger_map.json

@@ -508,6 +508,49 @@
       "counter_action": "Create or reuse one turn substrate object containing embedding, perturb snapshot, ProjectAllDomains result, awakenAria Garden block, DeepSoul/Noor/shards/Mizan signals; pass it downstream.",
       "message": "Duplicate projection path detected. Replace with one per-turn cognition packet and shared consumption."
     },
+    {
+      "trigger_id": "premature_task_closeout",
+      "trigger": "(?:done|complete|completed|ready|verified|fixed).{0,120}(?:but|except|caveat|remaining|not yet|still|separate|later|blocked|skipped)",
+      "rx": "(?:done|complete|completed|ready|verified|fixed).{0,120}(?:but|except|caveat|remaining|not yet|still|separate|later|blocked|skipped)",
+      "doctrine": "memory:feedback_no_premature_task_closeout.md",
+      "memory": "feedback_no_premature_task_closeout.md",
+      "severity": "block",
+      "teaching": "A task is not complete while material blockers remain. Completion claims must match the verified scope.",
+      "counter_action": "Do not close the task. Fix the blocker now, or create an owner-visible durable task with the exact failing surface and verification gap.",
+      "message": "Premature closeout detected: completion language coexists with unresolved blockers. Fix or durably track before emitting."
+    },
+    {
+      "trigger_id": "narrow_e2e_overclaim",
+      "trigger": "(?:production-ready|ready for production|works in general|client packages?|npm packages?|SDKs?|runtimes?|harnesses?).{0,220}(?:deal|single flow|one flow|widget|one service|specific path|covered flow)",
+      "rx": "(?:production-ready|ready for production|works in general|client packages?|npm packages?|SDKs?|runtimes?|harnesses?).{0,220}(?:deal|single flow|one flow|widget|one service|specific path|covered flow)",
+      "doctrine": "memory:feedback_narrow_e2e_overclaim.md",
+      "memory": "feedback_narrow_e2e_overclaim.md",
+      "severity": "block",
+      "teaching": "A narrow e2e does not prove general production readiness for SDKs, npm packages, runtimes, clients, or harnesses.",
+      "counter_action": "Run the general readiness matrix or explicitly limit the claim to the verified surface. Do not imply general readiness from one app flow.",
+      "message": "Narrow proof overclaim detected. General readiness requires the client/package/runtime/harness matrix."
+    },
+    {
+      "trigger_id": "advisory_gate_not_gate",
+      "trigger": "(?:non-blocking|warn(?:ing)? only|advisory|falls? through|fail open|soft fail|log(?:ged)? and continue|quality gate warning)",
+      "rx": "(?:non-blocking|warn(?:ing)? only|advisory|falls? through|fail open|soft fail|log(?:ged)? and continue|quality gate warning)",
+      "doctrine": "memory:feedback_advisory_gate_is_not_gate.md",
+      "memory": "feedback_advisory_gate_is_not_gate.md",
+      "severity": "block",
+      "teaching": "A gate that only warns or falls through is not a gate. Enforcement must fail closed where quality or doctrine is required.",
+      "counter_action": "Convert advisory paths to blocking errors, add a self-test that proves rejection, and install the hardened gate into each consumer surface.",
+      "message": "Advisory gate bypass detected. Convert to fail-closed enforcement and prove it with a blocking self-test."
+    },
+    {
+      "trigger_id": "start_new_session_as_gate_fix",
+      "trigger": "(?:start|open|begin).{0,40}(?:new|fresh).{0,30}session.{0,120}(?:fix|gate|harness|enforcement)",
+      "rx": "(?:start|open|begin).{0,40}(?:new|fresh).{0,30}session.{0,120}(?:fix|gate|harness|enforcement)",
+      "doctrine": "memory:feedback_advisory_gate_is_not_gate.md",
+      "memory": "feedback_advisory_gate_is_not_gate.md",
+      "severity": "block",
+      "teaching": "A new session is not an enforcement fix. It only reloads whatever gate contract exists; broken gates remain broken.",
+      "counter_action": "Fix the runtime/plugin/hook contract, reinstall it, and run a live bad-action/bad-output self-test that proves blocking."
+    },
     {
       "trigger_id": "registry_image_drift",
       "trigger": "image.?pull|ErrImageNeverPull|ImagePullBackOff|registry gc|image.*missing|image.*not.*found",

package/dist/runtime/harness-daemon.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { createServer } from 'node:http';
+import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -35,6 +36,7 @@ const LOCAL_FIRST_PRINCIPLE = 'Truth over deception. No harm. Sacred trust. Powe
 
 let cachedPacketEnvelope = loadCachedPacketEnvelope();
 let refreshInFlight = null;
+let refreshInFlightKey = '';
 let lastRefreshError = null;
 let lastRefreshStartedAt = null;
 let lastRefreshCompletedAt = cachedPacketEnvelope?.timestamp || null;
@@ -99,6 +101,46 @@ function sanitizePacketEnvelope(raw) {
   };
 }
 
+function stableIdentityValue(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function requestCacheKey(body = {}, apiKey = '') {
+  const identity = {
+    stage: stableIdentityValue(body.stage || body.packetRequest?.stage),
+    actor: stableIdentityValue(body.actor || body.packetRequest?.actor),
+    system: stableIdentityValue(body.system || body.packetRequest?.system),
+    platform: stableIdentityValue(body.platform || body.packetRequest?.platform),
+    roleProfile: stableIdentityValue(body.roleProfile || body.role_profile || body.packetRequest?.roleProfile || body.packetRequest?.role_profile),
+    token: apiKey ? createHash('sha256').update(apiKey).digest('hex').slice(0, 16) : '',
+  };
+  return createHash('sha256').update(JSON.stringify(identity)).digest('hex');
+}
+
+function extractPacketField(packet, field) {
+  if (!packet || typeof packet !== 'object') return '';
+  const direct = packet[field];
+  if (typeof direct === 'string' && direct.trim()) return stableIdentityValue(direct);
+  for (const source of [packet.adapter, packet.harness]) {
+    if (typeof source !== 'string') continue;
+    const match = source.match(new RegExp(`(?:^|\\n)\\s*${field}\\s*=\\s*([^\\n\\s]+)`, 'i'));
+    if (match?.[1]) return stableIdentityValue(match[1]);
+  }
+  return '';
+}
+
+function cachedPacketMatchesRequest(envelope, body = {}) {
+  const packet = envelope?.packet;
+  if (!packet || typeof packet !== 'object') return false;
+  for (const field of ['stage', 'actor', 'system']) {
+    const expected = stableIdentityValue(body[field] || body.packetRequest?.[field]);
+    if (!expected) continue;
+    const actual = extractPacketField(packet, field);
+    if (actual && actual !== expected) return false;
+  }
+  return true;
+}
+
 function loadCachedPacketEnvelope() {
   const candidates = [LOCAL_PACKET_CACHE_PATH, ...LEGACY_PACKET_CACHE_CANDIDATES];
   for (const candidate of candidates) {
@@ -220,10 +262,15 @@ async function fetchJsonWithRetry(url, init, attempts = 3) {
 }
 
 async function refreshPacket(body = {}, apiKey = '') {
-  if (refreshInFlight) return refreshInFlight;
+  const cacheKey = requestCacheKey(body, apiKey);
+  if (refreshInFlight && refreshInFlightKey === cacheKey) return refreshInFlight;
+  if (refreshInFlight) {
+    await refreshInFlight.catch(() => {});
+  }
   if (isLoopedUpstream(UPSTREAM_HARNESS_URL)) {
     throw new Error(`upstream harness URL loops back to local daemon: ${UPSTREAM_HARNESS_URL}`);
   }
+  refreshInFlightKey = cacheKey;
   lastRefreshStartedAt = new Date().toISOString();
   lastRefreshError = null;
   refreshInFlight = (async () => {
@@ -258,6 +305,7 @@ async function refreshPacket(body = {}, apiKey = '') {
     throw error;
   } finally {
     refreshInFlight = null;
+    refreshInFlightKey = '';
   }
 }
 
@@ -268,7 +316,7 @@ function queuePacketRefresh(body, apiKey) {
 }
 
 async function resolvePacketEnvelope(packetRequest = {}, apiKey = '', message = '') {
-  if (cachedPacketEnvelope) {
+  if (cachedPacketEnvelope && cachedPacketMatchesRequest(cachedPacketEnvelope, packetRequest)) {
     queuePacketRefresh(packetRequest, apiKey);
     return cachedPacketEnvelope;
   }

package/dist/runtime/hooks/aria-agent-handoff.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+// aria-agent-handoff.mjs — PreToolUse hook for the Agent tool.
+// Writes a handoff JSON before a sub-agent spawns so it inherits the
+// parent's owner/client-tier identity + ledger path instead of starting fresh.
+//
+// Owner tier  → ~/.claude/aria-agent-harness-handoff.json
+// Client tier → /var/lib/aria-licensee/{jti}/handoff.json
+//
+// Tier is determined by whether a JTI is present in the license file at
+// ~/.aria/license.json. If JTI is present → client tier. If absent (owner
+// JWT at ~/.aria/owner-token) → owner tier.
+//
+// Tier protection: client handoffs NEVER write to ~/.claude/ and NEVER
+// carry master tokens. Client paths are scoped to /var/lib/aria-licensee/{jti}/.
+// Default-on per Hamza doctrine — no env-flag gate to disable.
+//
+// Doctrine: feedback_aria_does_work.md (sub-agents inherit harness)
+//           feedback_implementation_coupled_cognition.md (handoff is the impl)
+//           feedback_no_flag_without_fix.md (no silent bypasses)
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createRequire } from 'node:module';
+
+const HOME = homedir();
+const LOG = `${HOME}/.claude/aria-pre-tool-gate.log`;
+const PACKET_CACHE = `${HOME}/.claude/.aria-harness-last-packet.json`;
+const LICENSE_PATH = `${HOME}/.aria/license.json`;
+const OWNER_TOKEN_PATH = `${HOME}/.aria/owner-token`;
+const HANDOFF_TTL_MS = 5 * 60 * 1000;
+const SHARED_RUNTIME_URL = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\/+$/, '');
+const SHARED_SDK_ROOT = `${HOME}/.aria/sdk`;
+
+function audit(msg) {
+  try {
+    if (!existsSync(dirname(LOG))) mkdirSync(dirname(LOG), { recursive: true });
+    appendFileSync(LOG, `${new Date().toISOString()} [agent-handoff] ${msg}\n`);
+  } catch {}
+}
+
+let input = '';
+for await (const chunk of process.stdin) input += chunk;
+
+let event;
+try { event = JSON.parse(input); }
+catch { process.exit(0); }
+
+const toolName = event.tool_name ?? event.toolName ?? '';
+if (toolName !== 'Agent' && toolName !== 'agent') process.exit(0);
+
+const sessionId =
+  event.session_id ?? event.sessionId ??
+  (event.transcript_path
+    ? event.transcript_path.split('/').pop()?.replace(/\.[^.]+$/, '')
+    : null) ??
+  'unknown';
+
+// ── Tier detection ──────────────────────────────────────────────────────────
+// Read license.json to detect client tier (has jti). If only owner-token
+// exists → owner tier. No license/owner-token → treat as owner tier (dev).
+
+let jti = null;
+let isClientTier = false;
+let licenseToken = '';
+
+try {
+  if (existsSync(LICENSE_PATH)) {
+    const lic = JSON.parse(readFileSync(LICENSE_PATH, 'utf8'));
+    jti = lic.jti ?? null;
+    licenseToken = lic.token ?? lic.license ?? '';
+    isClientTier = Boolean(jti);
+  }
+} catch (err) {
+  audit(`warn: license.json read failed: ${(err?.message || err).toString().slice(0, 120)}`);
+}
+
+// For owner tier, read harness token from env or owner-token file.
+let harnessToken = '';
+if (isClientTier) {
+  // Client tier: their own license JWT, never master token.
+  harnessToken = licenseToken;
+} else {
+  harnessToken =
+    process.env.ARIA_HARNESS_TOKEN ||
+    process.env.ARIA_API_KEY ||
+    process.env.ARIA_MASTER_TOKEN ||
+    '';
+  if (!harnessToken && existsSync(OWNER_TOKEN_PATH)) {
+    try { harnessToken = readFileSync(OWNER_TOKEN_PATH, 'utf8').trim(); } catch {}
+  }
+}
+
+const harnessUrl =
+  process.env.ARIA_HIVE_RUNTIME_URL ||
+  process.env.ARIA_HARNESS_BASE_URL ||
+  process.env.ARIA_HARNESS_URL ||
+  'https://harness.ariasos.com';
+
+// ── OwnerTier signal resolution ──────────────────────────────────────────────
+let ownerTier = {
+  hamza: !isClientTier,
+  trustedExec: false,
+  roleProfile: isClientTier ? 'client_tier_worker' : 'general_worker',
+};
+
+if (!isClientTier) {
+  try {
+    if (existsSync(PACKET_CACHE)) {
+      const cached = JSON.parse(readFileSync(PACKET_CACHE, 'utf8'));
+      const signals = cached?.contractGate?.signals ?? {};
+      ownerTier.hamza = signals.hamza === true || signals.hamza === 'true';
+      ownerTier.trustedExec = (cached?.harness || '').includes('trusted_exec_policy=allowed');
+      const adapterStr = cached?.adapter || cached?.harness || '';
+      const roleMatch = adapterStr.match(/role_profile\s*=\s*(\S+)/);
+      if (roleMatch) ownerTier.roleProfile = roleMatch[1];
+    }
+  } catch (err) {
+    audit(`warn: packet cache read failed: ${(err?.message || err).toString().slice(0, 120)}`);
+  }
+}
+
+// ── Path resolution (tier-scoped) ───────────────────────────────────────────
+const safeSession = String(sessionId).replace(/[^a-zA-Z0-9_-]/g, '_');
+
+let handoffPath;
+let parentLedgerPath;
+
+if (isClientTier) {
+  const base = `/var/lib/aria-licensee/${jti}`;
+  handoffPath = `${base}/handoff.json`;
+  parentLedgerPath = `${base}/aria-discoveries-${safeSession}.jsonl`;
+} else {
+  handoffPath = `${HOME}/.claude/aria-agent-harness-handoff.json`;
+  parentLedgerPath = `${HOME}/.claude/aria-discoveries-${safeSession}.jsonl`;
+}
+
+// ── Harness packet fetch for sub-agent substrate binding ────────────────────
+// Layer 1: after writing identity handoff, fetch the harness packet from
+// /api/harness/codex so the sub-agent can load COGNITION (not just identity).
+// Fail-soft: any fetch failure logs a warning and leaves the handoff identity-only.
+// Never blocks the spawn — packet is substrate enrichment, not a gate.
+//
+// Tier-aware packet paths:
+//   Owner: ~/.claude/aria-agent-harness-packet.json
+//   Client: /var/lib/aria-licensee/{jti}/aria-agent-harness-packet.json
+let packetPath = null;
+if (isClientTier) {
+  packetPath = `/var/lib/aria-licensee/${jti}/aria-agent-harness-packet.json`;
+} else {
+  packetPath = `${HOME}/.claude/aria-agent-harness-packet.json`;
+}
+
+async function fetchAndWriteHarnessPacket() {
+  if (!harnessToken || !harnessUrl) {
+    audit('warn: skipping packet fetch — no harnessToken or harnessUrl');
+    return null;
+  }
+  try {
+    const body = JSON.stringify({
+      stage: 'agent-spawn',
+      actor: 'harness-http-client',
+      system: 'claude-coding-agent',
+      surface: 'platform:harness-http-client',
+      isHamza: ownerTier.hamza,
+      sessionId: sessionId,
+      mode: 'subagent',
+    });
+    const resp = await fetch(`${harnessUrl}/api/harness/codex`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${harnessToken}`,
+      },
+      body,
+    });
+    if (!resp.ok) {
+      audit(`warn: harness packet fetch HTTP ${resp.status} — identity-only handoff`);
+      return null;
+    }
+    const data = await resp.json();
+    mkdirSync(dirname(packetPath), { recursive: true });
+    writeFileSync(packetPath, JSON.stringify(data, null, 2));
+    audit(`wrote harness packet tier=${isClientTier ? 'client' : 'owner'} path=${packetPath}`);
+    return packetPath;
+  } catch (err) {
+    audit(`warn: harness packet fetch failed: ${(err?.message || err).toString().slice(0, 200)} — identity-only handoff`);
+    return null;
+  }
+}
+
+const resolvedPacketPath = await fetchAndWriteHarnessPacket();
+
+const handoff = {
+  writtenAt: new Date().toISOString(),
+  parentSessionId: sessionId,
+  harnessToken,
+  harnessUrl,
+  runtimeUrl: SHARED_RUNTIME_URL,
+  sharedSdkRoot: SHARED_SDK_ROOT,
+  ownerTier,
+  parentLedgerPath,
+  cognitionMode: 'mizan-pre-mid-post',
+  requiredSkillPacks: ['aria-harness', 'aria-cognition'],
+  requiredLenses: ['nur', 'mizan', 'hikma', 'tafakkur', 'tadabbur', 'ilham', 'wahi', 'firasah'],
+  cognitionOperatingMethod: {
+    purpose: 'Use Aria cognition to improve the assigned work, not to satisfy formatting after the fact.',
+    loop: [
+      'perceive real substrate before acting',
+      'infer constraints and missing evidence',
+      'shape the next tool/input/output from those constraints',
+      'predict the observable result before claiming success',
+      'return evidence, residual risk, and exact artifact impact to the parent',
+    ],
+    requiredReturnShape: {
+      substrateUsed: ['axiom/frame/memory/packet anchors actually loaded'],
+      decisionDelta: 'what changed in the work because cognition ran',
+      artifactImpact: 'specific files, findings, commands, or prose semantics affected',
+      evidence: 'observed tool output, file state, endpoint result, or explicit unverified boundary',
+      unresolvedRisk: 'remaining risk or none',
+    },
+    prohibitedPatterns: [
+      'decorative cognition that does not alter the work',
+      'summary-only sub-agent result without evidence',
+      'asking the parent/user for choices that substrate can resolve',
+      'claiming completion from intent rather than observation',
+    ],
+  },
+  ttlMs: HANDOFF_TTL_MS,
+  // harnessPacketPath is set only if packet was successfully fetched;
+  // absent means sub-agent should fall back to calling /api/harness/codex directly.
+  ...(resolvedPacketPath ? { harnessPacketPath: resolvedPacketPath } : {}),
+};
+
+try {
+  mkdirSync(dirname(handoffPath), { recursive: true });
+  writeFileSync(handoffPath, JSON.stringify(handoff, null, 2));
+  audit(
+    `wrote handoff tier=${isClientTier ? 'client' : 'owner'} jti=${jti ?? 'none'} ` +
+    `session=${sessionId} hamza=${ownerTier.hamza} role=${ownerTier.roleProfile} ` +
+    `packetPath=${resolvedPacketPath ?? 'none'}`,
+  );
+} catch (err) {
+  audit(`ERROR: handoff write failed: ${(err?.message || err).toString().slice(0, 200)}`);
+}
+
+process.exit(0);