lazyclaw 4.2.2 → 5.0.0

package/gateway/http_gateway.mjs

@@ -0,0 +1,304 @@
+// HTTP/SSE realisation of the device gateway — Phase 27.
+//
+// The OpenClaw "gateway" is a long-lived process companion nodes connect
+// to and authenticate against. lazyclaw realises that over the EXISTING
+// HTTP daemon (no `ws` dependency, no hand-rolled RFC6455 framing): the
+// device-auth handshake is two POSTs, authenticated routes carry the
+// device's bearer token, and server-pushed events ride an SSE stream.
+// The security model is unchanged from gateway/device_auth.mjs:
+//
+//   POST /gateway/connect/challenge {deviceId?}        -> { nonce, ts }
+//     Mint a single-use, time-boxed challenge (ChallengeRegistry).
+//
+//   POST /gateway/connect {payload, signature, publicKey, nonce, ...}
+//     verifyConnect (Ed25519 sig + identity-binding + nonce + freshness),
+//     then ChallengeRegistry.consume (single-use / anti-replay). On
+//     success: an APPROVED device gets its rotated bearer token; an
+//     unapproved device gets a 403 `pending` receipt and a pairing
+//     request is recorded for the operator to `lazyclaw nodes approve`.
+//
+//   GET  /gateway/whoami        (Authorization: Bearer <deviceToken>,
+//                                x-device-id: <deviceId>)  -> { deviceId }
+//   GET  /gateway/events        (same auth)               -> text/event-stream
+//     Authenticated push channel. broadcast() fans an event to every live
+//     subscriber. Event producers (e.g. remote tool-call approval) are a
+//     later pass; the transport + auth are here now.
+//
+// These routes are mounted by daemon.mjs OUTSIDE the daemon's shared
+// `auth-token` gate: device-auth is their own gate, and the only
+// unauthenticated route (challenge) returns nothing but a random nonce.
+
+import crypto from 'node:crypto';
+import {
+  PairingStore,
+  deviceIdFromPublicKey,
+  verifyConnect,
+} from './device_auth.mjs';
+import { redactSecrets } from '../mas/redact.mjs';
+
+// Matches the daemon's readTextBody cap (1 MiB) so the Content-Length
+// pre-check and the stream reader agree on the limit.
+const GATEWAY_MAX_BODY = 1_048_576;
+
+function writeJson(res, status, body) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(body));
+}
+
+function bearerToken(req) {
+  const h = req.headers?.authorization || req.headers?.Authorization || '';
+  const m = /^Bearer\s+(.+)$/i.exec(String(h).trim());
+  return m ? m[1].trim() : '';
+}
+
+/**
+ * Build a gateway instance. `challengeRegistry` is created ONCE per daemon
+ * process and shared across requests — a challenge minted by one request
+ * is consumed by a later one, so it must outlive a single call. `nowFn`
+ * is injected for deterministic tests.
+ */
+export function createGateway({ configDir, challengeRegistry, nowFn = Date.now, heartbeatMs = 0 } = {}) {
+  if (!challengeRegistry) throw new Error('createGateway requires a challengeRegistry');
+  // Each entry: { res, deviceId }. Bounded globally and per-device so an
+  // authenticated device can't exhaust sockets/fds with open streams.
+  const sseClients = new Set();
+  const MAX_SSE_GLOBAL = 256;
+  const MAX_SSE_PER_DEVICE = 8;
+  const deviceStreamCount = (deviceId) => {
+    let n = 0;
+    for (const c of sseClients) if (c.deviceId === deviceId) n++;
+    return n;
+  };
+
+  // A fresh PairingStore per op re-reads the on-disk file, so an `approve`
+  // performed by the CLI in another process is visible to the daemon
+  // without a restart.
+  const store = () => new PairingStore(configDir);
+
+  // ── exec-approval producer ───────────────────────────────────────
+  // A trusted in-process caller (the daemon's POST /exec/request, which
+  // sits behind the daemon auth-token gate) calls requestApproval(); that
+  // broadcasts `exec.approval.requested` to every subscribed device and
+  // returns a Promise that settles when a device POSTs
+  // /gateway/exec/resolve (or on timeout). This is the remote
+  // human-in-the-loop gate for sensitive tool calls.
+  const approvals = new Map(); // id -> { detail, resolveFn, timer, createdAt }
+  const MAX_APPROVALS = 256;
+  const APPROVAL_TTL_MS = 5 * 60 * 1000;
+
+  // What the device is shown about a pending approval. Args may carry
+  // secrets (e.g. a bash command with a token), so the summary is redacted
+  // and capped before it leaves the process.
+  function approvalView(detail = {}) {
+    const summary = redactSecrets(String(detail.summary ?? detail.args ?? '')).slice(0, 500);
+    return { tool: detail.tool || '', agentId: detail.agentId || '', summary };
+  }
+
+  function requestApproval(detail = {}, { timeoutMs = APPROVAL_TTL_MS } = {}) {
+    // Bound the table — deny-and-evict the oldest pending if we're full so
+    // an approval flood can't grow memory without limit.
+    if (approvals.size >= MAX_APPROVALS) {
+      const oldest = approvals.keys().next().value;
+      if (oldest !== undefined) resolveApproval(oldest, false, 'system:capacity');
+    }
+    const id = 'ap_' + crypto.randomBytes(9).toString('hex');
+    let resolveFn;
+    const promise = new Promise((r) => { resolveFn = r; });
+    // Clamp both ends: a caller can't pin an HTTP socket + entry for an
+    // arbitrary (e.g. multi-day) duration, nor poll faster than 1s.
+    const ttl = Math.min(APPROVAL_TTL_MS, Math.max(1000, timeoutMs || APPROVAL_TTL_MS));
+    const timer = setTimeout(() => {
+      if (approvals.has(id)) {
+        approvals.delete(id);
+        resolveFn({ id, approved: false, reason: 'timeout' });
+        broadcast('exec.approval.resolved', { id, approved: false, reason: 'timeout' });
+      }
+    }, ttl);
+    if (typeof timer.unref === 'function') timer.unref();
+    approvals.set(id, { detail, resolveFn, timer, createdAt: nowFn() });
+    broadcast('exec.approval.requested', { id, ...approvalView(detail) });
+    return { id, promise };
+  }
+
+  // Trust model: every APPROVED device is uniformly trusted — any of them
+  // may resolve any pending approval and list pending ids. There is no
+  // per-device scoping by design (a paired device is an operator surface).
+  // Approval ids are unguessable (crypto.randomBytes), so only an
+  // already-trusted, authenticated device can act. If you pair a
+  // lower-trust device, revoke it (`lazyclaw nodes revoke`) rather than
+  // relying on approval scoping.
+  function resolveApproval(id, decision, by = '') {
+    const a = approvals.get(id);
+    if (!a) return { ok: false, reason: 'unknown or already resolved' };
+    clearTimeout(a.timer);
+    approvals.delete(id);
+    const approved = decision === true || decision === 'approve' || decision === 'allow';
+    a.resolveFn({ id, approved, by, reason: approved ? 'approved' : 'denied' });
+    broadcast('exec.approval.resolved', { id, approved, by });
+    return { ok: true, id, approved };
+  }
+
+  function pendingApprovals() {
+    return [...approvals.entries()].map(([id, a]) => ({ id, createdAt: a.createdAt, ...approvalView(a.detail) }));
+  }
+
+  async function readJsonBody(req, readBody) {
+    let raw;
+    try { raw = await readBody(req); }
+    catch { return { __tooLarge: true }; }                   // body exceeded the cap
+    if (!raw) return {};
+    try { return JSON.parse(raw); } catch { return null; }   // null => malformed
+  }
+
+  function authDevice(req) {
+    const token = bearerToken(req);
+    const deviceId = String(req.headers?.['x-device-id'] || '').trim();
+    if (!token || !deviceId) return null;
+    if (!store().verifyToken(deviceId, token)) return null;
+    return { deviceId };
+  }
+
+  async function handle(req, res, { readBody }) {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const p = url.pathname;
+    const m = req.method;
+
+    // ── challenge ────────────────────────────────────────────────
+    if (m === 'POST' && p === '/gateway/connect/challenge') {
+      const challenge = challengeRegistry.create();
+      return writeJson(res, 200, challenge);
+    }
+
+    // ── connect ──────────────────────────────────────────────────
+    if (m === 'POST' && p === '/gateway/connect') {
+      // Reject an oversized body up front via Content-Length so we answer
+      // 413 cleanly instead of the body reader destroying the socket
+      // (ECONNRESET) once the cap is hit mid-stream.
+      const clen = Number(req.headers?.['content-length'] || 0);
+      if (Number.isFinite(clen) && clen > GATEWAY_MAX_BODY) {
+        return writeJson(res, 413, { ok: false, reason: 'request body too large' });
+      }
+      const body = await readJsonBody(req, readBody);
+      if (body && body.__tooLarge) return writeJson(res, 413, { ok: false, reason: 'request body too large' });
+      if (!body) return writeJson(res, 400, { ok: false, reason: 'malformed body' });
+      const { payload, signature, publicKey, nonce, platform = '', label = '' } = body;
+      if (!payload || !signature || !publicKey || !nonce) {
+        return writeJson(res, 400, { ok: false, reason: 'payload, signature, publicKey and nonce are required' });
+      }
+      let deviceId;
+      try {
+        deviceId = deviceIdFromPublicKey(publicKey);
+      } catch {
+        // Generic — don't reflect node:crypto parse internals.
+        return writeJson(res, 400, { ok: false, reason: 'invalid public key' });
+      }
+      const now = nowFn();
+      const verdict = verifyConnect({ payload, signature, publicKey, challenge: { nonce }, nowMs: now });
+      if (!verdict.ok) {
+        return writeJson(res, 401, { ok: false, reason: verdict.reason });
+      }
+      // Single-use / anti-replay: only AFTER a valid signature, and only
+      // once. A replayed (payload,signature) re-presents the same nonce,
+      // which consume() has already retired.
+      if (!challengeRegistry.consume(nonce, now)) {
+        return writeJson(res, 401, { ok: false, reason: 'challenge expired or already used' });
+      }
+      const st = store();
+      if (st.isApproved(deviceId)) {
+        return writeJson(res, 200, { ok: true, deviceId, token: st.tokenFor(deviceId) });
+      }
+      // Not approved — record intent once (don't pile up duplicates) and
+      // tell the device to wait for the operator's approval.
+      const existing = st.pendingForDevice(deviceId);
+      let receipt;
+      if (existing) {
+        receipt = { requestId: existing.requestId };
+      } else {
+        try {
+          receipt = st.requestPairing({ deviceId, platform, label });
+        } catch (err) {
+          // Pending-requests ceiling hit — shed load rather than 500.
+          if (err && err.code === 'PAIRING_CAP') {
+            return writeJson(res, 429, { ok: false, reason: 'too many pending pairing requests; try later' });
+          }
+          throw err;
+        }
+      }
+      return writeJson(res, 403, { ok: false, status: 'pending', deviceId, requestId: receipt.requestId });
+    }
+
+    // ── whoami (token-authenticated) ─────────────────────────────
+    if (m === 'GET' && p === '/gateway/whoami') {
+      const ident = authDevice(req);
+      if (!ident) return writeJson(res, 401, { ok: false, reason: 'invalid device token' });
+      return writeJson(res, 200, { ok: true, deviceId: ident.deviceId });
+    }
+
+    // ── exec approval: device resolves a pending request ─────────
+    if (m === 'POST' && p === '/gateway/exec/resolve') {
+      const ident = authDevice(req);
+      if (!ident) return writeJson(res, 401, { ok: false, reason: 'invalid device token' });
+      const body = await readJsonBody(req, readBody);
+      if (body && body.__tooLarge) return writeJson(res, 413, { ok: false, reason: 'request body too large' });
+      if (!body || !body.id) return writeJson(res, 400, { ok: false, reason: 'id and decision are required' });
+      const r = resolveApproval(body.id, body.decision, ident.deviceId);
+      return writeJson(res, r.ok ? 200 : 404, r);
+    }
+
+    // ── exec approval: device lists what's awaiting a decision ───
+    if (m === 'GET' && p === '/gateway/exec/pending') {
+      const ident = authDevice(req);
+      if (!ident) return writeJson(res, 401, { ok: false, reason: 'invalid device token' });
+      return writeJson(res, 200, { pending: pendingApprovals() });
+    }
+
+    // ── events (SSE, token-authenticated) ────────────────────────
+    if (m === 'GET' && p === '/gateway/events') {
+      const ident = authDevice(req);
+      if (!ident) return writeJson(res, 401, { ok: false, reason: 'invalid device token' });
+      if (sseClients.size >= MAX_SSE_GLOBAL) {
+        return writeJson(res, 429, { ok: false, reason: 'event-stream capacity reached' });
+      }
+      if (deviceStreamCount(ident.deviceId) >= MAX_SSE_PER_DEVICE) {
+        return writeJson(res, 429, { ok: false, reason: 'too many event streams for this device' });
+      }
+      res.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+      });
+      res.write(`event: connected\ndata: ${JSON.stringify({ deviceId: ident.deviceId })}\n\n`);
+      const entry = { res, deviceId: ident.deviceId };
+      sseClients.add(entry);
+      const onClose = () => { sseClients.delete(entry); };
+      if (typeof req.once === 'function') req.once('close', onClose);
+      if (typeof res.once === 'function') res.once('close', onClose);
+      return; // connection stays open
+    }
+
+    return writeJson(res, 404, { ok: false, reason: 'no such gateway route' });
+  }
+
+  // Fan an event out to every live SSE subscriber. Best-effort: a dead
+  // socket is dropped, never throws into the caller.
+  function broadcast(eventName, data) {
+    const frame = `event: ${eventName}\ndata: ${JSON.stringify(data ?? {})}\n\n`;
+    for (const entry of sseClients) {
+      try { entry.res.write(frame); } catch { sseClients.delete(entry); }
+    }
+    return sseClients.size;
+  }
+
+  // Optional keep-alive: periodic `tick` event so SSE proxies don't idle
+  // out the stream and subscribers can prove the channel is live. Opt-in
+  // (heartbeatMs>0) and unref'd so it never holds the process open or
+  // leaks in unit tests that don't ask for it.
+  let heartbeat = null;
+  if (heartbeatMs > 0) {
+    heartbeat = setInterval(() => { broadcast('tick', { ts: nowFn() }); }, heartbeatMs);
+    if (typeof heartbeat.unref === 'function') heartbeat.unref();
+  }
+  function close() { if (heartbeat) { clearInterval(heartbeat); heartbeat = null; } }
+
+  return { handle, broadcast, sseClients, requestApproval, resolveApproval, pendingApprovals, close };
+}

package/mas/agent_memory.mjs

@@ -16,6 +16,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 
+import { runTextCompletion } from './provider_adapters.mjs';
+import { redactSecrets, neutralizeRoleLabels } from './redact.mjs';
+
 export const DEFAULT_MAX_CHARS = 12 * 1024;
 const AGENTS_MEM_DIR = path.join('memory', 'agents');
 
@@ -53,6 +56,11 @@ export function readMemory(name, configDir = defaultConfigDir(), maxChars = DEFA
     let cut = raw.slice(0, maxChars);
     const lastBlank = cut.lastIndexOf('\n\n');
     if (lastBlank > maxChars * 0.6) cut = cut.slice(0, lastBlank);
+    // Drop a trailing lone high-surrogate (U+D800..U+DBFF) left behind
+    // when the slice landed in the middle of a surrogate pair, so the
+    // returned string is never invalid UTF-16.
+    const lastUnit = cut.charCodeAt(cut.length - 1);
+    if (lastUnit >= 0xd800 && lastUnit <= 0xdbff) cut = cut.slice(0, -1);
     return cut + '\n\n…[older entries truncated]\n';
   } catch {
     return '';
@@ -135,19 +143,28 @@ export function buildMemoryBlock(name, configDir = defaultConfigDir(), maxChars
 // to the on-disk file (auto mode) or surface it to the user (manual
 // command). Throws on hard failure; the router catches and logs.
 //
-// We use the agent's own provider via the existing tool-use callOnce
-// adapters because they are already wired up with apiKey/baseUrl
-// passthrough. No tools are advertised — reflection is pure text.
+// We use the agent's own provider via the shared no-tools text
+// completion (mas/provider_adapters.mjs), which is already wired for
+// apiKey/baseUrl passthrough. No tools are advertised — reflection is
+// pure text. This module owns the reflection-specific transcript +
+// prompt; the call mechanics are shared with skill synthesis.
 export async function reflectOnce({ agent, task, apiKey, baseUrl, fetchImpl, maxBullets = 6 } = {}) {
   if (!agent || !task) throw new AgentMemoryError('agent and task are required', 'AGENT_MEMORY_BAD_INPUT');
-  const adapter = await pickAdapter(agent.provider);
 
-  const transcript = (Array.isArray(task.turns) ? task.turns : [])
-    .map((t) => {
-      const who = t.agent === 'user' ? 'User' : t.agent === 'system' ? 'System' : t.agent;
-      return `[${who}] ${t.text || ''}`;
-    })
-    .join('\n\n') || '(no turns)';
+  // Redact secrets from the transcript BEFORE it leaves for the model,
+  // so a token pasted into a task turn never reaches the LLM. Symmetric
+  // with skill_synth.synthesizeSkill, which already redacts its
+  // transcript; both share mas/redact.mjs.
+  const transcript = redactSecrets(
+    (Array.isArray(task.turns) ? task.turns : [])
+      .map((t) => {
+        const who = t.agent === 'user' ? 'User' : t.agent === 'system' ? 'System' : t.agent;
+        // Defang any forged role label inside the (model-controlled) body
+        // so a turn can't inject its own [System]/[User] authority line.
+        return `[${who}] ${neutralizeRoleLabels(t.text || '')}`;
+      })
+      .join('\n\n') || '(no turns)',
+  );
 
   const userMessage =
     `You just finished task "${task.title || '(untitled)'}" (id ${task.id}). Here is the full transcript:\n\n` +
@@ -157,33 +174,17 @@ export async function reflectOnce({ agent, task, apiKey, baseUrl, fetchImpl, max
     `gotchas, teammate preferences. Do NOT repeat generic advice. Do NOT exceed ${maxBullets} ` +
     `bullets. Reply with the bullets only — no headers, no preamble.`;
 
-  const initialUser = adapter.initialUserMessage
-    ? adapter.initialUserMessage(userMessage)
-    : { role: 'user', content: userMessage };
-
-  const resp = await adapter.callOnce({
-    messages: [initialUser],
-    tools: [],
+  const text = await runTextCompletion({
+    provider: agent.provider,
     model: agent.model,
-    apiKey,
     system: agent.role || '',
+    userMessage,
+    apiKey,
     baseUrl,
     fetchImpl,
   });
-  if (resp.kind !== 'final') {
-    throw new AgentMemoryError(`reflection expected text reply, got ${resp.kind}`, 'AGENT_MEMORY_NO_TEXT');
-  }
-  const text = (resp.text || '').trim();
-  return text;
-}
-
-async function pickAdapter(provider) {
-  switch (provider) {
-    case 'anthropic':  return await import('../providers/tool_use/anthropic.mjs');
-    case 'openai':     return await import('../providers/tool_use/openai.mjs');
-    case 'gemini':     return await import('../providers/tool_use/gemini.mjs');
-    case 'claude-cli': return await import('../providers/tool_use/claude_cli.mjs');
-    default:
-      throw new AgentMemoryError(`provider "${provider}" does not support reflection`, 'AGENT_MEMORY_NO_PROVIDER');
-  }
+  // Redact again on the way back: the model may echo a secret it saw in
+  // the transcript, and this body is persisted via prependEntry and
+  // replayed into every future system prompt.
+  return redactSecrets(text).trim();
 }

package/mas/agent_turn.mjs

@@ -25,6 +25,7 @@ import * as anthropic from '../providers/tool_use/anthropic.mjs';
 import * as openai from '../providers/tool_use/openai.mjs';
 import * as gemini from '../providers/tool_use/gemini.mjs';
 import * as claudeCli from '../providers/tool_use/claude_cli.mjs';
+import { put as _trajPut } from './trajectory_store.mjs';
 
 export class AgentTurnError extends Error {
   constructor(message, code) {
@@ -70,6 +71,8 @@ export async function runAgentTurn({
   apiKey,
   maxIterations = DEFAULT_MAX_ITERATIONS,
   signal,
+  approve,
+  trajectoryRef,
 } = {}) {
   if (!agent) throw new AgentTurnError('agent is required', 'NO_AGENT');
   const adapter = adapterFor(agent.provider);
@@ -91,6 +94,29 @@ export async function runAgentTurn({
   const toolCalls = [];
   let iterations = 0;
   let lastText = '';
+  if (trajectoryRef && !trajectoryRef.startedAt) trajectoryRef.startedAt = Date.now();
+
+  const _maybePersistTrajectory = async (outcome) => {
+    if (!trajectoryRef) return;
+    try {
+      await _trajPut({
+        taskId, agentName: agent.name || 'agent',
+        workerProvider: agent.provider, workerModel: agent.model,
+        startedAt: trajectoryRef.startedAt || Date.now(),
+        endedAt: Date.now(),
+        systemPrompt: agent.role || '',
+        userMessages: userMessage ? [String(userMessage)] : [],
+        turns: toolCalls.map((c, i) => ({
+          turnIdx: i, role: 'tool', content: '',
+          toolCalls: [{ name: c.name, args: c.input, result: JSON.stringify(c.result), success: c.ok, durationMs: 0 }],
+        })).concat(lastText ? [{
+          turnIdx: toolCalls.length, role: 'assistant', content: lastText, toolCalls: [],
+        }] : []),
+        finalAnswer: lastText,
+        outcome,
+      }, { configDir });
+    } catch { /* trajectory failure must not break the agent turn */ }
+  };
 
   while (iterations < maxIterations) {
     if (signal?.aborted) return { text: lastText, iterations, stoppedBy: 'abort', toolCalls };
@@ -102,6 +128,7 @@ export async function runAgentTurn({
     if (resp.text) lastText = resp.text;
 
     if (resp.kind === 'final') {
+      await _maybePersistTrajectory('done');
       return { text: resp.text || '', iterations, stoppedBy: 'final', toolCalls };
     }
 
@@ -118,7 +145,7 @@ export async function runAgentTurn({
       try {
         result = await runTool({
           agent, tool: call.name, args: call.input,
-          taskId, configDir, cwd,
+          taskId, configDir, cwd, approve,
         });
         if (result && result.ok === false) ok = false;
       } catch (err) {
@@ -139,9 +166,11 @@ export async function runAgentTurn({
     // model so it can recover. Only an extraordinary error (e.g. the
     // provider returned a malformed envelope) bails out here.
     if (toolErrored && process.env.LAZYCLAW_TOOL_STRICT === '1') {
+      await _maybePersistTrajectory('failed');
       return { text: lastText, iterations, stoppedBy: 'tool_error', toolCalls };
     }
   }
 
+  await _maybePersistTrajectory('abandoned');
   return { text: lastText, iterations, stoppedBy: 'budget', toolCalls };
 }

package/mas/confidence.mjs

@@ -0,0 +1,108 @@
+// Confidence calculator for v5 skills — spec §0.1 H2, §3.5.
+//
+// Pure functions, no I/O. Used by skill_synth v2 to stamp frontmatter
+// and by trajectory_store recall ranking to weight near-duplicates.
+//
+//   wilsonLowerBound(s, n)           — 95% Wilson lower bound on success rate.
+//   crossCliDampen(score, trainer, provider, factor?)
+//                                    — multiply by `factor` (default 0.85)
+//                                      when trainer provider differs from
+//                                      worker provider (canonical decision
+//                                      §0.1 H2). Phase H2 makes the factor
+//                                      tunable; same-family scores are
+//                                      always returned unchanged.
+//   recencyDecay(ageMs, halfLifeMs)  — exponential decay weight (0..1].
+//   computeConfidence({successes, trials, ageMs, trainer, provider, dampenFactor?})
+//                                    — composed score in [0, 1].
+//   resolveDampenFactor(cfg)         — pull `crossCliDampenFactor` out of
+//                                      cfg.orchestra.learning (or legacy
+//                                      cfg.orchestrator.learning); clamps
+//                                      to [0,1]; defaults to 0.85 on miss.
+
+const Z = 1.96; // 95% confidence two-sided
+
+export const DEFAULT_CROSS_CLI_DAMPEN = 0.85;
+
+export function wilsonLowerBound(successes, trials) {
+  const s = Number(successes) || 0;
+  const n = Number(trials) || 0;
+  if (n <= 0) return 0;
+  const phat = s / n;
+  const z2 = Z * Z;
+  const denom = 1 + z2 / n;
+  const center = phat + z2 / (2 * n);
+  const margin = Z * Math.sqrt((phat * (1 - phat) + z2 / (4 * n)) / n);
+  const lb = (center - margin) / denom;
+  return Math.max(0, Math.min(1, lb));
+}
+
+const PROVIDER_FAMILY = {
+  'claude-cli': 'anthropic',
+  'anthropic': 'anthropic',
+  'codex-cli': 'openai',
+  'openai': 'openai',
+  'gemini-cli': 'gemini',
+  'gemini': 'gemini',
+  'ollama': 'ollama',
+};
+
+export function sameFamily(a, b) {
+  if (!a || !b) return false;
+  return PROVIDER_FAMILY[a] === PROVIDER_FAMILY[b];
+}
+
+// Normalise a caller-supplied dampening factor. Anything non-finite (NaN,
+// non-numeric strings, undefined) falls back to the canonical 0.85 so a
+// typo in config does not silently zero out every cross-CLI skill.
+function _normalizeFactor(factor) {
+  if (factor === null || factor === undefined) return DEFAULT_CROSS_CLI_DAMPEN;
+  const n = Number(factor);
+  if (!Number.isFinite(n)) return DEFAULT_CROSS_CLI_DAMPEN;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+export function crossCliDampen(score, trainerProvider, workerProvider, factor) {
+  if (!trainerProvider || !workerProvider) return score;
+  if (sameFamily(trainerProvider, workerProvider)) return score;
+  return score * _normalizeFactor(factor);
+}
+
+export function recencyDecay(ageMs, halfLifeMs = 30 * 24 * 60 * 60 * 1000) {
+  const t = Math.max(0, Number(ageMs) || 0);
+  const hl = Math.max(1, Number(halfLifeMs) || 1);
+  return Math.pow(0.5, t / hl);
+}
+
+export function computeConfidence({
+  successes = 0,
+  trials = 0,
+  ageMs = 0,
+  trainerProvider = null,
+  workerProvider = null,
+  halfLifeMs,
+  dampenFactor,
+} = {}) {
+  const base = wilsonLowerBound(successes, trials);
+  const decayed = base * recencyDecay(ageMs, halfLifeMs);
+  const dampened = crossCliDampen(decayed, trainerProvider, workerProvider, dampenFactor);
+  return Math.max(0, Math.min(1, dampened));
+}
+
+// Pull the tunable factor out of config. Honours both the canonical
+// `cfg.orchestra.learning.crossCliDampenFactor` shape and the legacy
+// `cfg.orchestrator.learning.crossCliDampenFactor` (v4 callers). Returns
+// 0.85 when missing/invalid so callers never have to gate on undefined.
+export function resolveDampenFactor(cfg) {
+  if (!cfg || typeof cfg !== 'object') return DEFAULT_CROSS_CLI_DAMPEN;
+  const orchestra = cfg.orchestra || cfg.orchestrator || {};
+  const learning = orchestra.learning || {};
+  const raw = learning.crossCliDampenFactor;
+  if (raw === undefined || raw === null) return DEFAULT_CROSS_CLI_DAMPEN;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return DEFAULT_CROSS_CLI_DAMPEN;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}