sentinelayer-cli 0.39.2 → 0.41.0

package/src/mcp/smoke.js

@@ -5,6 +5,7 @@ import { requestHostedMcpAccessToken } from "./token-service.js";
 
 const PASS = "PASS";
 const FAIL = "FAIL";
+const SESSION_EVENTS_LIST_TOOL = "sessions_events_list";
 
 function joinUrl(base, suffix) {
   const normalizedBase = String(base || "").replace(/\/+$/, "");
@@ -233,13 +234,13 @@ export async function runHostedMcpSmoke({
   }
 
   if (normalizedSessionId) {
-    if (!toolNames.includes("sessions.events.list")) {
+    if (!toolNames.includes(SESSION_EVENTS_LIST_TOOL)) {
       probes.push({
         id: "session_events_list",
-        label: "MCP sessions.events.list",
+        label: `MCP ${SESSION_EVENTS_LIST_TOOL}`,
         status: 0,
         verdict: FAIL,
-        detail: "sessions.events.list tool was not advertised by tools/list",
+        detail: `${SESSION_EVENTS_LIST_TOOL} tool was not advertised by tools/list`,
         sessionId: normalizedSessionId,
       });
     } else {
@@ -254,7 +255,7 @@ export async function runHostedMcpSmoke({
           id: "mcp-smoke-events",
           method: "tools/call",
           params: {
-            name: "sessions.events.list",
+            name: SESSION_EVENTS_LIST_TOOL,
             arguments: {
               sessionId: normalizedSessionId,
               limit: normalizedLimit,
@@ -266,7 +267,7 @@ export async function runHostedMcpSmoke({
       if (!eventsResponse.reached) {
         probes.push({
           id: "session_events_list",
-          label: "MCP sessions.events.list",
+          label: `MCP ${SESSION_EVENTS_LIST_TOOL}`,
           status: eventsResponse.status,
           verdict: FAIL,
           detail: eventsResponse.detail,
@@ -275,7 +276,7 @@ export async function runHostedMcpSmoke({
       } else if (eventsResponse.status !== 200) {
         probes.push({
           id: "session_events_list",
-          label: "MCP sessions.events.list",
+          label: `MCP ${SESSION_EVENTS_LIST_TOOL}`,
           status: eventsResponse.status,
           verdict: FAIL,
           detail: `expected HTTP 200, got HTTP ${eventsResponse.status}`,
@@ -284,7 +285,7 @@ export async function runHostedMcpSmoke({
       } else if (eventsResponse.json?.error) {
         probes.push({
           id: "session_events_list",
-          label: "MCP sessions.events.list",
+          label: `MCP ${SESSION_EVENTS_LIST_TOOL}`,
           status: eventsResponse.status,
           verdict: FAIL,
           detail: summarizeJsonRpcError(eventsResponse.json.error, redactionSecrets),
@@ -297,7 +298,7 @@ export async function runHostedMcpSmoke({
           .filter((value) => Number.isFinite(value));
         probes.push({
           id: "session_events_list",
-          label: "MCP sessions.events.list",
+          label: `MCP ${SESSION_EVENTS_LIST_TOOL}`,
           status: eventsResponse.status,
           verdict: PASS,
           detail: `${events.length} event(s) returned`,

package/src/pocket/ring-owner.js

@@ -0,0 +1,97 @@
+import process from "node:process";
+
+import { requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+
+// The client half of Senti Pocket "ring the owner": an authed agent/CLI DESCRIBES a decision the owner must make and the
+// pocket-gateway (POST /dial/ring-owner) builds the canonical NeedCarterSignal server-side + rings the owner's phone.
+// SECURITY: this AUTHORS NOTHING — it only rings. The ring TARGET is the CALLER's own verified identity (the gateway
+// derives it from the bearer, NEVER a body field), so a caller can only ring THEIR OWN phone. The answered-call write
+// keeps its own governed confirm (dialing relaxes nothing).
+export const RING_OWNER_KINDS = Object.freeze(["decisionYours", "pickOption", "go", "info", "checkpointReady"]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+/**
+ * Resolve the pocket-gateway base URL — DISTINCT from the senti apiUrl (do NOT reuse resolveApiUrl; that is the API host).
+ * Precedence: env SENTI_POCKET_URL -> env POCKET_GATEWAY_URL -> a config value if the caller passed one. Absent -> "".
+ * A present value MUST be an http(s) URL (fail-closed on a bogus scheme). Trailing slashes trimmed.
+ */
+export function resolvePocketGatewayUrl({ env = process.env, configUrl = "" } = {}) {
+  const raw =
+    normalizeString(env.SENTI_POCKET_URL) ||
+    normalizeString(env.POCKET_GATEWAY_URL) ||
+    normalizeString(configUrl);
+  if (!raw) return "";
+  if (!/^https?:\/\//i.test(raw)) throw new Error("pocket gateway URL must be an http(s) URL");
+  return raw.replace(/\/+$/, "");
+}
+
+/**
+ * Ring the owner about a session decision via the pocket-gateway POST /dial/ring-owner.
+ * @param {string} question  the decision/question to put to the owner
+ * @param {object} opts  kind/sessionId/options/whatWeNeed/checkpointId/requestedBy/idempotencyKey/gatewayUrl + injectable
+ *                       resolveAuthSession + requestMutation (hermetic tests) + env
+ * @returns the gateway result ({ dialId, dispatched, reason?, kind?, idempotent? }).
+ */
+export async function ringOwner(
+  question,
+  {
+    kind = "decisionYours",
+    sessionId = "",
+    options = [],
+    whatWeNeed = "",
+    checkpointId = "",
+    requestedBy = "",
+    idempotencyKey = "",
+    gatewayUrl = "",
+    configUrl = "",
+    env = process.env,
+    cwd = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const q = normalizeString(question);
+  if (!q) throw new Error("question is required.");
+  const sid = normalizeString(sessionId);
+  if (!sid) throw new Error("session id is required (--session <id>).");
+  const normKind = normalizeString(kind) || "decisionYours";
+  if (!RING_OWNER_KINDS.includes(normKind)) {
+    throw new Error(`kind must be one of: ${RING_OWNER_KINDS.join(", ")}`);
+  }
+  if (normKind === "pickOption" && (!Array.isArray(options) || options.length === 0)) {
+    throw new Error("pickOption requires at least one --option.");
+  }
+
+  const gw = normalizeString(gatewayUrl)
+    ? normalizeString(gatewayUrl).replace(/\/+$/, "")
+    : resolvePocketGatewayUrl({ env, configUrl });
+  if (!gw) {
+    throw new Error("pocket gateway URL not configured. Set SENTI_POCKET_URL to the pocket-gateway base URL.");
+  }
+
+  const auth = await resolveAuthSession({ cwd, env, autoRotate: false });
+  if (!auth?.token) {
+    throw new Error("Not authenticated. Run `sl auth login` first.");
+  }
+
+  const context = { sessionId: sid };
+  if (normalizeString(whatWeNeed)) context.whatWeNeed = normalizeString(whatWeNeed);
+  if (normalizeString(checkpointId)) context.checkpointId = normalizeString(checkpointId);
+  const body = { question: q, kind: normKind, context };
+  if (normKind === "pickOption") body.options = options.map((o) => String(o));
+  if (normalizeString(requestedBy)) body.requestedBy = normalizeString(requestedBy);
+  if (normalizeString(idempotencyKey)) body.idempotencyKey = normalizeString(idempotencyKey);
+
+  // requestJsonMutation auto-derives a transport Idempotency-Key from operationName (retry-safe at the wire); the
+  // gateway's own ring-level dedupe (PR-B4) keys on body.idempotencyKey OR a content hash, so an identical retry rings once.
+  return requestMutation(`${gw}/dial/ring-owner`, {
+    method: "POST",
+    operationName: "pocket.ring_owner",
+    headers: { Authorization: `Bearer ${auth.token}` },
+    body,
+  });
+}

package/src/review/local-review.js

@@ -73,6 +73,12 @@ const SEVERITY_ORDER = new Map([
 
 const TEST_OR_FIXTURE_PATH_PATTERN = /(?:^|[\\/])(?:test|tests|__tests__|fixtures?)(?:[\\/]|$)/i;
 const LOCAL_REVIEW_SOURCE_PATH_PATTERN = /(?:^|[\\/])src[\\/]review[\\/]local-review\.js$/i;
+const SQL_STRING_CONCATENATION_PATTERN =
+  /["'`]\s*(?:SELECT|INSERT|UPDATE|DELETE)\b[^\n]{0,160}["'`]\s*\+/i;
+const SQL_CONCAT_EXCLUDE_PATH_PATTERN = new RegExp(
+  `${TEST_LIKE_PATH_PATTERN.source}|${LOCAL_REVIEW_SOURCE_PATH_PATTERN.source}`,
+  "i"
+);
 const WORK_ITEM_MARKER_EXCLUDE_PATH_PATTERN = new RegExp(
   `${TEST_OR_FIXTURE_PATH_PATTERN.source}|${LOCAL_REVIEW_SOURCE_PATH_PATTERN.source}`,
   "i"
@@ -249,11 +255,9 @@ const DETERMINISTIC_REVIEW_RULES = Object.freeze([
     severity: "P2",
     message: "Possible SQL string concatenation detected.",
     suggestedFix: "Use parameterized queries and prepared statements.",
-    regex: /\b(?:SELECT|INSERT|UPDATE|DELETE)\b[^;\n]{0,140}\+/i,
+    regex: SQL_STRING_CONCATENATION_PATTERN,
     sourceOnly: true,
-    // Self-scan dampener: the local-review source itself contains SQL-like
-    // regex literals and must not flag itself.
-    excludePathPattern: LOCAL_REVIEW_SOURCE_PATH_PATTERN,
+    excludePathPattern: SQL_CONCAT_EXCLUDE_PATH_PATTERN,
   },
   {
     id: "SL-SEC-018",
@@ -774,7 +778,7 @@ async function runPatternChecks({ rootPath, filePaths, maxFindings = MAX_FINDING
       }
     }
 
-    const sqlConcat = /\b(?:SELECT|INSERT|UPDATE|DELETE)\b[^\n]{0,160}\+/i.exec(text);
+    const sqlConcat = SQL_STRING_CONCATENATION_PATTERN.exec(text);
     if (
       sqlConcat &&
       findings.length < maxFindings &&

package/src/review/omargate-orchestrator.js

@@ -376,6 +376,79 @@ function summarizeFindings(findings = []) {
   };
 }
 
+function normalizeEvidenceNumber(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+function resolveAiResultCostUsd(result = {}) {
+  return Math.max(
+    normalizeEvidenceNumber(result?.costUsd),
+    normalizeEvidenceNumber(result?.usage?.costUsd),
+  );
+}
+
+function buildAiCallEvidence(result = {}, { dryRun = false } = {}) {
+  if (dryRun) {
+    return {
+      confirmedCalls: 0,
+      usageBackedCalls: 0,
+      ledgerBackedCalls: 0,
+      pricedCalls: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0,
+      providerCostUsd: 0,
+      customerCostUsd: 0,
+    };
+  }
+
+  const usage = result?.usage && typeof result.usage === "object" ? result.usage : {};
+  const ledger = result?.billing?.ok === true && result?.billing?.ledgerEntry
+    ? result.billing.ledgerEntry
+    : {};
+  const usageInputTokens = normalizeEvidenceNumber(usage.inputTokens);
+  const usageOutputTokens = normalizeEvidenceNumber(usage.outputTokens);
+  const usageTotalTokens = normalizeEvidenceNumber(usage.totalTokens);
+  const ledgerInputTokens = normalizeEvidenceNumber(ledger.inputTokens);
+  const ledgerOutputTokens = normalizeEvidenceNumber(ledger.outputTokens);
+  const ledgerTotalTokens = normalizeEvidenceNumber(ledger.totalTokens);
+  const inputTokens = Math.max(usageInputTokens, ledgerInputTokens);
+  const outputTokens = Math.max(usageOutputTokens, ledgerOutputTokens);
+  const totalTokens = Math.max(usageTotalTokens, ledgerTotalTokens, inputTokens + outputTokens);
+  const ledgerProviderCostUsd = normalizeEvidenceNumber(ledger.providerCostUsd);
+  const providerCostUsd = Math.max(resolveAiResultCostUsd(result), ledgerProviderCostUsd);
+  const customerCostUsd = normalizeEvidenceNumber(ledger.customerCostUsd);
+  const usageBacked = usageInputTokens + usageOutputTokens + usageTotalTokens > 0;
+  const ledgerBacked =
+    ledgerInputTokens + ledgerOutputTokens + ledgerTotalTokens > 0 || ledgerProviderCostUsd > 0;
+  const priced = providerCostUsd > 0 || customerCostUsd > 0;
+  const confirmed = usageBacked || ledgerBacked || priced;
+
+  return {
+    confirmedCalls: confirmed ? 1 : 0,
+    usageBackedCalls: usageBacked ? 1 : 0,
+    ledgerBackedCalls: ledgerBacked ? 1 : 0,
+    pricedCalls: priced ? 1 : 0,
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    providerCostUsd,
+    customerCostUsd,
+  };
+}
+
+function combineAiCallEvidence(entries = []) {
+  const combined = buildAiCallEvidence({}, { dryRun: true });
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    for (const key of Object.keys(combined)) {
+      combined[key] += normalizeEvidenceNumber(entry[key]);
+    }
+  }
+  return combined;
+}
+
 function buildPersonaHealthFindings(personaHealth = {}) {
   if (personaHealth.healthy || personaHealth.total <= 0) {
     return [];
@@ -386,13 +459,16 @@ function buildPersonaHealthFindings(personaHealth = {}) {
   const total = Number(personaHealth.total || 0);
   const errorRatio = Number(personaHealth.errorRatio || 0);
   const totalCostUsd = Number(personaHealth.totalCostUsd || 0);
+  const aiCallEvidence = personaHealth.aiCallEvidence || {};
+  const okCount = Number(personaHealth.ok || 0);
+  const unverifiedOkCount = Number(personaHealth.unverifiedOk || 0);
   const allPersonasFailed = total > 0 && errorCount === total;
   const severity = allPersonasFailed ? "P0" : "P1";
   let message = `Omar AI coverage degraded: ${errorCount}/${total} dispatched personas errored (${Math.round(errorRatio * 100)}%).`;
   if (allPersonasFailed) {
     message = `Omar AI coverage failed closed: all ${total} dispatched personas errored before producing findings.`;
-  } else if (errorCount === 0 && totalCostUsd <= 0) {
-    message = "Omar AI coverage failed closed: personas reported ok but total AI cost was $0.00, indicating no LLM calls were made.";
+  } else if (errorCount === 0 && unverifiedOkCount > 0) {
+    message = `Omar AI coverage failed closed: ${unverifiedOkCount}/${okCount} successful personas lacked token-bearing usage, billing-ledger, or priced-call evidence.`;
   }
 
   return [
@@ -417,6 +493,9 @@ function buildPersonaHealthFindings(personaHealth = {}) {
         total,
         errorRatio,
         totalCostUsd,
+        okCount,
+        unverifiedOkCount,
+        aiCallEvidence,
       },
     },
   ];
@@ -636,6 +715,8 @@ async function runOmarPersonaSwarm({
           });
           return normalized;
         });
+        const costUsd = resolveAiResultCostUsd(result);
+        const aiCallEvidence = buildAiCallEvidence(result, { dryRun });
 
         if (onEvent) {
           for (const finding of findings) {
@@ -659,11 +740,11 @@ async function runOmarPersonaSwarm({
               fileCount: scopedFiles.length,
               findings: findings.length,
               summary: result?.summary || summarizeFindings(findings),
-              costUsd: result?.usage?.costUsd || 0,
+              costUsd,
               durationMs: Date.now() - subagentStart,
             },
             usage: {
-              costUsd: result?.usage?.costUsd || 0,
+              costUsd,
               durationMs: Date.now() - subagentStart,
               toolCalls: result?.usage?.toolCalls || 0,
             },
@@ -678,7 +759,8 @@ async function runOmarPersonaSwarm({
           files: scopedFiles,
           findings,
           summary: result?.summary || summarizeFindings(findings),
-          costUsd: result?.usage?.costUsd || 0,
+          costUsd,
+          aiCallEvidence,
           model: result?.model || model || null,
           billing: result?.billing || null,
           artifacts: result?.artifacts || null,
@@ -739,6 +821,9 @@ async function runOmarPersonaSwarm({
   );
   const findings = settledSubagents.flatMap((result) => result.findings || []);
   const totalCostUsd = settledSubagents.reduce((sum, result) => sum + (result.costUsd || 0), 0);
+  const aiCallEvidence = combineAiCallEvidence(
+    settledSubagents.map((result) => result.aiCallEvidence),
+  );
   const summary = summarizeFindings(findings);
   const okCount = settledSubagents.filter((result) => result.status === "ok").length;
   const errorCount = settledSubagents.filter((result) => result.status === "error").length;
@@ -811,6 +896,7 @@ async function runOmarPersonaSwarm({
     findings,
     summary,
     costUsd: totalCostUsd,
+    aiCallEvidence,
     model: model || null,
     durationMs: Date.now() - startedAt,
     error: okCount > 0 ? null : settledSubagents.find((result) => result.error)?.error || null,
@@ -829,6 +915,7 @@ async function runOmarPersonaSwarm({
         files: result.files,
         findings: (result.findings || []).length,
         costUsd: result.costUsd || 0,
+        aiCallEvidence: result.aiCallEvidence || null,
         billing: result.billing || null,
         durationMs: result.durationMs || 0,
         error: result.error || null,
@@ -1142,6 +1229,8 @@ export async function runOmarGateOrchestrator({
         confidenceFloor: personaConfidenceFloor,
         personaConfidenceFloor,
       }));
+      const personaCost = resolveAiResultCostUsd(result);
+      const aiCallEvidence = buildAiCallEvidence(result, { dryRun });
 
       if (onEvent) {
         for (const finding of findings) {
@@ -1174,14 +1263,13 @@ export async function runOmarGateOrchestrator({
             identity,
             findings: findings.length,
             summary: result?.summary || {},
-            costUsd: result?.costUsd || 0,
+            costUsd: personaCost,
             durationMs: Date.now() - personaStart,
           },
           runId,
         }));
       }
 
-      const personaCost = result?.costUsd || 0;
       runningCostUsd += personaCost;
 
       return {
@@ -1190,6 +1278,7 @@ export async function runOmarGateOrchestrator({
         findings,
         summary: result?.summary || { P0: 0, P1: 0, P2: 0, P3: 0 },
         costUsd: personaCost,
+        aiCallEvidence,
         model: result?.model || model || null,
         billing: result?.billing || null,
         artifacts: result?.artifacts || null,
@@ -1269,28 +1358,35 @@ export async function runOmarGateOrchestrator({
   );
 
   const totalCost = settled.reduce((sum, r) => sum + (r.costUsd || 0), 0);
+  const aiCallEvidence = combineAiCallEvidence(settled.map((result) => result.aiCallEvidence));
   const totalDuration = Date.now() - startTime;
 
-  // Silent-failure detection: if >=50% of personas errored OR total cost is
-  // zero with non-zero personas dispatched, treat as a LOUD orchestrator
-  // warning. Prior behavior silently returned zero AI findings, masking
-  // auth failures or LLM proxy outages as "clean scan".
+  // Silent-failure detection requires evidence of an actual provider call.
+  // Customer cost is not evidence by itself because internal/zero-priced
+  // billing can still carry token-bearing usage and provider-cost receipts.
   const personaErrorCount = settled.filter((r) => r.status === "error").length;
   const personaSkippedCount = settled.filter((r) => r.status === "skipped").length;
   const personaOkCount = settled.filter((r) => r.status === "ok").length;
+  const personaVerifiedOkCount = settled.filter(
+    (r) => r.status === "ok" && Number(r.aiCallEvidence?.confirmedCalls || 0) > 0
+  ).length;
+  const personaUnverifiedOkCount = personaOkCount - personaVerifiedOkCount;
   const totalPersonas = settled.length;
   const errorRatio = totalPersonas > 0 ? personaErrorCount / totalPersonas : 0;
   const aiCoverageHealthy =
     totalPersonas === 0 ||
-    (personaOkCount > 0 && totalCost > 0 && errorRatio < 0.5 && !dryRun);
+    (personaOkCount > 0 && personaUnverifiedOkCount === 0 && errorRatio < 0.5 && !dryRun);
 
   const personaHealth = {
     ok: personaOkCount,
     error: personaErrorCount,
     skipped: personaSkippedCount,
     total: totalPersonas,
+    verifiedOk: personaVerifiedOkCount,
+    unverifiedOk: personaUnverifiedOkCount,
     errorRatio,
     totalCostUsd: totalCost,
+    aiCallEvidence,
     healthy: aiCoverageHealthy || dryRun,
     warnings: [],
   };
@@ -1304,9 +1400,9 @@ export async function runOmarGateOrchestrator({
         `${personaErrorCount}/${totalPersonas} personas errored (${Math.round(errorRatio * 100)}%). AI coverage is degraded.`
       );
     }
-    if (personaOkCount > 0 && totalCost <= 0) {
+    if (personaUnverifiedOkCount > 0) {
       personaHealth.warnings.push(
-        `Personas reported ok status but totalCost=$0.00 — likely silently returned empty findings without making LLM calls.`
+        `${personaUnverifiedOkCount}/${personaOkCount} successful personas lacked token-bearing usage, billing-ledger, or priced-call evidence.`
       );
     }
   }
@@ -1330,6 +1426,7 @@ export async function runOmarGateOrchestrator({
       findings: (r.findings || []).length,
       summary: r.summary || { P0: 0, P1: 0, P2: 0, P3: 0 },
       costUsd: r.costUsd,
+      aiCallEvidence: r.aiCallEvidence || null,
       durationMs: r.durationMs,
       model: r.model || null,
       billing: r.billing || null,

package/src/review/spec-binding.js

@@ -201,6 +201,19 @@ function tokenizePath(relativePath) {
   return [...tokens];
 }
 
+function specMentionsExactPath(markdown, relativePath) {
+  const normalizedPath = toPosixPath(relativePath).toLowerCase().replace(/^\.\/+/, "");
+  if (!normalizedPath) {
+    return false;
+  }
+  const escapedPath = normalizedPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const normalizedMarkdown = toPosixPath(markdown).toLowerCase();
+  return new RegExp(
+    `(^|[^a-z0-9._/-])(?:\\./)?${escapedPath}(?=$|[^a-z0-9._/-])`,
+    "m"
+  ).test(normalizedMarkdown);
+}
+
 function isSourceFile(relativePath) {
   return SOURCE_EXTENSIONS.has(path.extname(String(relativePath || "")).toLowerCase());
 }
@@ -393,7 +406,9 @@ export async function runSpecBindingChecks({
       tokenMatchesByPath.set(relativePath, true);
       continue;
     }
-    const tokenMatches = tokenizePath(relativePath).some((token) => normalizedSpecText.includes(token));
+    const tokenMatches =
+      specMentionsExactPath(spec.markdown, relativePath) ||
+      tokenizePath(relativePath).some((token) => normalizedSpecText.includes(token));
     tokenMatchesByPath.set(relativePath, tokenMatches);
     if (evaluateScopeDrift && !tokenMatches) {
       pushFinding(

package/src/scan/generator.js

@@ -2,7 +2,7 @@ import YAML from "yaml";
 
 export const DEFAULT_SCAN_WORKFLOW_PATH = ".github/workflows/omar-gate.yml";
 export const DEFAULT_SCAN_SECRET_NAME = "SENTINELAYER_TOKEN";
-export const SENTINELAYER_ACTION_REF = "mrrCarter/sentinelayer-v1-action@a496be33a466c0cc3f8616d66bbd7d78f7d3c31d";
+export const SENTINELAYER_ACTION_REF = "mrrCarter/sentinelayer-v1-action@8afb7dbb42a5e1c25233d422c4cabe401ba02380";
 export const SUPPORTED_E2E_HINTS = Object.freeze(["auto", "yes", "no"]);
 export const SUPPORTED_PLAYWRIGHT_MODES = Object.freeze(["auto", "off", "baseline", "audit"]);
 

package/src/session/agent-registry.js

@@ -4,16 +4,14 @@ import path from "node:path";
 import process from "node:process";
 
 import { STUCK_THRESHOLDS } from "../agents/jules/pulse.js";
-import { createAgentEvent } from "../events/schema.js";
 import { inferSessionAgentIdentity } from "./agent-identity.js";
 import { resolveSessionPaths } from "./paths.js";
-import { emitContextBriefing } from "./recap.js";
+import { buildContextBriefing } from "./recap.js";
 import {
   assignFriendlyName,
   buildSentiWelcome,
   shouldAutoRenameInRegistry,
 } from "./senti-naming.js";
-import { appendToStream } from "./stream.js";
 
 const AGENT_SNAPSHOT_SCHEMA_VERSION = "1.0.0";
 
@@ -177,28 +175,6 @@ async function writeAgentSnapshot(snapshotPath, snapshot) {
   }
 }
 
-async function emitAgentEvent(
-  sessionId,
-  event,
-  payload,
-  { targetPath = process.cwd(), awaitRemoteSync = false } = {}
-) {
-  const envelope = createAgentEvent({
-    event,
-    agent: {
-      id: payload.agentId,
-      model: payload.model,
-      displayName: payload.displayName,
-      provider: payload.provider,
-      role: payload.role,
-      clientKind: payload.clientKind,
-    },
-    sessionId,
-    payload,
-  });
-  await appendToStream(sessionId, envelope, { targetPath, awaitRemoteSync });
-}
-
 function buildAgentSnapshotPath(paths, agentId) {
   const normalizedAgentId = normalizeString(agentId);
   if (!normalizedAgentId) {
@@ -288,17 +264,15 @@ function _untrackLocalAgent(sessionId, agentId) {
   _localAgents.delete(_agentKey(sessionId, agentId));
 }
 
-async function _emitLeaveForAllLocalAgents(reason) {
+async function _leaveAllLocalAgents(reason) {
   const entries = [..._localAgents.values()];
   _localAgents.clear();
   for (const entry of entries) {
     try {
-      await emitAgentEvent(
-        entry.sessionId,
-        "agent_leave",
-        { agentId: entry.agentId, reason, model: "unknown", role: "participant" },
-        { targetPath: entry.targetPath },
-      );
+      await unregisterAgent(entry.sessionId, entry.agentId, {
+        reason,
+        targetPath: entry.targetPath,
+      });
     } catch {
       // Best-effort: a stuck filesystem or network shouldn't block exit.
     }
@@ -309,7 +283,7 @@ function _ensureExitHooksInstalled() {
   if (_exitHooksInstalled) return;
   _exitHooksInstalled = true;
   const onSignal = (signal) => {
-    void _emitLeaveForAllLocalAgents("manual").finally(() => {
+    void _leaveAllLocalAgents("manual").finally(() => {
       process.removeListener(signal, onSignal);
       process.kill(process.pid, signal);
     });
@@ -317,7 +291,7 @@ function _ensureExitHooksInstalled() {
   process.on("SIGINT", onSignal);
   process.on("SIGTERM", onSignal);
   process.on("beforeExit", () => {
-    void _emitLeaveForAllLocalAgents("manual");
+    void _leaveAllLocalAgents("manual");
   });
 }
 
@@ -332,7 +306,6 @@ export async function registerAgent(
     role = "observer",
     targetPath = process.cwd(),
     trackProcessExit = true,
-    awaitRemoteSync = false,
   } = {}
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
@@ -426,46 +399,39 @@ export async function registerAgent(
   );
 
   await writeAgentSnapshot(snapshotPath, snapshot);
-  await emitAgentEvent(paths.sessionId, "agent_join", {
-    agentId: snapshot.agentId,
-    model: snapshot.model,
-    displayName: snapshot.displayName,
-    provider: snapshot.provider,
-    clientKind: snapshot.clientKind,
-    role: snapshot.role,
-    status: snapshot.status,
-  }, { targetPath, awaitRemoteSync });
   if (trackProcessExit) {
     _trackLocalAgent(paths.sessionId, snapshot.agentId, targetPath);
   }
 
+  let welcome = null;
   if (renamedFrom) {
-    const welcome = buildSentiWelcome({
+    welcome = buildSentiWelcome({
       agentId: snapshot.agentId,
       model: snapshot.model,
       role: snapshot.role,
       wasAnonymous: true,
       originalAgentId: renamedFrom,
     });
-    await emitAgentEvent(paths.sessionId, "agent_identified", {
-      ...welcome,
-      sessionId: paths.sessionId,
-    }, { targetPath });
   }
 
+  let contextBriefing = null;
   if (normalizeString(snapshot.agentId).toLowerCase() !== "senti") {
-    await emitContextBriefing(paths.sessionId, {
+    contextBriefing = await buildContextBriefing(paths.sessionId, {
       forAgentId: snapshot.agentId,
       targetPath,
-      awaitRemoteSync,
     }).catch(() => {});
   }
 
   return {
     ...snapshot,
     snapshotPath,
-    emittedJoinEvent: true,
-    emittedContextBriefing: normalizeString(snapshot.agentId).toLowerCase() !== "senti",
+    emittedJoinEvent: false,
+    emittedContextBriefing: false,
+    returnedContextBriefing: Boolean(contextBriefing),
+    onboarding: {
+      welcome,
+      contextBriefing,
+    },
     refreshedExistingAgent: false,
   };
 }
@@ -607,16 +573,9 @@ export async function unregisterAgent(
   );
 
   await writeAgentSnapshot(snapshotPath, snapshot);
-  await emitAgentEvent(paths.sessionId, "agent_leave", {
-    agentId: snapshot.agentId,
-    reason: normalizedReason,
-    role: snapshot.role,
-    model: snapshot.model,
-    displayName: snapshot.displayName,
-    provider: snapshot.provider,
-    clientKind: snapshot.clientKind,
-  }, { targetPath });
-  // Already left explicitly — don't double-emit on process exit.
+  // Presence and roster state are projections, not transcript events. The
+  // snapshot is authoritative for this workspace; remote listener presence is
+  // renewed through the TTL endpoint.
   _untrackLocalAgent(paths.sessionId, snapshot.agentId);
 
   return {