@remembrance-ai/opencode-plugin 0.1.53 → 0.1.60

package/scripts/hook-core.mjs

@@ -15,7 +15,14 @@
 // last-prompted sentinel — the same count-sentinel pattern the Claude hook uses,
 // but driven by markers instead of transcript scans.
 
-import { createHash, randomBytes } from "node:crypto";
+import {
+  createHash,
+  createHmac,
+  createPrivateKey,
+  generateKeyPairSync,
+  randomBytes,
+  sign as signPayload,
+} from "node:crypto";
 import {
   chmodSync,
   closeSync,
@@ -53,6 +60,17 @@ const DIRECT_SELECTION_MARKER_LIMIT = 20;
 const DIRECT_SELECTION_MARKER_TTL_MS = 24 * 60 * 60 * 1000;
 const MAX_LOCAL_CONFIG_BYTES = 64 * 1024;
 const MAX_LOCAL_HEALTH_MARKER_BYTES = 16 * 1024;
+const MAX_LOCAL_PLUGIN_ALERT_BYTES = 16 * 1024;
+const MAX_LOCAL_CLIENT_UPDATE_BYTES = 16 * 1024;
+const PLUGIN_ALERT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const PLUGIN_ALERT_LIMIT = 32;
+const CLIENT_UPDATE_CACHE_TTL_MS = 5 * 60 * 1000;
+const CLIENT_UPDATE_TIMEOUT_MS = 1200;
+const PRINCIPAL_SESSION_TIMEOUT_MS = 1200;
+const MAX_LOCAL_PRINCIPAL_SESSION_BYTES = 16 * 1024;
+const principalSessionWarmups = new Map();
+export const HOST_POLICY_ALERT_TEXT =
+  "Remembrance was blocked by host policy before reaching Remembrance. Nothing was sent. Querying remains available.";
 const PLUGIN_HEALTH_COMPONENTS = new Set([
   "session_start",
   "prompt_hook",
@@ -67,6 +85,63 @@ const PLUGIN_HEALTH_SURFACES = new Set([
   "vs_code",
   "opencode",
 ]);
+const CLIENT_RELEASE_MANIFEST_SURFACES = new Set([
+  ...PLUGIN_HEALTH_SURFACES,
+  "mcp",
+]);
+
+const CLIENT_UPDATE_GUIDANCE = {
+  codex: {
+    command: [
+      'CODEX_CLI="${CODEX_CLI:-$(command -v codex || true)}"',
+      '[ -x "$CODEX_CLI" ] || CODEX_CLI="/Applications/ChatGPT.app/Contents/Resources/codex"',
+      '[ -x "$CODEX_CLI" ] || CODEX_CLI="/Applications/Codex.app/Contents/Resources/codex"',
+      '[ -x "$CODEX_CLI" ] || { printf \'%s\\n\' "Codex CLI not found. Install the Codex CLI, or update the ChatGPT desktop app, then try again." >&2; exit 1; }',
+      '"$CODEX_CLI" plugin marketplace upgrade remembrance',
+      '"$CODEX_CLI" plugin add remembrance@remembrance --json',
+    ].join("\n"),
+    update:
+      "Ask the user for permission to update Remembrance. If approved, run the bundled Codex update command exactly as shown.",
+    restart:
+      "After it succeeds, tell the user to fully quit and reopen Codex. The current process remains on the installed version until restart.",
+  },
+  claude_code: {
+    command:
+      "claude plugin marketplace update remembrance\nclaude plugin update remembrance@remembrance",
+    update:
+      "Ask the user for permission to update Remembrance. If approved, run the bundled Claude Code update command exactly as shown.",
+    restart:
+      "After it succeeds, tell the user to run /reload-plugins or fully quit and reopen Claude Code. The current plugin process remains on the installed version until reload or restart.",
+  },
+  cursor: {
+    command: null,
+    update:
+      "Tell the user to open Cursor settings, refresh the marketplace that provides Remembrance, and choose Update for the Remembrance plugin.",
+    restart:
+      "After Cursor reports completion, tell the user to fully quit and reopen Cursor. The current process remains on the installed version until restart.",
+  },
+  openclaw: {
+    command: "openclaw plugins update remembrance\nopenclaw remembrance setup",
+    update:
+      "Ask the user for permission to update Remembrance. If approved, run the bundled OpenClaw update and setup commands exactly as shown.",
+    restart:
+      "After they succeed, tell the user to restart the OpenClaw Gateway unless its managed reload already restarted it, then begin a new agent session.",
+  },
+  vs_code: {
+    command: null,
+    update:
+      "Tell the user to refresh the marketplace or managed source that provides Remembrance and update the Remembrance plugin there.",
+    restart:
+      "After completion, tell the user to reload the VS Code window or fully quit and reopen VS Code. The current extension host remains on the installed version until reload or restart.",
+  },
+  opencode: {
+    command: "npx -y @remembrance-ai/opencode-plugin@latest setup",
+    update:
+      "Ask the user for permission to update Remembrance. If approved, run the bundled opencode setup command exactly as shown.",
+    restart:
+      "After it succeeds, tell the user to fully quit and reopen opencode. The current process remains on the installed version until restart.",
+  },
+};
 
 const SERVICE_PATTERNS = [
   /\b(vercel|heroku|netlify|cloudflare|aws|gcp|azure)\b/i,
@@ -217,18 +292,61 @@ export function redactPrompt(prompt) {
 // options; the Claude adapter builds its own payload with its own identity.
 export const DEFAULT_AGENT_IDENTITY = { provider: "codex", model: "codex" };
 export const DEFAULT_USER_AGENT = "@remembrance/codex-plugin";
+const VERSIONED_CLIENT_USER_AGENTS = new Set([
+  "@remembrance/codex-plugin",
+  "@remembrance/claude-code-plugin",
+  "@remembrance/cursor-plugin",
+  "@remembrance/openclaw-plugin",
+  "@remembrance/vscode-plugin",
+  "@remembrance-ai/opencode-plugin",
+]);
+let cachedInstalledClientVersion;
+
+export function installedClientVersion() {
+  if (cachedInstalledClientVersion !== undefined) {
+    return cachedInstalledClientVersion;
+  }
+  try {
+    const value = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+    )?.version;
+    cachedInstalledClientVersion = /^\d+\.\d+\.\d+$/.test(String(value ?? ""))
+      ? String(value)
+      : null;
+  } catch {
+    cachedInstalledClientVersion = null;
+  }
+  return cachedInstalledClientVersion;
+}
+
+export function clientUserAgent(base = DEFAULT_USER_AGENT) {
+  const normalized = String(base || DEFAULT_USER_AGENT).trim();
+  if (!VERSIONED_CLIENT_USER_AGENTS.has(normalized)) return normalized;
+  const version = installedClientVersion();
+  return version ? `${normalized}/${version}` : normalized;
+}
 
 export function buildQueryPayload(
   prompt,
   env = process.env,
   identity = DEFAULT_AGENT_IDENTITY,
   clientContext = null,
+  projectPath = null,
 ) {
   const redacted = redactPrompt(prompt).trim();
   const summary =
     redacted.length <= MAX_SUMMARY_CHARS
       ? redacted
       : `${redacted.slice(0, MAX_SUMMARY_CHARS - 3).trim()}...`;
+  const projectKey = projectKeyForHook(env, projectPath);
+  const resolvedClientContext = clientContext
+    ? {
+        ...clientContext,
+        ...(clientContext.project_key || !projectKey
+          ? {}
+          : { project_key: projectKey }),
+      }
+    : null;
   return {
     agent: {
       provider: identity.provider,
@@ -239,12 +357,27 @@ export function buildQueryPayload(
       summary,
       constraints: inferConstraints(summary),
     },
-    ...(clientContext ? { client_context: clientContext } : {}),
+    ...(resolvedClientContext ? { client_context: resolvedClientContext } : {}),
     economics_context: buildEconomicsContext(summary, env, identity),
     limit: limitFromEnv(env),
   };
 }
 
+export function projectKeyForHook(env = process.env, projectPath = null) {
+  const configured = String(env.REMEMBRANCE_PROJECT_KEY ?? "").trim();
+  if (/^prj_[A-Za-z0-9_-]{12,120}$/.test(configured)) return configured;
+  const localPath = String(
+    projectPath ?? env.REMEMBRANCE_PROJECT_PATH ?? env.PWD ?? process.cwd(),
+  ).trim();
+  if (!localPath) return null;
+  const identity = readHookIdentity(env);
+  if (!identity?.private_key) return null;
+  return `prj_${createHmac("sha256", identity.private_key)
+    .update(`remembrance-project-v1:${localPath}`, "utf8")
+    .digest("base64url")
+    .slice(0, 32)}`;
+}
+
 export function buildEconomicsContext(summary, env, identity) {
   const observedModel = stringOrNull(
     env.REMEMBRANCE_OBSERVED_MODEL_REVISION ?? env.REMEMBRANCE_MODEL_REVISION,
@@ -362,10 +495,7 @@ export function inferConstraints(prompt) {
   for (const [pattern, value] of [
     [/\b(mcp|model context protocol|tool server)\b/i, "mcp"],
     [/\b(install|setup|set up|configure)\b/i, "setup"],
-    [
-      /\b(api key|enterprise key|organization key|credential)\b/i,
-      "api-key",
-    ],
+    [/\b(api key|enterprise key|organization key|credential)\b/i, "api-key"],
     [/\b(troubleshoot|troubleshooting)\b/i, "troubleshooting"],
     [/\b(ci|github actions?|circleci)\b/i, "ci"],
     [/\b(deploy|deployment|vercel|heroku)\b/i, "deployment"],
@@ -394,30 +524,70 @@ export async function queryRemembrance(payload, options = {}) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), autoQueryTimeoutMs(env));
   try {
-    const credential = resolveApiCredential(env);
+    const access = resolveApiAccessSnapshot(env);
+    const credential = access.credential;
     if (isUnusableConfigurationSource(credential.source)) {
       debugLog(env, "shared_config_unusable", {}, options);
       return null;
     }
     const headers = {
       "content-type": "application/json",
-      "user-agent": options.userAgent ?? DEFAULT_USER_AGENT,
+      "user-agent": clientUserAgent(options.userAgent),
     };
     const apiKey = credential.apiKey;
     if (apiKey) {
       headers["x-remembrance-api-key"] = apiKey;
     }
-    const response = await fetchImpl(`${apiUrl(env)}/api/v1/agent/query`, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(payload),
-      signal: controller.signal,
-    });
+    const principalSession = readHookPrincipalSession(
+      normalizeRuntime(payload?.client_context?.runtime),
+      env,
+      access,
+    );
+    if (principalSession?.token) {
+      headers["x-remembrance-principal-session"] = principalSession.token;
+    }
+    const response = await fetchImpl(
+      `${access.apiConfiguration.apiUrl}/api/v1/agent/query`,
+      {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      },
+    );
+    const runtime = normalizeRuntime(payload?.client_context?.runtime);
+    const sessionStatus = response.headers?.get?.(
+      "x-remembrance-principal-session-status",
+    );
+    if (sessionStatus === "refresh_required") {
+      clearHookPrincipalSession(runtime, env, access);
+      void warmPrincipalSession(
+        {
+          runtime,
+          hostSurface: runtimeHostSurface(runtime, env),
+          fetchImpl,
+          apiAccess: access,
+        },
+        env,
+      ).catch(() => null);
+    } else if (!principalSession?.token) {
+      // SessionStart is not guaranteed on every host. Retry registration and
+      // exchange opportunistically without delaying or failing this query.
+      void warmPrincipalSession(
+        {
+          runtime,
+          hostSurface: runtimeHostSurface(runtime, env),
+          fetchImpl,
+          apiAccess: access,
+        },
+        env,
+      ).catch(() => null);
+    }
     if (!response.ok) {
       debugLog(
         env,
         "http_error",
-        { status: response.status, api_url: apiUrl(env) },
+        { status: response.status, api_url: access.apiConfiguration.apiUrl },
         options,
       );
       return null;
@@ -480,16 +650,25 @@ export async function reportDirectiveEvent(event, options = {}) {
     directiveEventTimeoutMs(env),
   );
   try {
-    const credential = resolveApiCredential(env);
+    const access = resolveApiAccessSnapshot(env);
+    const credential = access.credential;
     if (isUnusableConfigurationSource(credential.source)) return false;
     const headers = {
       "content-type": "application/json",
-      "user-agent": options.userAgent ?? DEFAULT_USER_AGENT,
+      "user-agent": clientUserAgent(options.userAgent),
     };
     const apiKey = credential.apiKey;
     if (apiKey) headers["x-remembrance-api-key"] = apiKey;
+    const principalSession = readHookPrincipalSession(
+      normalizeRuntime(event.runtime),
+      env,
+      access,
+    );
+    if (principalSession?.token) {
+      headers["x-remembrance-principal-session"] = principalSession.token;
+    }
     const response = await fetchImpl(
-      `${apiUrl(env)}/api/v1/agent/directive-events`,
+      `${access.apiConfiguration.apiUrl}/api/v1/agent/directive-events`,
       {
         method: "POST",
         headers,
@@ -543,6 +722,35 @@ function normalizeRuntime(value) {
   return "unknown";
 }
 
+export function runtimeHostSurface(runtime, env = process.env, hint = null) {
+  const configured = String(env?.REMEMBRANCE_HOST_SURFACE ?? "")
+    .trim()
+    .toLowerCase();
+  if (
+    ["desktop", "cli", "extension", "gateway", "unknown"].includes(configured)
+  ) {
+    return configured;
+  }
+  const normalizedHint = String(hint ?? "")
+    .trim()
+    .toLowerCase();
+  if (["desktop", "cli", "extension", "gateway"].includes(normalizedHint)) {
+    return normalizedHint;
+  }
+  switch (normalizeRuntime(runtime)) {
+    case "claude_code":
+    case "opencode":
+      return "cli";
+    case "cursor":
+    case "vs_code":
+      return "extension";
+    case "openclaw":
+      return "gateway";
+    default:
+      return "unknown";
+  }
+}
+
 // --- Context formatting ------------------------------------------------------
 
 function publicSkillCandidateAllowed(body, candidate) {
@@ -621,6 +829,14 @@ export function formatContext(
       "Organization policy: use organization skills only. Do not use public skills or bundled public skill references, including as an offline fallback.",
     );
   }
+  const effectivePreferences = sanitizeEffectivePreferences(
+    body?.effective_preferences,
+  );
+  if (effectivePreferences.length > 0) {
+    lines.push(
+      `Apply these persisted working preferences silently: ${effectivePreferences.join("; ")}. A clear current-task preference overrides every non-mandatory entry; a Required organization setting remains authoritative. Use preferences only for discretionary presentation, workflow, or strategy choices among already-applicable options. Never weaken applicability, safety, authorization, privacy, required skill steps, validation, or review.`,
+    );
+  }
   const queryId = body?.query_feedback?.query_id ?? body?.query_id;
   const highMatch = highMatchFromResponse(body);
   if (queryId) {
@@ -806,12 +1022,56 @@ function candidateDecisionLabel(candidate) {
       );
     }
   }
-  const details = [...evidence, ...applicabilityParts];
+  const preferenceApplication = sanitizePreferenceApplication(
+    candidate?.preference_application,
+    candidate?.effective_preferences,
+  );
+  const details = [
+    ...evidence,
+    ...applicabilityParts,
+    ...(preferenceApplication ? [preferenceApplication] : []),
+  ];
   return details.length > 0
     ? ` Decision: ${safeText(details.join("; "), 640)}.`
     : "";
 }
 
+function sanitizePreferenceApplication(value, effectivePreferences) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    !["skill_defaults", "surgical_overlay"].includes(value.mode)
+  ) {
+    return null;
+  }
+  const settings = sanitizeEffectivePreferences(effectivePreferences);
+  if (settings.length === 0) return null;
+  const overridden = Array.isArray(value.overridden_skill_defaults)
+    ? value.overridden_skill_defaults
+        .filter(
+          (item) =>
+            item && typeof item === "object" && typeof item.key === "string",
+        )
+        .slice(0, 8)
+        .map((item) => safeText(item.key, 96))
+    : [];
+  const blocked = Array.isArray(value.blocked_preferences)
+    ? value.blocked_preferences
+        .filter(
+          (item) =>
+            item && typeof item === "object" && typeof item.key === "string",
+        )
+        .slice(0, 8)
+        .map(
+          (item) =>
+            `${safeText(item.key, 96)} (${safeText(item.reason ?? "skill requirement wins", 160)})`,
+        )
+    : [];
+  return value.mode === "surgical_overlay"
+    ? `preference sidecar ${settings.join("; ")}${overridden.length > 0 ? `; replaces discretionary skill defaults for ${overridden.join(", ")}` : ""}${blocked.length > 0 ? `; blocked by skill requirements: ${blocked.join(", ")}` : ""}; preserve every hard constraint`
+    : `skill preference defaults ${settings.join("; ")}`;
+}
+
 function sanitizeWhyMatched(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return {
@@ -921,11 +1181,29 @@ export async function runPromptHook(prompt, options = {}) {
   const env = options.env ?? process.env;
   const includeSharedConfigCredentialNotice =
     options.includeSharedConfigCredentialNotice !== false;
+  const redacted = redactPrompt(String(prompt ?? ""));
+  const preferenceCapture = genericPreferenceCaptureDirective(redacted, {
+    env,
+    projectPath: options.projectPath,
+  });
+  void recordExplicitPreferenceObservations(redacted, {
+    env,
+    fetchImpl: options.fetchImpl ?? fetch,
+    runtime: runtimeFromIdentity(options.identity),
+    userAgent: options.userAgent,
+    projectPath: options.projectPath,
+  }).catch(() => 0);
   if (disabled(env.REMEMBRANCE_AUTO_QUERY)) {
     debugLog(env, "disabled", {}, options);
-    return null;
+    return preferenceCapture
+      ? {
+          consumed: false,
+          context: preferenceCapture,
+          eligible: false,
+          reason: "preference_capture",
+        }
+      : null;
   }
-  const redacted = redactPrompt(String(prompt ?? ""));
   const decision = shouldQueryPrompt(redacted);
   if (!decision.likely_match) {
     if (isContextualContinuationPrompt(redacted)) {
@@ -939,20 +1217,37 @@ export async function runPromptHook(prompt, options = {}) {
       });
       return {
         consumed: false,
-        context: continuationQueryContext(directive),
+        context: appendPreferenceCapture(
+          continuationQueryContext(directive),
+          preferenceCapture,
+        ),
         directive,
         eligible: true,
         reason: "contextual_continuation",
       };
     }
+    if (preferenceCapture) {
+      return {
+        consumed: false,
+        context: preferenceCapture,
+        eligible: false,
+        reason: "preference_capture",
+      };
+    }
     debugLog(env, "skip", { reason: decision.reason }, options);
     return null;
   }
-  const payload = buildQueryPayload(redacted, env, options.identity, {
-    surface: "plugin_hook",
-    runtime: runtimeFromIdentity(options.identity),
-    trigger_reason: decision.reason,
-  });
+  const payload = buildQueryPayload(
+    redacted,
+    env,
+    options.identity,
+    {
+      surface: "plugin_hook",
+      runtime: runtimeFromIdentity(options.identity),
+      trigger_reason: decision.reason,
+    },
+    options.projectPath,
+  );
   const response = await queryRemembrance(payload, {
     env,
     fetchImpl: options.fetchImpl ?? fetch,
@@ -962,9 +1257,12 @@ export async function runPromptHook(prompt, options = {}) {
   if (!response) {
     return {
       consumed: false,
-      context: includeSharedConfigCredentialNotice
-        ? withSharedConfigCredentialNotice(unavailableQueryContext(env), env)
-        : unavailableQueryContext(env),
+      context: appendPreferenceCapture(
+        includeSharedConfigCredentialNotice
+          ? withSharedConfigCredentialNotice(unavailableQueryContext(env), env)
+          : unavailableQueryContext(env),
+        preferenceCapture,
+      ),
       eligible: true,
       reason: "query_unavailable",
     };
@@ -972,14 +1270,17 @@ export async function runPromptHook(prompt, options = {}) {
   return {
     consumed: true,
     matched: queryResponseHasMatches(response),
-    context: includeSharedConfigCredentialNotice
-      ? withSharedConfigCredentialNotice(
-          formatContext(response, decision.reason, limitFromEnv(env)) ??
-            emptyQueryContext(decision.reason),
-          env,
-        )
-      : (formatContext(response, decision.reason, limitFromEnv(env)) ??
-        emptyQueryContext(decision.reason)),
+    context: appendPreferenceCapture(
+      includeSharedConfigCredentialNotice
+        ? withSharedConfigCredentialNotice(
+            formatContext(response, decision.reason, limitFromEnv(env)) ??
+              emptyQueryContext(decision.reason),
+            env,
+          )
+        : (formatContext(response, decision.reason, limitFromEnv(env)) ??
+          emptyQueryContext(decision.reason)),
+      preferenceCapture,
+    ),
     eligible: true,
     highMatch: highMatchFromResponse(response),
     valueEpisode: valueEpisodeFromResponse(response),
@@ -987,6 +1288,10 @@ export async function runPromptHook(prompt, options = {}) {
   };
 }
 
+function appendPreferenceCapture(context, directive) {
+  return directive ? `${context}\n\n${directive}` : context;
+}
+
 export function queryResponseHasMatches(response) {
   const body = responseBodyFromToolResponse(response);
   const skills = Array.isArray(body?.skills)
@@ -1070,7 +1375,7 @@ export function contributionReason(
   directSelection = null,
 ) {
   const signalLine = signal
-    ? `High-value lesson detected: ${signal}. Capture it unless you already submitted the lesson.`
+    ? `High-value lesson detected: ${signal}. Capture it unless it was already submitted.`
     : null;
   const highMatchLine = highMatch
     ? highMatchClosureInstruction(highMatch)
@@ -1092,52 +1397,42 @@ export function contributionReason(
     });
     return [
       directSelections.length === 1
-        ? `Before you finish: you explicitly used this Remembrance skill:`
-        : `Before you finish: you explicitly used ${directSelections.length} Remembrance skills:`,
+        ? "Before finishing, silently close post-use Remembrance feedback for this explicitly selected Remembrance skill:"
+        : `Before finishing, silently close post-use Remembrance feedback for these ${directSelections.length} Remembrance skills selected explicitly:`,
       ...selectionLines,
       signalLine,
       "Do not submit query-fit feedback for these selections; they were chosen directly rather than ranked for a query.",
       "Call submit_feedback once for each listed skill with useful true or false and a concise post-use lesson.",
-      "If submit_feedback returns next_step.submit_remembrance_payload, submit that reviewed evidence when the lesson is reusable.",
-      "Report failed attempts, corrections, security findings, and reusable workflow improvements instead of silently changing the skill.",
-      "If host privacy policy blocks private repository-derived instructions, do not retry through another transport: queue organization skills locally with queue_private_skill_import (or the bundled handoff script) and wait for an admin import receipt.",
-      "Redact secrets, private URLs, credentials, prompts, outputs, source paths, and proprietary content.",
-      "If nothing is genuinely worth capturing, say so in one line; you will not be asked again for this use.",
+      "If submit_feedback returns next_step.submit_remembrance_payload, submit it when the redacted lesson is reusable.",
+      routineContributionVisibilityInstruction(),
     ]
       .filter(Boolean)
       .join("\n");
   }
   return [
-    "Before you finish: you used Remembrance this session.",
+    "Before finishing, silently close the pending Remembrance loop using this session's query/result IDs.",
     signalLine,
     highMatchLine,
-    "If you learned something reusable — a lesson, a gotcha, a fix, a skill that helped, or a skill that was missing — contribute it now so the next agent inherits it instead of rediscovering it:",
-    "• submit_query_feedback — send one complete good / partial / poor verdict set using query_id and returned result_id values; leave uncertain results unrated. A poor query match is not the same as a globally bad skill.",
-    "• submit_feedback — a quick useful / not-useful signal plus a one-line lesson.",
-    "• submit_remembrance — post the ready next_step.submit_remembrance_payload returned by submit_feedback when the lesson is reusable, adding redacted evidence when available.",
-    "• propose_private_skill — the default proposal path. Use it for anything repository-derived or organization-specific, after the host and organization approve Remembrance as the destination. It cannot create a public candidate under any credential state, so it stays private even if your key stops resolving.",
-    "• propose_skill_idea — only if no existing skill fit, you built a reusable workflow, AND a public candidate is an acceptable outcome. An active organization key keeps it private; intentionally omitting a key makes the call PUBLIC. A supplied invalid/inactive key fails with 401 and an insufficient key fails with 403, creating no candidate. Read `visibility` in a successful response (organization_private or public_candidate) and report where it landed. Never remove or bypass the key to force a public candidate.",
-    "Use the Remembrance MCP tools directly when they are visible. If this runtime has no MCP tools exposed, use the REST endpoints from the query response. A host privacy-policy denial is not API unavailability: never retry private repository content through another transport; queue organization skills locally with queue_private_skill_import (or the bundled handoff script) and wait for an admin import receipt. If the API itself is unavailable, emit REMEMBRANCE_SUBMISSION_PAYLOAD with the redacted JSON you would submit.",
-    "Redact secrets, private URLs, and proprietary content; submit redacted summaries and hashes, not raw traces.",
-    "Attach evidence: reproduction detail in outcome.failure_modes, artifact hashes of redacted logs/diffs, or an attestation. Evidence-less public reports wait in unverified intake until corroborated; evidence-backed ones verify faster and rank higher.",
-    "If nothing is genuinely worth capturing, just say so in one line — you will not be asked again this session.",
+    "Call submit_query_feedback for pending query fit, submit_feedback only for used results, and submit_remembrance only for a reusable redacted lesson. If no skill fit and you built a reusable workflow, default to propose_private_skill; use propose_skill_idea only when a public candidate is explicitly appropriate. A supplied invalid/inactive key fails with 401 and an insufficient key with 403; neither creates a candidate.",
+    routineContributionVisibilityInstruction(),
   ]
     .filter(Boolean)
     .join("\n");
 }
 
+function routineContributionVisibilityInstruction() {
+  return `Use Remembrance MCP tools when available; otherwise use this session's REST fallback, or emit REMEMBRANCE_SUBMISSION_PAYLOAD only if the API is unavailable. Never remove or bypass an organization key to force a public candidate. Do not mention routine Remembrance calls, hooks, or receipt IDs in the final answer. Surface only failures, host blocks, or required action. On a host block, say exactly: "${HOST_POLICY_ALERT_TEXT}" and do not retry through another transport. Redact secrets and proprietary content.`;
+}
+
 export function taskClosureReason(signal = null) {
   const signalLine = signal
-    ? `High-value lesson detected: ${signal}. Capture it unless you already submitted the lesson.`
+    ? `High-value lesson detected: ${signal}. Capture it unless it was already submitted.`
     : null;
   return [
-    "Before you finish: this session involved a reusable service, API, tool, workflow, UI, review, or engineering task, but no completed Remembrance query/use was recorded.",
+    "Before finishing, silently recover the pending Remembrance query for this reusable task using the full conversation; no completed Remembrance query/use was recorded.",
     signalLine,
-    "Infer the concrete task from the full conversation and call query_skills now when the MCP tool is visible. If MCP is unavailable, use POST /api/v1/agent/query with a redacted summary.",
-    "Evaluate returned result IDs explicitly: call submit_query_feedback once with the complete good/partial/poor verdict set, then use submit_feedback only after actually using a skill. If nothing fits, report overall_fit none and propose a skill idea only when you actually built a reusable workflow.",
-    "Submit a failure_report for a reusable self-correction, user-caught mistake, CI/deploy failure, security issue, or release/versioning miss even when no skill was used.",
-    "Redact secrets, private URLs, credentials, raw logs, and proprietary content; attach bounded reproduction detail or artifact hashes when available.",
-    "If the task was truly trivial and produced no reusable lesson, say so in one line; you will not be asked again for this task.",
+    "Call query_skills with a redacted full-context summary, evaluate the returned matches, then close any warranted submit_query_feedback, submit_feedback, or submit_remembrance action before responding.",
+    routineContributionVisibilityInstruction(),
   ]
     .filter(Boolean)
     .join("\n");
@@ -1169,6 +1464,17 @@ export function detectHighValueLessonSignalInText(text) {
   return null;
 }
 
+export function hostPolicyAlertWasReported(input) {
+  const value = String(
+    input?.last_assistant_message ??
+      input?.lastAssistantMessage ??
+      input?.assistant_message ??
+      input?.message ??
+      "",
+  );
+  return value.includes(HOST_POLICY_ALERT_TEXT);
+}
+
 // Pure decision function (unit-tested): compare completed registry use and task
 // eligibility with the last-prompted count. A completed use prompts for a
 // contribution; eligible work with no completed query prompts for full-context
@@ -1182,6 +1488,9 @@ export function decideStop(input, options = {}) {
   if (input?.stop_hook_active) {
     return { allow: true, why: "stop_hook_active" };
   }
+  if (hostPolicyAlertWasReported(input)) {
+    return { allow: true, why: "host_policy_alert_reported" };
+  }
   const sessionId = sessionIdFor(input);
   const readUse = options.readUseCount ?? readRegistryUseCount;
   const useCount = readUse(sessionId, env);
@@ -2142,16 +2451,25 @@ async function postTaskOutcome(payload, options = {}) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), autoQueryTimeoutMs(env));
   try {
-    const credential = resolveApiCredential(env);
+    const access = resolveApiAccessSnapshot(env);
+    const credential = access.credential;
     if (isUnusableConfigurationSource(credential.source)) return false;
     const headers = {
       "content-type": "application/json",
-      "user-agent": options.userAgent ?? DEFAULT_USER_AGENT,
+      "user-agent": clientUserAgent(options.userAgent),
     };
     const apiKey = credential.apiKey;
     if (apiKey) headers["x-remembrance-api-key"] = apiKey;
+    const principalSession = readHookPrincipalSession(
+      normalizeRuntime(env.REMEMBRANCE_PLUGIN_HOST),
+      env,
+      access,
+    );
+    if (principalSession?.token) {
+      headers["x-remembrance-principal-session"] = principalSession.token;
+    }
     const response = await (options.fetchImpl ?? fetch)(
-      `${apiUrl(env)}/api/v1/agent/task-outcomes`,
+      `${access.apiConfiguration.apiUrl}/api/v1/agent/task-outcomes`,
       {
         method: "POST",
         headers,
@@ -2304,74 +2622,1130 @@ function pluginHealthDir(env = process.env) {
   return join(homedir(), ".cache", "remembrance", "plugin-health");
 }
 
-function normalizedPluginHealthSurface(value) {
-  const surface = String(value ?? "")
-    .trim()
-    .toLowerCase();
-  return PLUGIN_HEALTH_SURFACES.has(surface) ? surface : null;
+function pluginAlertDir(env = process.env) {
+  if (env?.REMEMBRANCE_PLUGIN_ALERT_DIR) {
+    return String(env.REMEMBRANCE_PLUGIN_ALERT_DIR);
+  }
+  if (process.env.VITEST) {
+    return join(
+      tmpdir(),
+      "remembrance-plugin-alert-tests",
+      String(process.pid),
+    );
+  }
+  return join(homedir(), ".cache", "remembrance", "plugin-alerts");
 }
 
-export function pluginHealthPath(surface, env = process.env) {
-  return pluginHealthSessionPath(surface, null, env);
+function clientUpdateDir(env = process.env) {
+  if (env?.REMEMBRANCE_CLIENT_UPDATE_DIR) {
+    return String(env.REMEMBRANCE_CLIENT_UPDATE_DIR);
+  }
+  if (process.env.VITEST) {
+    return join(
+      tmpdir(),
+      "remembrance-client-update-tests",
+      String(process.pid),
+    );
+  }
+  return join(homedir(), ".cache", "remembrance", "client-updates");
 }
 
-function pluginHealthSessionPath(surface, sessionId, env = process.env) {
-  const normalized = normalizedPluginHealthSurface(surface);
-  if (!normalized) return null;
-  const normalizedSession = safeText(sessionId ?? "", 256);
-  if (!normalizedSession || normalizedSession === "unknown") {
-    return join(pluginHealthDir(env), `${normalized}.json`);
+function principalSessionDir(env = process.env) {
+  if (env?.REMEMBRANCE_PRINCIPAL_SESSION_DIR) {
+    return String(env.REMEMBRANCE_PRINCIPAL_SESSION_DIR);
   }
-  const sessionHash = createHash("sha256")
-    .update(normalizedSession, "utf8")
+  if (process.env.VITEST) {
+    return join(
+      tmpdir(),
+      "remembrance-principal-session-tests",
+      String(process.pid),
+    );
+  }
+  return join(homedir(), ".cache", "remembrance", "principal-sessions");
+}
+
+function agentIdentityPath(env = process.env) {
+  return (
+    String(env.REMEMBRANCE_AGENT_KEY_PATH ?? "").trim() ||
+    join(
+      env.XDG_CONFIG_HOME || join(homedir(), ".config"),
+      "remembrance",
+      "agent-key.json",
+    )
+  );
+}
+
+function readHookIdentity(env = process.env) {
+  try {
+    const parsed = JSON.parse(
+      readSecureHookFile(agentIdentityPath(env), MAX_LOCAL_CONFIG_BYTES),
+    );
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed) ||
+      !["other", "codex", "cursor", "claude_code"].includes(parsed.provider) ||
+      typeof parsed.key_id !== "string" ||
+      !parsed.key_id ||
+      typeof parsed.subject !== "string" ||
+      !parsed.subject ||
+      typeof parsed.public_key !== "string" ||
+      !parsed.public_key ||
+      typeof parsed.private_key !== "string" ||
+      !parsed.private_key
+    ) {
+      return null;
+    }
+    createPrivateKey(parsed.private_key);
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function localIdentityProvider(runtime) {
+  const normalized = normalizeRuntime(runtime);
+  return ["codex", "cursor", "claude_code"].includes(normalized)
+    ? normalized
+    : "other";
+}
+
+function createHookIdentity(runtime, env = process.env) {
+  const path = agentIdentityPath(env);
+  const existing = readHookIdentity(env);
+  if (existing) return existing;
+  try {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    const publicKeyPem = String(
+      publicKey.export({ type: "spki", format: "pem" }),
+    );
+    const keyId = `tofu_${createHash("sha256")
+      .update(publicKeyPem)
+      .digest("hex")
+      .slice(0, 24)}`;
+    const identity = {
+      provider: localIdentityProvider(runtime),
+      subject: `local:${keyId}`,
+      key_id: keyId,
+      public_key: publicKeyPem,
+      private_key: String(privateKey.export({ type: "pkcs8", format: "pem" })),
+      created_at: new Date().toISOString(),
+    };
+    ensureSecureHookDirectory(dirname(path));
+    writeFileSync(path, `${JSON.stringify(identity, null, 2)}\n`, {
+      mode: 0o600,
+      flag: "wx",
+    });
+    return identity;
+  } catch {
+    return readHookIdentity(env);
+  }
+}
+
+function canonicalHookJson(value) {
+  const sort = (candidate) => {
+    if (Array.isArray(candidate)) return candidate.map(sort);
+    if (candidate && typeof candidate === "object") {
+      return Object.keys(candidate)
+        .sort()
+        .reduce((result, key) => {
+          result[key] = sort(candidate[key]);
+          return result;
+        }, {});
+    }
+    return candidate;
+  };
+  return JSON.stringify(sort(value));
+}
+
+async function registerHookIdentity(identity, fetchImpl, access, signal) {
+  let ownerBinding = null;
+  try {
+    const bindingResponse = await fetchImpl(
+      `${access.apiConfiguration.apiUrl}/api/v1/agent/keys/register`,
+      {
+        method: "GET",
+        headers: principalRequestHeaders(access),
+        signal,
+      },
+    );
+    if (bindingResponse?.ok) {
+      const bindingPayload = await bindingResponse.json();
+      const candidate = String(bindingPayload?.owner_binding ?? "").trim();
+      if (/^areg_[A-Za-z0-9_-]{24,120}$/.test(candidate)) {
+        ownerBinding = candidate;
+      }
+    }
+  } catch {
+    // Registration remains fail-open; an existing same-scope key can still use
+    // the legacy proof while new organization claims require the binding.
+  }
+  const signedAt = new Date().toISOString();
+  const publicKeyHash = `sha256:${createHash("sha256")
+    .update(identity.public_key)
+    .digest("hex")}`;
+  const signingPayload = canonicalHookJson({
+    version: ownerBinding ? "v2" : "v1",
+    purpose: "remembrance-agent-key-registration",
+    provider: identity.provider,
+    key_id: identity.key_id,
+    ...(ownerBinding ? { owner_binding: ownerBinding } : {}),
+    public_key_hash: publicKeyHash,
+    subject: identity.subject,
+    signed_at: signedAt,
+  });
+  const signature = signPayload(
+    null,
+    Buffer.from(signingPayload),
+    createPrivateKey(identity.private_key),
+  ).toString("base64url");
+  const response = await fetchImpl(
+    `${access.apiConfiguration.apiUrl}/api/v1/agent/keys/register`,
+    {
+      method: "POST",
+      headers: principalRequestHeaders(access),
+      body: JSON.stringify({
+        provider: identity.provider,
+        key_id: identity.key_id,
+        public_key: identity.public_key,
+        subject: identity.subject,
+        proof: {
+          algorithm: "ed25519",
+          ...(ownerBinding ? { owner_binding: ownerBinding } : {}),
+          signed_at: signedAt,
+          signature,
+        },
+        metadata: { registered_by: "remembrance-plugin-hook" },
+      }),
+      signal,
+    },
+  );
+  return response?.ok === true;
+}
+
+function principalSessionCachePath(
+  runtime,
+  keyId,
+  env = process.env,
+  access = resolveApiAccessSnapshot(env),
+) {
+  const credentialFingerprint = createHash("sha256")
+    .update(
+      [access.credential.source, access.credential.apiKey].join(":"),
+      "utf8",
+    )
     .digest("hex")
-    .slice(0, 24);
-  return join(pluginHealthDir(env), `${normalized}.${sessionHash}.json`);
+    .slice(0, 16);
+  const digest = createHash("sha256")
+    .update(
+      [
+        access.apiConfiguration.apiUrl,
+        credentialFingerprint,
+        normalizeRuntime(runtime),
+        String(keyId),
+      ].join(":"),
+      "utf8",
+    )
+    .digest("hex")
+    .slice(0, 32);
+  return join(principalSessionDir(env), `${digest}.json`);
 }
 
-export function readPluginLifecycleHealth(
-  surface,
+export function readHookPrincipalSession(
+  runtime,
   env = process.env,
-  sessionId = null,
+  access = resolveApiAccessSnapshot(env),
 ) {
-  const path = pluginHealthSessionPath(surface, sessionId, env);
-  if (!path) return null;
+  const identity = readHookIdentity(env);
+  if (!identity) return null;
   try {
     const parsed = JSON.parse(
-      readSecureHookFile(path, MAX_LOCAL_HEALTH_MARKER_BYTES),
+      readSecureHookFile(
+        principalSessionCachePath(runtime, identity.key_id, env, access),
+        MAX_LOCAL_PRINCIPAL_SESSION_BYTES,
+      ),
     );
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? parsed
-      : null;
+    if (
+      typeof parsed?.token !== "string" ||
+      !/^psess_[A-Za-z0-9_-]{24,160}$/.test(parsed.token) ||
+      !Number.isFinite(Date.parse(parsed.expires_at ?? "")) ||
+      Date.parse(parsed.expires_at) <= Date.now() + 60_000
+    ) {
+      return null;
+    }
+    return {
+      token: parsed.token,
+      expires_at: parsed.expires_at,
+      member_linked: parsed.member_linked === true,
+    };
   } catch {
     return null;
   }
 }
 
-// Record that a native lifecycle component actually executed. The marker is
-// intentionally local and content-free: it contains only surface/version,
-// component timestamps, and the credential source category. Local MCP reads
-// it through run_connection_doctor so partial activation cannot look healthy.
-export function recordPluginLifecycleHealth(
+export function clearHookPrincipalSession(
+  runtime,
+  env = process.env,
+  access = resolveApiAccessSnapshot(env),
+) {
+  const identity = readHookIdentity(env);
+  if (!identity) return false;
+  try {
+    rmSync(principalSessionCachePath(runtime, identity.key_id, env, access), {
+      force: true,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function warmPrincipalSession(
   {
-    surface,
-    component,
-    pluginVersion = null,
+    runtime,
+    hostSurface = null,
+    clientVersion = null,
     hostVersion = null,
-    credentialSource = null,
-    sessionId = null,
+    fetchImpl = fetch,
+    apiAccess = null,
   },
   env = process.env,
 ) {
-  const normalizedSurface = normalizedPluginHealthSurface(surface);
-  const normalizedComponent = String(component ?? "")
-    .trim()
-    .toLowerCase();
+  // Same pause-don't-downgrade rule the query, directive-event, and task-outcome
+  // paths enforce. It has to live HERE, not in the callers: every host adapter
+  // warms the principal session at session start, so a per-caller guard is one
+  // that six adapters can each forget.
+  //
+  // principalRequestHeaders() already withholds the API key when the source is
+  // unusable, which is only half a guard: the request would still go out, and
+  // apiUrl() hands back DEFAULT_API_URL while merely flagging the source, so an
+  // unreadable config would register the agent key anonymously against the
+  // default registry instead of the destination that config was naming. The
+  // principal-session challenge also carries a member link token, so suppressing
+  // the request — not just the header — is what keeps a secret from reaching a
+  // destination the user never chose.
+  const access = apiAccess ?? resolveApiAccessSnapshot(env);
+  const credential = access.credential;
   if (
-    !normalizedSurface ||
-    !PLUGIN_HEALTH_COMPONENTS.has(normalizedComponent)
+    isUnusableConfigurationSource(access.apiConfiguration.source) ||
+    isUnusableConfigurationSource(credential.source)
   ) {
-    return false;
+    debugLog(env, "shared_config_unusable", {});
+    return null;
+  }
+  const normalizedRuntime = normalizeRuntime(runtime);
+  const normalizedHostSurface = runtimeHostSurface(
+    normalizedRuntime,
+    env,
+    hostSurface,
+  );
+  const identity =
+    readHookIdentity(env) ?? createHookIdentity(normalizedRuntime, env);
+  if (!identity) return null;
+  const cached = readHookPrincipalSession(normalizedRuntime, env, access);
+  if (cached) return cached;
+  const warmupKey = principalSessionCachePath(
+    normalizedRuntime,
+    identity.key_id,
+    env,
+    access,
+  );
+  const activeWarmup = principalSessionWarmups.get(warmupKey);
+  if (activeWarmup) return activeWarmup;
+  const warmup = warmPrincipalSessionUncached(
+    {
+      normalizedRuntime,
+      normalizedHostSurface,
+      clientVersion,
+      hostVersion,
+      fetchImpl,
+      identity,
+      warmupKey,
+      apiAccess: access,
+    },
+    env,
+  );
+  principalSessionWarmups.set(warmupKey, warmup);
+  try {
+    return await warmup;
+  } finally {
+    if (principalSessionWarmups.get(warmupKey) === warmup) {
+      principalSessionWarmups.delete(warmupKey);
+    }
+  }
+}
+
+async function warmPrincipalSessionUncached(
+  {
+    normalizedRuntime,
+    normalizedHostSurface,
+    clientVersion,
+    hostVersion,
+    fetchImpl,
+    identity,
+    warmupKey,
+    apiAccess,
+  },
+  env,
+) {
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(),
+    PRINCIPAL_SESSION_TIMEOUT_MS,
+  );
+  try {
+    if (
+      !(await registerHookIdentity(
+        identity,
+        fetchImpl,
+        apiAccess,
+        controller.signal,
+      ))
+    ) {
+      return null;
+    }
+    const memberLinkToken = apiAccess.memberLinkToken;
+    const profileKey = createHash("sha256")
+      .update(
+        [
+          identity.key_id,
+          normalizedRuntime,
+          normalizedHostSurface,
+          "plugin_hook",
+        ].join(":"),
+        "utf8",
+      )
+      .digest("base64url");
+    const challengePayload = {
+      action: "challenge",
+      provider: identity.provider,
+      key_id: identity.key_id,
+      runtime_profile: {
+        runtime: normalizedRuntime,
+        surface: "plugin_hook",
+        host_surface: normalizedHostSurface,
+        client_name: runtimeDisplayName(normalizedRuntime),
+        client_version: safeText(clientVersion ?? "unknown", 64),
+        runtime_version: safeText(hostVersion ?? "", 64) || null,
+        profile_key: `rpf_${profileKey}`,
+      },
+      ...(memberLinkToken ? { member_link_token: memberLinkToken } : {}),
+    };
+    let challenge = await postPrincipalSession(
+      challengePayload,
+      fetchImpl,
+      apiAccess,
+      controller.signal,
+    );
+    if (!challenge && memberLinkToken) {
+      challenge = await postPrincipalSession(
+        { ...challengePayload, member_link_token: undefined },
+        fetchImpl,
+        apiAccess,
+        controller.signal,
+      );
+    }
+    if (!challenge?.challenge_id || !challenge?.signing_payload) return null;
+    const signature = signPayload(
+      null,
+      Buffer.from(challenge.signing_payload),
+      createPrivateKey(identity.private_key),
+    ).toString("base64url");
+    const session = await postPrincipalSession(
+      {
+        action: "exchange",
+        provider: identity.provider,
+        key_id: identity.key_id,
+        challenge_id: challenge.challenge_id,
+        signature,
+      },
+      fetchImpl,
+      apiAccess,
+      controller.signal,
+    );
+    if (!session?.session_token || !session?.expires_at) return null;
+    const stored = {
+      token: session.session_token,
+      expires_at: session.expires_at,
+      member_linked: session.member_linked === true,
+    };
+    writeHookPrincipalSession(warmupKey, stored);
+    return stored;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function postPrincipalSession(payload, fetchImpl, access, signal) {
+  const response = await fetchImpl(
+    `${access.apiConfiguration.apiUrl}/api/v1/agent/principal-sessions`,
+    {
+      method: "POST",
+      headers: principalRequestHeaders(access),
+      body: JSON.stringify(payload),
+      signal,
+    },
+  );
+  return response?.ok ? response.json() : null;
+}
+
+function principalRequestHeaders(access) {
+  const headers = {
+    "content-type": "application/json",
+    "user-agent": clientUserAgent(),
+  };
+  const credential = access.credential;
+  if (credential.apiKey && !isUnusableConfigurationSource(credential.source)) {
+    headers["x-remembrance-api-key"] = credential.apiKey;
+  }
+  return headers;
+}
+
+function writeHookPrincipalSession(path, value) {
+  const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    ensureSecureHookDirectory(dirname(path));
+    writeFileSync(temporaryPath, `${JSON.stringify(value)}\n`, {
+      mode: 0o600,
+      flag: "wx",
+    });
+    renameSync(temporaryPath, path);
+    return true;
+  } catch {
+    try {
+      rmSync(temporaryPath, { force: true });
+    } catch {
+      // Principal sessions are optional and always fail open for retrieval.
+    }
+    return false;
+  }
+}
+
+function runtimeDisplayName(runtime) {
+  return (
+    {
+      codex: "Codex",
+      claude_code: "Claude Code",
+      cursor: "Cursor",
+      openclaw: "OpenClaw",
+      vs_code: "VS Code",
+      opencode: "opencode",
+    }[runtime] ?? "Agent"
+  );
+}
+
+function sanitizeEffectivePreferences(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter(
+      (item) =>
+        item &&
+        typeof item === "object" &&
+        !Array.isArray(item) &&
+        /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(item.key) &&
+        typeof item.value === "string" &&
+        /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(item.value) &&
+        ["presentation", "workflow", "strategy_selection"].includes(
+          item.effect ?? "presentation",
+        ) &&
+        ["prefer", "avoid"].includes(item.strength ?? "prefer"),
+    )
+    .slice(0, 32)
+    .map((item) => {
+      const label = safeText(item.label ?? item.key, 96);
+      const behavior = safeText(item.behavior ?? item.value, 320);
+      const direction = item.strength === "avoid" ? "avoid" : "prefer";
+      const authority =
+        item.source === "mandatory_org" ? "required organization" : item.source;
+      return `${label} [${safeText(item.effect ?? "presentation", 24)}, ${safeText(authority ?? "preference", 32)}]: ${direction} ${behavior}`;
+    });
+}
+
+function clientUpdatePath(surface, env = process.env) {
+  const normalized = normalizedPluginHealthSurface(surface);
+  return normalized ? join(clientUpdateDir(env), `${normalized}.json`) : null;
+}
+
+export async function checkForClientUpdate(
+  {
+    surface,
+    currentVersion,
+    fetchImpl = fetch,
+    now = Date.now(),
+    timeoutMs = CLIENT_UPDATE_TIMEOUT_MS,
+  },
+  env = process.env,
+) {
+  const normalizedSurface = normalizedPluginHealthSurface(surface);
+  if (
+    !normalizedSurface ||
+    disabled(env.REMEMBRANCE_CLIENT_UPDATE_CHECK) ||
+    !parseStableClientVersion(currentVersion)
+  ) {
+    return null;
+  }
+  const configuration = resolveApiConfiguration(env);
+  if (isUnusableConfigurationSource(configuration.source)) return null;
+  const path = clientUpdatePath(normalizedSurface, env);
+  let manifest = readCachedClientRelease(path, now);
+  if (!manifest) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(
+        `${configuration.apiUrl.replace(/\/+$/, "")}/.well-known/remembrance-client-release.json`,
+        {
+          headers: { accept: "application/json" },
+          signal: controller.signal,
+        },
+      );
+      if (!response?.ok) return null;
+      const text = await response.text();
+      if (Buffer.byteLength(text, "utf8") > MAX_LOCAL_CLIENT_UPDATE_BYTES) {
+        return null;
+      }
+      try {
+        manifest = parseClientReleaseManifest(JSON.parse(text));
+      } catch {
+        return null;
+      }
+      if (!manifest) return null;
+      writeCachedClientRelease(path, manifest, now);
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  if (
+    !manifest.surfaces.includes(normalizedSurface) ||
+    compareStableClientVersions(manifest.latest_version, currentVersion) <= 0
+  ) {
+    return null;
+  }
+  const guidance = CLIENT_UPDATE_GUIDANCE[normalizedSurface];
+  if (!guidance) return null;
+  const command = guidance.command
+    ? `\nTrusted update command bundled with this installed client:\n${guidance.command}`
+    : "";
+  return {
+    current_version: currentVersion,
+    latest_version: manifest.latest_version,
+    surface: normalizedSurface,
+    notice: [
+      `Remembrance update available: installed ${currentVersion}, published ${manifest.latest_version}.`,
+      guidance.update,
+      command,
+      guidance.restart,
+      "Do not claim the new version is active until a fresh process reports it.",
+    ]
+      .filter(Boolean)
+      .join("\n"),
+  };
+}
+
+function readCachedClientRelease(path, now) {
+  if (!path) return null;
+  try {
+    const parsed = JSON.parse(
+      readSecureHookFile(path, MAX_LOCAL_CLIENT_UPDATE_BYTES),
+    );
+    if (
+      parsed?.schema_version !== 1 ||
+      !Number.isFinite(parsed?.checked_at) ||
+      parsed.checked_at > now + 5 * 60 * 1000 ||
+      parsed.checked_at + CLIENT_UPDATE_CACHE_TTL_MS <= now
+    ) {
+      return null;
+    }
+    return parseClientReleaseManifest(parsed.manifest);
+  } catch {
+    return null;
+  }
+}
+
+function writeCachedClientRelease(path, manifest, now) {
+  if (!path) return false;
+  const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    ensureSecureHookDirectory(dirname(path));
+    writeFileSync(
+      temporaryPath,
+      `${JSON.stringify({ schema_version: 1, checked_at: now, manifest })}\n`,
+      { mode: 0o600, flag: "wx" },
+    );
+    renameSync(temporaryPath, path);
+    return true;
+  } catch {
+    try {
+      rmSync(temporaryPath, { force: true });
+    } catch {
+      // Update checks are advisory and never break the host lifecycle.
+    }
+    return false;
+  }
+}
+
+function parseClientReleaseManifest(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (value.schema_version !== "1") return null;
+  if (!parseStableClientVersion(value.latest_version)) return null;
+  if (
+    typeof value.published_at !== "string" ||
+    !isCanonicalClientReleaseTimestamp(value.published_at) ||
+    !Array.isArray(value.surfaces)
+  ) {
+    return null;
+  }
+  const surfaces = value.surfaces.filter(
+    (item) =>
+      typeof item === "string" && CLIENT_RELEASE_MANIFEST_SURFACES.has(item),
+  );
+  if (
+    surfaces.length !== value.surfaces.length ||
+    new Set(surfaces).size !== surfaces.length
+  ) {
+    return null;
+  }
+  return {
+    schema_version: "1",
+    latest_version: value.latest_version,
+    published_at: new Date(value.published_at).toISOString(),
+    surfaces,
+  };
+}
+
+function isCanonicalClientReleaseTimestamp(value) {
+  const timestamp = Date.parse(value);
+  return (
+    Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value
+  );
+}
+
+function parseStableClientVersion(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(
+    String(value ?? ""),
+  );
+  if (!match) return null;
+  const parts = match.slice(1).map(Number);
+  return parts.every(
+    (part) => Number.isSafeInteger(part) && part >= 0 && part <= 9_999,
+  )
+    ? parts
+    : null;
+}
+
+function compareStableClientVersions(left, right) {
+  const leftParts = parseStableClientVersion(left);
+  const rightParts = parseStableClientVersion(right);
+  if (!leftParts || !rightParts) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    const difference = leftParts[index] - rightParts[index];
+    if (difference !== 0) return Math.sign(difference);
+  }
+  return 0;
+}
+
+function pluginAlertSessionPath(surface, sessionId, env = process.env) {
+  const normalized = normalizedPluginHealthSurface(surface);
+  if (!normalized) return null;
+  const hash = createHash("sha256")
+    .update(String(sessionId ?? "unknown"), "utf8")
+    .digest("hex")
+    .slice(0, 24);
+  return join(pluginAlertDir(env), `${normalized}.${hash}.json`);
+}
+
+function hostPolicyOperationClass(toolName) {
+  const normalized = String(toolName ?? "").toLowerCase();
+  if (
+    normalized.endsWith("query_skills") ||
+    normalized.endsWith("list_skills") ||
+    normalized.endsWith("get_skill") ||
+    normalized.endsWith("get_resource") ||
+    normalized.endsWith("invoke_skill") ||
+    normalized.endsWith("run_connection_doctor") ||
+    normalized.endsWith("get_connection_status")
+  ) {
+    return "query";
+  }
+  if (
+    normalized.endsWith("propose_private_skill") ||
+    normalized.endsWith("queue_private_skill_import")
+  ) {
+    return "private_contribution";
+  }
+  if (
+    normalized.endsWith("propose_skill_idea") ||
+    normalized.endsWith("submit_remembrance") ||
+    normalized.endsWith("submit_suggestion") ||
+    normalized.endsWith("submit_resource") ||
+    normalized.endsWith("submit_resource_review")
+  ) {
+    return "contribution";
+  }
+  if (
+    normalized.endsWith("submit_query_feedback") ||
+    normalized.endsWith("submit_feedback") ||
+    normalized.endsWith("report_task_outcome")
+  ) {
+    return "feedback";
+  }
+  return "other";
+}
+
+function isRemembranceToolName(toolName) {
+  const normalized = String(toolName ?? "").toLowerCase();
+  return (
+    normalized.includes("remembrance") ||
+    [
+      "run_connection_doctor",
+      "get_connection_status",
+      "query_skills",
+      "list_skills",
+      "get_skill",
+      "get_resource",
+      "invoke_skill",
+      "get_value_proof",
+      "report_task_outcome",
+      "submit_query_feedback",
+      "submit_feedback",
+      "submit_remembrance",
+      "propose_skill_idea",
+      "propose_private_skill",
+      "queue_private_skill_import",
+      "submit_suggestion",
+      "submit_resource",
+      "submit_resource_review",
+    ].some((candidate) => normalized.endsWith(candidate))
+  );
+}
+
+function boundedHostPolicyText(value, depth = 0) {
+  if (depth > 3 || value == null) return "";
+  if (typeof value === "string") return value.slice(0, 2_000);
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, 8)
+      .map((item) => boundedHostPolicyText(item, depth + 1))
+      .join(" ")
+      .slice(0, 4_000);
+  }
+  if (typeof value !== "object") return "";
+  return [
+    value.message,
+    value.reason,
+    value.permission_decision_reason,
+    value.permissionDecisionReason,
+    value.decision,
+    value.response,
+    value.error,
+    value.detail,
+    value.details,
+    value.output,
+    value.result,
+    value.tool_response,
+    value.toolResponse,
+    value.properties?.error,
+    value.properties?.message,
+    value.properties?.reason,
+  ]
+    .map((item) => boundedHostPolicyText(item, depth + 1))
+    .filter(Boolean)
+    .join(" ")
+    .slice(0, 4_000);
+}
+
+export function classifyHostPolicyDenial({
+  eventType = "",
+  toolName = "",
+  value = null,
+} = {}) {
+  if (!isRemembranceToolName(toolName)) return null;
+  const text = boundedHostPolicyText(value);
+  const denied =
+    /\b(?:block(?:ed|ing)?|den(?:y|ied|ial)|disallow(?:ed)?|prohibit(?:ed)?|not permitted|permission refused|cannot (?:send|share|export)|may not (?:send|share|export))\b/i.test(
+      text,
+    );
+  const policyContext =
+    /\b(?:host|tenant|workspace|organization|administrator|admin|privacy|security|policy|data[- ](?:export|egress|loss prevention)|dlp|external service|trusted service)\b/i.test(
+      text,
+    );
+  const normalizedEvent = String(eventType ?? "").toLowerCase();
+  const permissionEvent = normalizedEvent.includes("permission");
+  const explicitPreTransportContext =
+    /\b(?:host(?:ed)?|tenant|workspace)\s+(?:(?:privacy|security|execution|tool|mcp|data[- ](?:export|egress))\s+)?policy\b|\b(?:privacy|security|data[- ](?:export|egress|loss prevention)|dlp)\s+(?:guard|policy|rule|restriction)\b|\bbefore\s+(?:contacting|reaching|calling|sending\s+(?:it\s+)?to)\s+(?:remembrance|the\s+(?:mcp|external service)|an?\s+external service)\b|\b(?:external|trusted)\s+service\b/i.test(
+      text,
+    );
+  // A host permission event is itself pre-transport evidence. Generic failed
+  // tool events need an explicit host/export signal so a Remembrance API 403
+  // such as an organization-policy refusal is never mislabeled as host policy.
+  if (
+    !denied ||
+    !policyContext ||
+    (!permissionEvent && !explicitPreTransportContext)
+  ) {
+    return null;
+  }
+  return {
+    denial_class: permissionEvent
+      ? "host_permission_policy"
+      : "host_execution_policy",
+    operation_class: hostPolicyOperationClass(toolName),
+    before_mcp: permissionEvent ? "yes" : "unknown",
+  };
+}
+
+function readPluginAlertState(surface, sessionId, env = process.env) {
+  const path = pluginAlertSessionPath(surface, sessionId, env);
+  if (!path) return null;
+  try {
+    const parsed = JSON.parse(
+      readSecureHookFile(path, MAX_LOCAL_PLUGIN_ALERT_BYTES),
+    );
+    if (parsed?.schema_version !== 1 || !Array.isArray(parsed?.observations)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writePluginAlertState(surface, sessionId, state, env = process.env) {
+  const path = pluginAlertSessionPath(surface, sessionId, env);
+  if (!path) return false;
+  const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    ensureSecureHookDirectory(dirname(path));
+    writeFileSync(temporaryPath, `${JSON.stringify(state)}\n`, {
+      mode: 0o600,
+      flag: "wx",
+    });
+    renameSync(temporaryPath, path);
+    prunePluginAlertFiles(path, env);
+    return true;
+  } catch {
+    try {
+      rmSync(temporaryPath, { force: true });
+    } catch {
+      // Local policy observations are advisory and must never break the host.
+    }
+    return false;
+  }
+}
+
+function prunePluginAlertFiles(keepPath, env) {
+  const directory = pluginAlertDir(env);
+  const cutoff = Date.now() - PLUGIN_ALERT_TTL_MS;
+  try {
+    const candidates = readdirSync(directory)
+      .filter((name) => /^[a-z_]+\.[a-f0-9]{24}\.json$/.test(name))
+      .map((name) => {
+        const path = join(directory, name);
+        return { path, modified: statSync(path).mtimeMs };
+      })
+      .sort((left, right) => right.modified - left.modified);
+    for (const candidate of candidates) {
+      if (
+        candidate.path !== keepPath &&
+        (candidate.modified < cutoff ||
+          candidates.indexOf(candidate) >= PLUGIN_ALERT_LIMIT)
+      ) {
+        rmSync(candidate.path, { force: true });
+      }
+    }
+  } catch {
+    // Pruning is advisory.
+  }
+}
+
+export function recordHostPolicyDenial(
+  {
+    surface,
+    sessionId,
+    eventType = "",
+    toolName = "",
+    value = null,
+    pluginVersion = null,
+    hostVersion = null,
+  },
+  env = process.env,
+) {
+  const normalizedSurface = normalizedPluginHealthSurface(surface);
+  const classification = classifyHostPolicyDenial({
+    eventType,
+    toolName,
+    value,
+  });
+  if (!normalizedSurface || !classification) return null;
+  const now = new Date().toISOString();
+  const sessionHash = createHash("sha256")
+    .update(String(sessionId ?? "unknown"), "utf8")
+    .digest("hex")
+    .slice(0, 24);
+  const id = createHash("sha256")
+    .update(
+      [
+        normalizedSurface,
+        sessionHash,
+        classification.operation_class,
+        classification.denial_class,
+      ].join(":"),
+      "utf8",
+    )
+    .digest("hex")
+    .slice(0, 24);
+  const existing = readPluginAlertState(normalizedSurface, sessionId, env);
+  const current = existing?.observations?.find((item) => item?.id === id);
+  const observation = {
+    id,
+    denial_class: classification.denial_class,
+    operation_class: classification.operation_class,
+    before_mcp: classification.before_mcp,
+    plugin_version: safeText(pluginVersion ?? "", 64),
+    host_version: safeText(hostVersion ?? "", 64),
+    first_seen_at: current?.first_seen_at ?? now,
+    last_seen_at: now,
+    count: Math.min(999, Math.max(0, Number(current?.count) || 0) + 1),
+    alerted_at: current?.alerted_at ?? null,
+  };
+  const observations = [
+    observation,
+    ...(existing?.observations ?? []).filter((item) => item?.id !== id),
+  ]
+    .filter((item) => {
+      const seenAt = Date.parse(item?.last_seen_at ?? "");
+      return (
+        Number.isFinite(seenAt) && Date.now() - seenAt <= PLUGIN_ALERT_TTL_MS
+      );
+    })
+    .slice(0, 12);
+  const state = {
+    schema_version: 1,
+    surface: normalizedSurface,
+    session_hash: sessionHash,
+    observations,
+    updated_at: now,
+  };
+  return writePluginAlertState(normalizedSurface, sessionId, state, env)
+    ? observation
+    : null;
+}
+
+export function readPendingHostPolicyAlert(
+  surface,
+  sessionId,
+  env = process.env,
+) {
+  const state = readPluginAlertState(surface, sessionId, env);
+  return (
+    state?.observations?.find(
+      (item) =>
+        !item?.alerted_at &&
+        Date.now() - Date.parse(item?.last_seen_at ?? "") <=
+          PLUGIN_ALERT_TTL_MS,
+    ) ?? null
+  );
+}
+
+export function markHostPolicyAlertDelivered(
+  surface,
+  sessionId,
+  observationId,
+  env = process.env,
+) {
+  const state = readPluginAlertState(surface, sessionId, env);
+  if (!state) return false;
+  const now = new Date().toISOString();
+  let changed = false;
+  const observations = state.observations.map((item) => {
+    if (item?.id !== observationId || item?.alerted_at) return item;
+    changed = true;
+    return { ...item, alerted_at: now };
+  });
+  if (!changed) return false;
+  return writePluginAlertState(
+    surface,
+    sessionId,
+    { ...state, observations, updated_at: now },
+    env,
+  );
+}
+
+function normalizedPluginHealthSurface(value) {
+  const surface = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  return PLUGIN_HEALTH_SURFACES.has(surface) ? surface : null;
+}
+
+export function pluginHealthPath(surface, env = process.env) {
+  return pluginHealthSessionPath(surface, null, env);
+}
+
+function pluginHealthSessionPath(surface, sessionId, env = process.env) {
+  const normalized = normalizedPluginHealthSurface(surface);
+  if (!normalized) return null;
+  const normalizedSession = safeText(sessionId ?? "", 256);
+  if (!normalizedSession || normalizedSession === "unknown") {
+    return join(pluginHealthDir(env), `${normalized}.json`);
+  }
+  const sessionHash = createHash("sha256")
+    .update(normalizedSession, "utf8")
+    .digest("hex")
+    .slice(0, 24);
+  return join(pluginHealthDir(env), `${normalized}.${sessionHash}.json`);
+}
+
+export function readPluginLifecycleHealth(
+  surface,
+  env = process.env,
+  sessionId = null,
+) {
+  const path = pluginHealthSessionPath(surface, sessionId, env);
+  if (!path) return null;
+  try {
+    const parsed = JSON.parse(
+      readSecureHookFile(path, MAX_LOCAL_HEALTH_MARKER_BYTES),
+    );
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// Record that a native lifecycle component actually executed. The marker is
+// intentionally local and content-free: it contains only surface/version,
+// component timestamps, and the credential source category. Local MCP reads
+// it through run_connection_doctor so partial activation cannot look healthy.
+export function recordPluginLifecycleHealth(
+  {
+    surface,
+    component,
+    pluginVersion = null,
+    hostVersion = null,
+    credentialSource = null,
+    sessionId = null,
+  },
+  env = process.env,
+) {
+  const normalizedSurface = normalizedPluginHealthSurface(surface);
+  const normalizedComponent = String(component ?? "")
+    .trim()
+    .toLowerCase();
+  if (
+    !normalizedSurface ||
+    !PLUGIN_HEALTH_COMPONENTS.has(normalizedComponent)
+  ) {
+    return false;
   }
   // Codex currently gives SessionStart a thread identifier while prompt/tool/
   // completion hooks use turn identifiers. Preserve the specific startup
@@ -2439,8 +3813,24 @@ export function recordPluginLifecycleHealth(
     .update(apiConfiguration.apiUrl.replace(/\/+$/, ""), "utf8")
     .digest("hex")
     .slice(0, 16);
+  const configuredEvidenceOrigin = String(
+    env?.REMEMBRANCE_PLUGIN_HEALTH_EVIDENCE_ORIGIN ?? "host_runtime",
+  )
+    .trim()
+    .toLowerCase();
+  const evidenceOrigin = [
+    "host_runtime",
+    "host_process",
+    "direct_adapter",
+  ].includes(configuredEvidenceOrigin)
+    ? configuredEvidenceOrigin
+    : "host_runtime";
+  const releaseRunId =
+    evidenceOrigin === "host_process"
+      ? safeText(env?.REMEMBRANCE_RELEASE_RUN_ID ?? "", 96)
+      : "";
   const payload = {
-    schema_version: 1,
+    schema_version: 2,
     surface: normalizedSurface,
     session_hash:
       sessionId && sessionId !== "unknown"
@@ -2465,6 +3855,8 @@ export function recordPluginLifecycleHealth(
         : "none",
     api_destination_source: apiConfiguration.source,
     api_destination_fingerprint: apiDestinationFingerprint,
+    evidence_origin: evidenceOrigin,
+    release_run_id: releaseRunId || null,
     components: {
       ...currentComponents,
       [normalizedComponent]: now,
@@ -2544,20 +3936,39 @@ export function readRemembranceConfig(env = process.env) {
   }
 }
 
-export function resolveApiCredential(env = process.env) {
-  const apiConfiguration = resolveApiConfiguration(env);
+function readSharedConfigSnapshot(env = process.env) {
+  const path = remembranceConfigPath(env);
+  if (!existsSync(path)) {
+    return { present: false, parsed: null, config: {} };
+  }
+  try {
+    const parsed = JSON.parse(readSecureHookFile(path, MAX_LOCAL_CONFIG_BYTES));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? { present: true, parsed, config: parsed }
+      : { present: true, parsed: null, config: {} };
+  } catch {
+    return { present: true, parsed: null, config: {} };
+  }
+}
+
+export function resolveApiAccessSnapshot(env = process.env) {
+  const shared = readSharedConfigSnapshot(env);
+  const apiConfiguration = resolveApiConfigurationFromSnapshot(env, shared);
   if (isUnusableConfigurationSource(apiConfiguration.source)) {
-    return { apiKey: "", source: apiConfiguration.source };
+    return {
+      apiConfiguration,
+      credential: { apiKey: "", source: apiConfiguration.source },
+      memberLinkToken: "",
+    };
   }
   const environmentKey = String(env.REMEMBRANCE_API_KEY ?? "").trim();
+  let credential;
   if (environmentKey) {
-    const explicitBinding = String(
-      env.REMEMBRANCE_API_KEY_ORIGIN ?? "",
-    ).trim();
+    const explicitBinding = String(env.REMEMBRANCE_API_KEY_ORIGIN ?? "").trim();
     const binding = explicitBinding
       ? normalizeApiUrl(explicitBinding, env)
       : { apiUrl: DEFAULT_API_URL, issue: null };
-    return credentialForApiDestination(
+    credential = credentialForApiDestination(
       binding.apiUrl && !binding.issue
         ? {
             apiKey: environmentKey,
@@ -2567,44 +3978,52 @@ export function resolveApiCredential(env = process.env) {
         : unusableDestinationCredential(),
       apiConfiguration,
     );
-  }
-  const path = remembranceConfigPath(env);
-  if (!existsSync(path)) {
-    return { apiKey: "", source: "none" };
-  }
-  try {
-    const parsed = JSON.parse(
-      readSecureHookFile(path, MAX_LOCAL_CONFIG_BYTES),
-    );
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return unusableSharedConfigCredential();
-    }
+  } else if (!shared.present) {
+    credential = { apiKey: "", source: "none" };
+  } else if (!shared.parsed) {
+    credential = unusableSharedConfigCredential();
+  } else {
+    const parsed = shared.parsed;
     if (
       Object.prototype.hasOwnProperty.call(parsed, "apiKey") &&
       (typeof parsed.apiKey !== "string" || !parsed.apiKey.trim())
     ) {
-      return unusableSharedConfigCredential();
-    }
-    const fromFile = parsed.apiKey;
-    if (typeof fromFile !== "string" || !fromFile.trim()) {
-      return { apiKey: "", source: "none" };
+      credential = unusableSharedConfigCredential();
+    } else {
+      const fromFile = parsed.apiKey;
+      if (typeof fromFile !== "string" || !fromFile.trim()) {
+        credential = { apiKey: "", source: "none" };
+      } else {
+        const binding = Object.prototype.hasOwnProperty.call(parsed, "apiUrl")
+          ? normalizeApiUrl(parsed.apiUrl, env)
+          : { apiUrl: DEFAULT_API_URL, issue: null };
+        credential = credentialForApiDestination(
+          binding.apiUrl && !binding.issue
+            ? {
+                apiKey: fromFile.trim(),
+                source: "shared_config",
+                boundApiUrl: binding.apiUrl,
+              }
+            : unusableSharedConfigCredential(),
+          apiConfiguration,
+        );
+      }
     }
-    const binding = Object.prototype.hasOwnProperty.call(parsed, "apiUrl")
-      ? normalizeApiUrl(parsed.apiUrl, env)
-      : { apiUrl: DEFAULT_API_URL, issue: null };
-    return credentialForApiDestination(
-      binding.apiUrl && !binding.issue
-        ? {
-            apiKey: fromFile.trim(),
-            source: "shared_config",
-            boundApiUrl: binding.apiUrl,
-          }
-        : unusableSharedConfigCredential(),
-      apiConfiguration,
-    );
-  } catch {
-    return unusableSharedConfigCredential();
   }
+  const rawMemberLinkToken = String(
+    env.REMEMBRANCE_MEMBER_LINK_TOKEN ?? shared.config.memberLinkToken ?? "",
+  ).trim();
+  return {
+    apiConfiguration,
+    credential,
+    memberLinkToken: /^mlink_[A-Za-z0-9_-]{24,160}$/.test(rawMemberLinkToken)
+      ? rawMemberLinkToken
+      : "",
+  };
+}
+
+export function resolveApiCredential(env = process.env) {
+  return resolveApiAccessSnapshot(env).credential;
 }
 
 // The org API key: an explicit env var wins, then the config file. Returns ""
@@ -2613,6 +4032,253 @@ export function resolveApiKey(env = process.env) {
   return resolveApiCredential(env).apiKey;
 }
 
+export function explicitPreferenceSettingsFromPrompt(prompt) {
+  const text = String(prompt ?? "").toLowerCase();
+  const settings = new Map();
+  const set = (key, value) => settings.set(key, { key, value });
+  if (
+    /\b(?:too many|fewer|less|minimal|sparse)\s+(?:code\s+)?comments?\b/.test(
+      text,
+    ) ||
+    /\bcomments?\s+(?:only\s+)?(?:when|for)\s+(?:the\s+)?(?:logic is )?(?:tricky|non-obvious)\b/.test(
+      text,
+    )
+  ) {
+    set("comment_density", "sparse");
+  } else if (
+    /\b(?:more|detailed|comprehensive)\s+(?:code\s+)?comments?\b/.test(text)
+  ) {
+    set("comment_density", "detailed");
+  }
+  if (/\bcomments?\s+(?:only\s+)?(?:on|for)\s+api\s+contracts?\b/.test(text)) {
+    set("comment_focus", "api_contracts");
+  } else if (
+    /\bcomments?\s+(?:only\s+)?(?:when|for)\s+(?:the\s+)?(?:logic is )?(?:tricky|non-obvious)\b/.test(
+      text,
+    )
+  ) {
+    set("comment_focus", "tricky_logic");
+  } else if (/\bcomments?\s+(?:only\s+)?(?:on|for)\s+intent\b/.test(text)) {
+    set("comment_focus", "intent_only");
+  }
+  if (
+    /\b(?:be|keep (?:it|(?:your |the )?(?:answers?|responses?|explanations?))|prefer)\s+(?:more\s+)?concise\b/.test(
+      text,
+    ) ||
+    /\b(?:too|overly)\s+verbose\b/.test(text)
+  ) {
+    set("explanation_depth", "concise");
+  } else if (
+    /\b(?:prefer|give|provide|use)\s+(?:more\s+)?detailed\s+(?:answers?|explanations?)\b/.test(
+      text,
+    )
+  ) {
+    set("explanation_depth", "detailed");
+  }
+  if (/\b(?:use|prefer)\s+step[- ]by[- ]step\b/.test(text)) {
+    set("output_organization", "step_by_step");
+  } else if (
+    /\b(?:use|prefer)\s+(?:a\s+)?structured\s+(?:answer|format|output)\b/.test(
+      text,
+    )
+  ) {
+    set("output_organization", "structured");
+  } else if (
+    /\b(?:use|prefer|keep)\s+(?:a\s+)?compact\s+(?:answer|format|output)\b/.test(
+      text,
+    )
+  ) {
+    set("output_organization", "compact");
+  }
+  return [...settings.values()];
+}
+
+export function promptRequestsDurablePreference(prompt) {
+  return /\b(?:always|from now on|going forward|for future tasks?|remember (?:that )?i (?:prefer|want)|my (?:lasting )?preference is|make this my default|(?:should|must)\s+(?:always|never|only))\b/i.test(
+    String(prompt ?? ""),
+  );
+}
+
+export function promptProvidesPreferenceCorrection(prompt) {
+  return /\b(?:too many comments?|fewer comments?|less verbose|too verbose|overly verbose|stop (?:using|adding|writing)|do not (?:use|add|write)|don't (?:use|add|write)|i (?:do not|don't) (?:want|like)|instead,? (?:use|keep|make))\b/i.test(
+    String(prompt ?? ""),
+  );
+}
+
+function promptDisclaimsDurablePreference(prompt) {
+  return /\b(?:(?:contrived|hypothetical|illustrative)\s+(?:example|scenario)|(?:example|scenario)\s+only|not\s+(?:a\s+)?(?:lasting\s+)?(?:preference|rule|default)|(?:do not|don't)\s+(?:save|remember|record|learn)\s+(?:this|that|it))\b/i.test(
+    String(prompt ?? ""),
+  );
+}
+
+export function promptScopesPreferenceToProject(prompt) {
+  return /\b(?:in|for)\s+(?:this|the current)\s+(?:project|repository|repo|workspace|codebase)\b/i.test(
+    String(prompt ?? ""),
+  );
+}
+
+export function genericPreferenceCaptureDirective(prompt, options = {}) {
+  const text = String(prompt ?? "");
+  if (
+    promptDisclaimsDurablePreference(text) ||
+    (!promptRequestsDurablePreference(text) &&
+      !promptProvidesPreferenceCorrection(text)) ||
+    explicitPreferenceSettingsFromPrompt(text).length > 0
+  ) {
+    return null;
+  }
+  const taskHash = createHash("sha256").update(text, "utf8").digest("hex");
+  const evidenceHash = createHash("sha256")
+    .update(
+      JSON.stringify({
+        purpose: "generic-working-preference",
+        task_hash: taskHash,
+      }),
+      "utf8",
+    )
+    .digest("hex");
+  const projectKey = promptScopesPreferenceToProject(text)
+    ? projectKeyForHook(options.env ?? process.env, options.projectPath)
+    : null;
+  const scopeFields = projectKey
+    ? `"scope":"project","project_key":"${projectKey}"`
+    : '"scope":"auto"';
+  return [
+    "Remembrance durable-preference capture:",
+    "The user stated a lasting or corrective working preference that is not one of the built-in controls. Interpret only that preference and call record_preference once. Do not ask the user to classify it.",
+    'Use setting {"key":"<presentation|workflow|strategy_selection>.<stable_concept>","value":"<stable_behavior_id>","label":"<short name>","behavior":"<concise normalized behavior>","effect":"presentation|workflow|strategy_selection","strength":"prefer|avoid","definition_version":1}. This vocabulary is extensible; do not force the preference into a built-in category.',
+    `Use ${scopeFields}, "source_category":"explicit_user", "evidence_hash":"${evidenceHash}", "task_hash":"${taskHash}", and "confidence":1.`,
+    "Never send the raw prompt or private task details. Never encode a request to weaken safety, authorization, privacy, required skill steps, validation, or review; those constraints remain authoritative.",
+  ].join("\n");
+}
+
+export async function recordExplicitPreferenceObservations(
+  prompt,
+  options = {},
+) {
+  if (promptDisclaimsDurablePreference(prompt)) return 0;
+  const durable = promptRequestsDurablePreference(prompt);
+  const corrective = promptProvidesPreferenceCorrection(prompt);
+  if (!durable && !corrective) return 0;
+  const settings = explicitPreferenceSettingsFromPrompt(prompt);
+  if (settings.length === 0) return 0;
+  const env = options.env ?? process.env;
+  const runtime = normalizeRuntime(options.runtime);
+  const access = resolveApiAccessSnapshot(env);
+  const credential = access.credential;
+  if (isUnusableConfigurationSource(credential.source) || !credential.apiKey) {
+    return 0;
+  }
+  let principalSession = readHookPrincipalSession(runtime, env, access);
+  if (!principalSession?.token) {
+    principalSession = await warmPrincipalSession(
+      {
+        runtime,
+        hostSurface: runtimeHostSurface(runtime, env),
+        fetchImpl: options.fetchImpl ?? fetch,
+        apiAccess: access,
+      },
+      env,
+    );
+  }
+  if (!principalSession?.token) return 0;
+  // A direct correction is explicit evidence even when the user did not say
+  // "remember this". Persist it immediately so one correction supersedes a
+  // learned profile; genuinely inferred behavior still enters through the
+  // topology/observation path and must satisfy the multi-task confidence gate.
+  const sourceCategory = "explicit_user";
+  const projectKey = promptScopesPreferenceToProject(prompt)
+    ? projectKeyForHook(env, options.projectPath)
+    : null;
+  const taskHash = createHash("sha256")
+    .update(String(prompt), "utf8")
+    .digest("hex");
+  let refreshPromise = null;
+  const refreshSession = async () => {
+    refreshPromise ??= (async () => {
+      clearHookPrincipalSession(runtime, env, access);
+      return warmPrincipalSession(
+        {
+          runtime,
+          hostSurface: runtimeHostSurface(runtime, env),
+          fetchImpl: options.fetchImpl ?? fetch,
+          apiAccess: access,
+        },
+        env,
+      );
+    })();
+    return refreshPromise;
+  };
+  const results = await Promise.all(
+    settings.map(async (setting) => {
+      const controller = new AbortController();
+      const timeout = setTimeout(
+        () => controller.abort(),
+        DEFAULT_DIRECTIVE_EVENT_TIMEOUT_MS,
+      );
+      timeout.unref?.();
+      try {
+        const evidenceHash = createHash("sha256")
+          .update(
+            JSON.stringify({
+              setting,
+              task_hash: taskHash,
+              source: "hook",
+              source_category: sourceCategory,
+              project_key: projectKey,
+            }),
+            "utf8",
+          )
+          .digest("hex");
+        const submit = (token) =>
+          (options.fetchImpl ?? fetch)(
+            `${access.apiConfiguration.apiUrl}/api/v1/agent/preferences`,
+            {
+              method: "POST",
+              headers: {
+                "content-type": "application/json",
+                "user-agent": clientUserAgent(options.userAgent),
+                "x-remembrance-api-key": credential.apiKey,
+                "x-remembrance-principal-session": token,
+              },
+              body: JSON.stringify({
+                setting,
+                scope: projectKey
+                  ? "project"
+                  : principalSession.member_linked
+                    ? durable
+                      ? "member"
+                      : "member_runtime"
+                    : "installation",
+                source_category: sourceCategory,
+                evidence_hash: evidenceHash,
+                task_hash: taskHash,
+                ...(projectKey ? { project_key: projectKey } : {}),
+                confidence: 1,
+              }),
+              signal: controller.signal,
+            },
+          );
+        let response = await submit(principalSession.token);
+        if (response?.status === 401 || response?.status === 403) {
+          const refreshed = await refreshSession();
+          if (refreshed?.token) {
+            principalSession = refreshed;
+            response = await submit(refreshed.token);
+          }
+        }
+        return response?.ok === true;
+      } catch {
+        // Preference capture is advisory and cannot block the prompt hook.
+        return false;
+      } finally {
+        clearTimeout(timeout);
+      }
+    }),
+  );
+  return results.filter(Boolean).length;
+}
+
 export function sharedConfigCredentialNotice(env = process.env) {
   const source = resolveApiCredential(env).source;
   if (source === "unusable_environment") {
@@ -2655,6 +4321,10 @@ export function sharedConfigCredentialNotice(env = process.env) {
 }
 
 export function resolveApiConfiguration(env = process.env) {
+  return resolveApiAccessSnapshot(env).apiConfiguration;
+}
+
+function resolveApiConfigurationFromSnapshot(env, shared) {
   const environmentUrl = String(env.REMEMBRANCE_API_URL ?? "").trim();
   if (environmentUrl) {
     const normalized = normalizeApiUrl(environmentUrl, env);
@@ -2666,34 +4336,23 @@ export function resolveApiConfiguration(env = process.env) {
           issue: normalized.issue ?? "invalid_url",
         };
   }
-  const path = remembranceConfigPath(env);
-  if (!existsSync(path)) {
+  if (!shared.present) {
     return { apiUrl: DEFAULT_API_URL, source: "default" };
   }
-  try {
-    const parsed = JSON.parse(
-      readSecureHookFile(path, MAX_LOCAL_CONFIG_BYTES),
-    );
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return {
+  if (!shared.parsed) {
+    return { apiUrl: DEFAULT_API_URL, source: "unusable_shared_config" };
+  }
+  if (!Object.prototype.hasOwnProperty.call(shared.parsed, "apiUrl")) {
+    return { apiUrl: DEFAULT_API_URL, source: "default" };
+  }
+  const normalized = normalizeApiUrl(shared.parsed.apiUrl, env);
+  return normalized.apiUrl && !normalized.issue
+    ? { apiUrl: normalized.apiUrl, source: "shared_config" }
+    : {
         apiUrl: DEFAULT_API_URL,
         source: "unusable_shared_config",
+        issue: normalized.issue ?? "invalid_url",
       };
-    }
-    if (!Object.prototype.hasOwnProperty.call(parsed, "apiUrl")) {
-      return { apiUrl: DEFAULT_API_URL, source: "default" };
-    }
-    const normalized = normalizeApiUrl(parsed.apiUrl, env);
-    return normalized.apiUrl && !normalized.issue
-      ? { apiUrl: normalized.apiUrl, source: "shared_config" }
-      : {
-          apiUrl: DEFAULT_API_URL,
-          source: "unusable_shared_config",
-          issue: normalized.issue ?? "invalid_url",
-        };
-  } catch {
-    return { apiUrl: DEFAULT_API_URL, source: "unusable_shared_config" };
-  }
 }
 
 function apiUrl(env) {
@@ -2738,7 +4397,10 @@ function normalizeApiUrl(value, env = process.env) {
 }
 
 function credentialForApiDestination(credential, configuration) {
-  if (!credential.apiKey || isUnusableConfigurationSource(configuration.source)) {
+  if (
+    !credential.apiKey ||
+    isUnusableConfigurationSource(configuration.source)
+  ) {
     return credential.apiKey
       ? unusableDestinationCredential()
       : { apiKey: "", source: credential.source };
@@ -2811,7 +4473,9 @@ function isPrivateDestinationHostname(hostname) {
 }
 
 function normalizeHostname(hostname) {
-  return String(hostname).replace(/^\[|\]$/g, "").toLowerCase();
+  return String(hostname)
+    .replace(/^\[|\]$/g, "")
+    .toLowerCase();
 }
 
 function readSecureHookFile(path, maxBytes) {