@peopl-health/nexus 5.67.2 → 5.68.0-dev.12044

package/lib/clinical/AssistantProcessor.js

@@ -127,10 +127,9 @@ class AssistantProcessor {
 
       try {
         if (!runOptions.shadow && isPatientTurn) {
-          await cancelPendingFollowUps({ code: thread.code, trace: ctx?.trace || null });
-        } else {
-          followUpSnapshot = await readPendingFollowUpsForPatient({ code: thread.code });
+          await cancelPendingFollowUps({ code: thread.code, trace: ctx?.trace || null, recoveryOnly: true });
         }
+        followUpSnapshot = await readPendingFollowUpsForPatient({ code: thread.code });
       } catch (error) {
         logger.warn('[AssistantProcessor] follow-up state update failed', { code: thread.code, error: error.message });
         // A proactive turn must not create or send a second follow-up while the plan read is stale.

package/lib/clinical/providers/BaseLLMProvider.js

@@ -317,10 +317,10 @@ class BaseLLMProvider {
       role: 'developer',
       content: [
         '## Seguimiento, recordatorio y contingencia — no son intercambiables',
-        '- SEGUIMIENTO: tú decides volver a contactar para mantener continuidad cuando ya no falta un dato clínico que pueda cambiar el riesgo. Elige cuándo y redacta la pregunta exacta para esa persona. Usa schedulePatientReminder con reminder_type seguimiento y la utility_basis concreta. Prográmalo cuando indicaste una acción (medicamento de venta libre, autocuidado, educación) cuyo efecto se ve en 24–72 h; cuando la paciente ya dio el dato y quieres saber si el síntoma vuelve o cruza un umbral que nombraste; cuando cerraste un episodio que vale la pena revisar; o cuando tiene un evento próximo (inicio de tratamiento, cita, infusión) cuyo resultado importa. Si en este turno le indicaste un medicamento, una medida de autocuidado o que contacte a alguien (dentista, su médico, urgencias), o le transmitiste un tratamiento que indicó el equipo, decide el seguimiento en este mismo turno: si no queda una red ni un seguimiento activo para ese síntoma, programa uno a 24–48 h con utility_basis agreed_action: si fue un medicamento o una medida, para saber si funcionó; si fue una cita o un estudio, para saber si pudo agendarlo o si ya fue y cuándo. Pedirle «avísame cómo te va» no sustituye ese seguimiento. No lo programes por inactividad sola; cualquier actividad posterior de la paciente lo cancela y entonces respondes a lo nuevo.',
+        '- SEGUIMIENTO: tú decides volver a contactar para mantener continuidad cuando ya no falta un dato clínico que pueda cambiar el riesgo. Elige cuándo y redacta la pregunta exacta para esa persona. Usa schedulePatientReminder con reminder_type seguimiento y la utility_basis concreta. Prográmalo cuando indicaste una acción (medicamento de venta libre, autocuidado, educación) cuyo efecto se ve en 24–72 h; cuando la paciente ya dio el dato y quieres saber si el síntoma vuelve o cruza un umbral que nombraste; cuando cerraste un episodio que vale la pena revisar; o cuando tiene un evento próximo (inicio de tratamiento, cita, infusión) cuyo resultado importa. Si en este turno le indicaste un medicamento, una medida de autocuidado o que contacte a alguien (dentista, su médico, urgencias), o le transmitiste un tratamiento que indicó el equipo, decide el seguimiento en este mismo turno: si no queda una red ni un seguimiento activo para ese síntoma, programa uno a 24–48 h con utility_basis agreed_action: si fue un medicamento o una medida, para saber si funcionó; si fue una cita o un estudio, para saber si pudo agendarlo o si ya fue y cuándo. Pedirle «avísame cómo te va» no sustituye ese seguimiento. No lo programes por inactividad sola. Si la paciente vuelve a escribir antes, el seguimiento sigue pendiente y lo verás en «Seguimientos ya programados»: mantenlo, actualízalo o cancélalo según lo que cambió.',
         '- RECORDATORIO: sólo existe si la paciente pidió explícitamente que se lo recuerdes o aceptó explícitamente tu oferta de recordárselo. Usa schedulePatientReminder con el tipo concreto (medicamento, cita, examen u otros) y exactamente a la hora que pidió. No lo adelantes para que llegue antes de una cita o tarea salvo que ella haya pedido ese adelanto. No infieras un recordatorio porque mencionó o agendó algo, ni lo uses para preguntar cómo sigue o vigilar incertidumbre clínica.',
         '- CONTINGENCIA: protege una incertidumbre clínica todavía abierta; falta un dato u observación que podría cambiar el grado, la urgencia o la conducta. Usa setContingencyPlan: la contingencia define qué se espera, cuánto silencio tolerar y, si corresponde, la escalada posterior. Nunca la sustituyas por seguimiento ni por recordatorio.',
-        'Regla de desempate: si esperas saber “cómo sigue” por continuidad, es seguimiento; si la paciente pidió explícitamente o aceptó que le recuerdes hacer algo, es recordatorio; si esperas un dato porque no tenerlo podría volver insegura la conducta, es contingencia. Una tarea acordada o agendada sin esa petición no es un recordatorio. Una contingencia activa gana sólo mientras siga faltando su dato; cuando la resuelves porque la paciente ya lo dio o porque la preocupación quedó atendida, la vigilancia que queda es un seguimiento, no una red rearmada ni un cierre del tema. Una indicación del equipo de agendar o hacerse una visita o un estudio no resuelve por sí sola una red cuyo dato sigue faltando: la red se mantiene tal como está y no programes un seguimiento aparte mientras siga activa (no se enviaría): pregunta por la visita o el estudio cuando la paciente vuelva a escribir o cuando la red se resuelva.',
+        'Regla de desempate: si esperas saber “cómo sigue” por continuidad, es seguimiento; si la paciente pidió explícitamente o aceptó que le recuerdes hacer algo, es recordatorio; si esperas un dato porque no tenerlo podría volver insegura la conducta, es contingencia. Una tarea acordada o agendada sin esa petición no es un recordatorio. Una contingencia activa gana sólo mientras siga faltando su dato; cuando la resuelves porque la paciente ya lo dio o porque la preocupación quedó atendida, la vigilancia que queda es un seguimiento, no una red rearmada ni un cierre del tema. Una indicación del equipo de agendar o hacerse una visita o un estudio no resuelve por sí sola una red cuyo dato sigue faltando: la red se mantiene tal como está y, además, programa el seguimiento sobre la visita o el estudio: una red abierta no lo detiene.',
       ].join('\n'),
     }];
   }
@@ -440,7 +440,15 @@ class BaseLLMProvider {
     const pending = Array.isArray(promptVariables?.active_follow_ups) ? promptVariables.active_follow_ups : [];
     if (!pending.length) return [];
     const rows = pending.map((item) => `- ${sanitizeInlineText(item.reminderId)} a las ${sanitizeInlineText(item.fireAt)}: ${sanitizeInlineText(item.message)}`);
-    return [{ role: 'developer', content: ['## Seguimientos ya programados', ...rows, 'No programes ni envíes otro seguimiento que cruce uno de estos planes; actualiza el existente si cambió.'].join('\n') }];
+    return [{
+      role: 'developer',
+      content: [
+        '## Seguimientos ya programados',
+        ...rows,
+        'Siguen pendientes aunque la paciente haya vuelto a escribir. Si esta conversación ya respondió su pregunta o la volvió innecesaria, cancélalo (schedulePatientReminder con reminder_action_type cancel y su reminder_id); si cambió lo que hay que preguntar o cuándo, actualízalo; si sigue valiendo, déjalo. No crees otro seguimiento que lo cruce.',
+      ].join('\n'),
+      [TAIL_PLACEMENT]: true,
+    }];
   }
 
   _buildClinicalMessage(promptVariables, interpolatedVariables = []) {

package/lib/clinical/services/clinicalAirtableService.js

@@ -48,6 +48,9 @@ const REMINDER_TYPE_TO_AIRTABLE = {
 // of pending rows so the predicate cannot drift between them.
 const PENDING_ROW_FILTER = 'IF({is_active}, "true", "false") = "true", IF({is_sent}, "true", "false") = "false"';
 const ROUTINE_OUTREACH_FILTER = 'OR({type} = "seguimiento", LEFT({schedule_id}, 9) = "recovery_")';
+const RECOVERY_FILTER = 'LEFT({schedule_id}, 9) = "recovery_"';
+// The fire trigger opens 5 min either side of reminder_date; a row still pending after that was not sent.
+const FIRE_TRIGGER_GRACE_MS = 10 * 60 * 1000;
 
 // intake.source only offers self|doctor; team_relay carries "según médico" authority.
 const INTAKE_SOURCE_TO_AIRTABLE = {
@@ -432,7 +435,9 @@ async function hasPendingReminderForPatient({ code, withinMinutes }) {
   return Array.isArray(rows) && rows.length > 0;
 }
 
-async function readPendingFollowUpsForPatient({ code }) {
+// A row whose fire time passed unsent was skipped and is never re-triggered, and one past its expiry
+// can never fire; neither is a plan the agent or the create guard should see.
+async function readPendingFollowUpsForPatient({ code, now = new Date() }) {
   if (!code) return [];
   const rows = await airtableService.getRecordByFilter(
     Monitoreo_ID,
@@ -447,7 +452,30 @@ async function readPendingFollowUpsForPatient({ code }) {
     message: row.description || '',
     expiresAt: row.expires_at || null,
     windowReasoning: row.window_reasoning || null,
-  }));
+  })).filter((plan) => !isAtOrBefore(plan.expiresAt, now) && !isAtOrBefore(plan.fireAt, new Date(now).getTime() - FIRE_TRIGGER_GRACE_MS));
+}
+
+function isAtOrBefore(when, now) {
+  const at = when ? new Date(when).getTime() : NaN;
+  return Number.isFinite(at) && at <= new Date(now).getTime();
+}
+
+/*
+ * Another check-in about to reach this patient: a net's patient check-in or another routine
+ * follow-up, due within `withinMinutes` either side of now so two rows firing together see each
+ * other. Patient-requested reminders are left out; they are what she asked for.
+ */
+async function hasCheckInNear({ code, withinMinutes, excludeReminderId }) {
+  const window = Number(withinMinutes);
+  if (!code || !Number.isFinite(window) || window <= 0) return false;
+  const rows = await airtableService.getRecordByFilter(
+    Monitoreo_ID,
+    'reminder',
+    `AND(${fieldEquals('whatsapp_id', code)}, ${PENDING_ROW_FILTER}, OR(RIGHT({schedule_id}, 8) = "-patient", ${ROUTINE_OUTREACH_FILTER}), NOT(${fieldEquals('schedule_id', excludeReminderId)}), ABS(DATETIME_DIFF({reminder_date}, NOW(), 'minutes')) <= ${window})`,
+    null,
+    ['schedule_id'],
+  );
+  return Array.isArray(rows) && rows.length > 0;
 }
 
 async function readPendingReminderForPatient({ code, reminderId }) {
@@ -470,14 +498,37 @@ async function readPendingReminderForPatient({ code, reminderId }) {
   } : null;
 }
 
-async function cancelPendingFollowUps({ code, trace = null, reason = 'patient_replied' }) {
+// Patient activity retires only turn-loss recovery rows; a seguimiento stays for the agent to keep, update or cancel.
+async function cancelPendingFollowUps({ code, trace = null, reason = 'patient_replied', recoveryOnly = false }) {
   return standDownRow({
     code,
     trace,
     table: 'reminder',
     planId: null,
     standDownReason: reason,
-    filter: `AND(${fieldEquals('whatsapp_id', code)}, ${ROUTINE_OUTREACH_FILTER}, ${PENDING_ROW_FILTER})`,
+    filter: `AND(${fieldEquals('whatsapp_id', code)}, ${recoveryOnly ? RECOVERY_FILTER : ROUTINE_OUTREACH_FILTER}, ${PENDING_ROW_FILTER})`,
+  });
+}
+
+async function cancelFollowUp({ code, reminderId, trace = null, reason, isLive = null }) {
+  if (!code || !reminderId) return false;
+  return auditedWrite({
+    trace,
+    code,
+    isLive,
+    table: 'reminder',
+    meta: { reminderId, standDown: true },
+    write: async () => {
+      const updated = await airtableService.updateRecordByFilter(
+        Monitoreo_ID,
+        'reminder',
+        `AND(${fieldEquals('whatsapp_id', code)}, ${fieldEquals('schedule_id', reminderId)}, ${ROUTINE_OUTREACH_FILTER}, ${PENDING_ROW_FILTER})`,
+        { is_active: false, stand_down_reason: reason },
+        code,
+      );
+      if (!updated?.length) throw new Error(`pending follow-up ${reminderId} was not stood down`);
+      return updated;
+    },
   });
 }
 
@@ -637,6 +688,8 @@ module.exports = {
   readPendingFollowUpsForPatient,
   readPendingReminderForPatient,
   cancelPendingFollowUps,
+  cancelFollowUp,
+  hasCheckInNear,
   markReminderSent,
   recordContingencyEscalation,
   cancelContingencyRows,

package/lib/clinical/tools/schedulePatientReminderTool.js

@@ -2,7 +2,7 @@ const moment = require('moment-timezone');
 
 const { isShadowRun } = require('../helpers/shadowHelper');
 const { dispatchReminder } = require('../services/reminderDispatchService');
-const { recordReminder, readPendingFollowUpsForPatient } = require('../services/clinicalAirtableService');
+const { recordReminder, readPendingFollowUpsForPatient, cancelFollowUp } = require('../services/clinicalAirtableService');
 const { isWithinTriageProtectionWindow } = require('../services/outreachSweepService');
 const { UTILITY_BASES, sanitizeVariable } = require('../services/outreachCarrierService');
 const { logger } = require('../../utils/logger');
@@ -10,7 +10,7 @@ const { DEFAULT_TIMEZONE } = require('../../utils/scheduleUtils');
 
 const definition = {
   name: 'schedulePatientReminder',
-  description: '**Does:** Creates or updates one agent-authored WhatsApp reminder. An ordinary reminder (medication, appointment, exam, or other task) is allowed only when the patient explicitly asks for or explicitly accepts that reminder. Do not infer a reminder merely because the patient mentioned or scheduled something. Schedule it at the exact date and time the patient requested. Never move it earlier to precede an appointment or task unless the patient explicitly requested that offset. On any patient conversation—not only a triage—or on a proactive review, use reminder_type seguimiento when this turn decides both when to check in again and the exact patient-facing words. Schedule one whenever a later contact materially helps continuity and has a concrete utility_basis — typically: you recommended an action (OTC medication, self-care, education) whose effect shows within 24–72h; the patient already gave the deciding datum and you want to know whether the symptom comes back or crosses a threshold you named; you closed a symptom episode worth checking on; or the patient has an upcoming event (starting a treatment, an appointment, an infusion) whose outcome matters. Inactivity alone is not a basis.\\n\\nA seguimiento is a lightweight engagement plan: it is capped at 600 characters, never truncated, expires 24 hours after its chosen fire time, and cannot be created while another seguimiento is active. Any patient activity cancels it.\\n\\n**When NOT to call:** when the reminder guards unresolved clinical uncertainty, use setContingencyPlan instead; that plan owns its silence window and lifecycle. Never update a contingency-owned `plan_…-patient` reminder here.\\n\\nRequired: future patient-local reminder_date, reminder_description, reminder_type, action type, reminder_id for updates, and utility_basis for seguimiento.',
+  description: '**Does:** Creates or updates one agent-authored WhatsApp reminder. An ordinary reminder (medication, appointment, exam, or other task) is allowed only when the patient explicitly asks for or explicitly accepts that reminder. Do not infer a reminder merely because the patient mentioned or scheduled something. Schedule it at the exact date and time the patient requested. Never move it earlier to precede an appointment or task unless the patient explicitly requested that offset. On any patient conversation—not only a triage—or on a proactive review, use reminder_type seguimiento when this turn decides both when to check in again and the exact patient-facing words. Schedule one whenever a later contact materially helps continuity and has a concrete utility_basis — typically: you recommended an action (OTC medication, self-care, education) whose effect shows within 24–72h; the patient already gave the deciding datum and you want to know whether the symptom comes back or crosses a threshold you named; you closed a symptom episode worth checking on; or the patient has an upcoming event (starting a treatment, an appointment, an infusion) whose outcome matters. Inactivity alone is not a basis.\\n\\nA seguimiento is a lightweight engagement plan: it is capped at 600 characters, never truncated, fires at most 48 hours ahead, expires 24 hours after its chosen fire time, and cannot be created while another seguimiento is active. It stays pending when the patient writes again: later turns list it under «Seguimientos ya programados» so you keep it, update it, or cancel it (reminder_action_type cancel) when the conversation already answered it.\\n\\n**When NOT to call:** when the reminder guards unresolved clinical uncertainty, use setContingencyPlan instead; that plan owns its silence window and lifecycle. Never update a contingency-owned `plan_…-patient` reminder here.\\n\\nRequired: future patient-local reminder_date, reminder_description, reminder_type, action type, reminder_id for updates, and utility_basis for seguimiento.',
   strict: true,
   parameters: {
     type: 'object',
@@ -26,12 +26,12 @@ const definition = {
       reminder_type: {
         type: 'string',
         enum: ['medicamento', 'exámen', 'examen', 'cita', 'check_in', 'seguimiento', 'otros'],
-        description: '\'seguimiento\' = the agent chooses to contact later with an exact continuity/engagement question once no datum that could raise the grade is still missing; patient activity cancels it. \'medicamento\', \'cita\', \'examen\'/\'exámen\', and \'otros\' require an explicit patient request or acceptance to be reminded. A mention or scheduled event alone is insufficient. \'check_in\' is legacy compatibility; use seguimiento for new agent-owned follow-ups. Never use this tool to guard unresolved clinical uncertainty—use setContingencyPlan.',
+        description: '\'seguimiento\' = the agent chooses to contact later with an exact continuity/engagement question once no datum that could raise the grade is still missing; it stays pending until sent, expired, updated or cancelled by you. \'medicamento\', \'cita\', \'examen\'/\'exámen\', and \'otros\' require an explicit patient request or acceptance to be reminded. A mention or scheduled event alone is insufficient. \'check_in\' is legacy compatibility; use seguimiento for new agent-owned follow-ups. Never use this tool to guard unresolved clinical uncertainty—use setContingencyPlan.',
       },
       reminder_action_type: {
         type: 'string',
-        enum: ['create', 'update'],
-        description: '\'create\' = new reminder. \'update\' = modify an existing reminder (change date/time/description) — pass its id in `reminder_id`.',
+        enum: ['create', 'update', 'cancel'],
+        description: '\'create\' = new reminder. \'update\' = modify an existing reminder (change date/time/description) — pass its id in `reminder_id`. \'cancel\' = retire a pending seguimiento that the conversation already answered or made unnecessary — pass its id in `reminder_id`; the date and description are ignored.',
       },
       reminder_id: {
         type: ['string', 'null'],
@@ -51,6 +51,8 @@ const definition = {
 const REMINDER_TYPES = definition.parameters.properties.reminder_type.enum;
 const ACTION_TYPES = definition.parameters.properties.reminder_action_type.enum;
 
+const MAX_FOLLOW_UP_LEAD_HOURS = 48;
+
 const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?$/;
 const FIRE_AT_FORMATS = ['YYYY-MM-DDTHH:mm:ss', 'YYYY-MM-DDTHH:mm', 'YYYY-MM-DD HH:mm:ss', 'YYYY-MM-DD HH:mm'];
 
@@ -76,6 +78,9 @@ async function handler(args = {}, context = {}) {
     }
     const { turnId } = runtime;
 
+    const requestedAction = (args?.reminder_action_type || '').toLowerCase();
+    if (requestedAction === 'cancel') return await cancelSeguimiento(args, runtime);
+
     const reminderDate = (args?.reminder_date || '').trim();
     const description = sanitizeVariable(args?.reminder_description || '');
     if (!reminderDate || !description) {
@@ -116,6 +121,9 @@ async function handler(args = {}, context = {}) {
     if (!fireMoment.isAfter(moment.tz(timeZone))) {
       return JSON.stringify({ success: false, error: `reminder_date must be in the future (${timeZone}) — got '${reminderDate}'.`, data: {} });
     }
+    if (reminderType === 'seguimiento' && fireMoment.isAfter(moment.tz(timeZone).add(MAX_FOLLOW_UP_LEAD_HOURS, 'hours'))) {
+      return JSON.stringify({ success: false, error: `seguimiento must fire within ${MAX_FOLLOW_UP_LEAD_HOURS} hours; ask about a later event in a seguimiento closer to it.`, data: {} });
+    }
     const isRoutineOutreach = reminderType === 'seguimiento' || laneType === 'otros';
     if (isRoutineOutreach && isWithinTriageProtectionWindow(fireMoment.toDate())) {
       return JSON.stringify({ success: false, error: 'routine outreach cannot be scheduled during the 07:30-11:00 triage protection window; choose 11:00 or later.', data: {} });
@@ -202,6 +210,26 @@ async function handler(args = {}, context = {}) {
   }
 }
 
+async function cancelSeguimiento(args, runtime) {
+  const reminderId = typeof args?.reminder_id === 'string' ? args.reminder_id.trim() : '';
+  if (!reminderId) {
+    return JSON.stringify({ success: false, error: 'cancel requires the reminder_id of a pending seguimiento.', data: {} });
+  }
+  const { patientCode, trace } = runtime;
+  const notPending = () => JSON.stringify({ success: false, error: 'not_pending — only a pending seguimiento listed under «Seguimientos ya programados» can be cancelled.', data: { reminder_id: reminderId } });
+  if (!reminderId.startsWith('followup_')) return notPending();
+  if (patientCode && !isShadowRun()) {
+    const pending = await readPendingFollowUpsForPatient({ code: patientCode });
+    if (!pending.some((plan) => plan.reminderId === reminderId)) return notPending();
+    if (!await cancelFollowUp({ code: patientCode, reminderId, trace, reason: 'agent_cancelled', isLive: runtime.isLive?.bind(runtime) })) {
+      return JSON.stringify({ success: false, error: 'seguimiento cancellation failed; retry', data: { reminder_id: reminderId } });
+    }
+  }
+  const existing = Array.isArray(trace.signals?.reminderIntents) ? trace.signals.reminderIntents : [];
+  trace.setSignals({ reminderIntents: [...existing, { reminderId, reminderType: 'seguimiento', actionType: 'cancel', channel: 'whatsapp' }] });
+  return JSON.stringify({ success: true, data: { reminder_id: reminderId, action_type: 'cancel' } });
+}
+
 module.exports = {
   definition,
   handler,

package/lib/clinical/tools/setContingencyPlanTool.js

@@ -12,7 +12,7 @@ const MAX_PATIENT_SILENCE_MIN = 1380;
 
 const definition = {
   name: 'setContingencyPlan',
-  description: `**Does:** Manages the contingency safety net guarding an open case or cluster, selected via \`action\`. A net is a single promise: if the patient goes quiet, you write to them again.\n- \`arm\` (default): arms a new net — a CarePlan anchor plus the follow-up check-in that goes out to the patient after true silence.\n- \`resolve\`: stands an active net down because this turn's conversation addressed the guarded concern, or it is no longer clinically relevant. Requires \`plan_id\` + \`resolution_reasoning\`.\n- \`rearm\`: replaces the target's active net with this new definition (fresh silence window anchored now) — same required fields as \`arm\`. Use when new information changes the concern, window, or message.\n\n**Required inputs:** \`arm\`/\`rearm\`: \`concern\`, \`awaiting_characterization\`; at least one of \`related_case_id\` / \`related_cluster_id\`; \`patient_followup_reminder\` \`${STEP_SHAPE}\` (message + a positive \`fires_after_silence_minutes\` <= ${MAX_PATIENT_SILENCE_MIN}, plus \`window_reasoning\`: one sentence on why that wait). \`resolve\`: \`plan_id\` + \`resolution_reasoning\`.\n\n**When to call:** \`arm\` when, read against the symptom's CTCAE grade scale, a datum is still missing that could put the case at a grade above your current read. If everything needed to settle the severity is already known, do not arm. The rubric is the test, not how alarming the symptom sounds.\n- Missing information could move it from G1 to G2/G3 → arm, and wait for exactly that datum.\n- Everything needed to rule out the higher grades is already known → do not arm.\n- Serious AND fully assessed → escalate. A finished assessment needs a person, not a check-in.\n\nFind the gap in the \`grade_scale\` you graded against: which clause of the next grade up can you neither confirm nor rule out? Name that datum in \`awaiting_characterization\`, concrete enough that the next turn can tell whether their message addressed it. It is an answer the patient still owes about the symptom as it stands now — what qualifies it is that it moves the grade, not the form it takes. A pending detail that cannot change the grade (an administrative confirmation, a name, an appointment) is not a reason to arm. Neither is a watch that starts after the patient already gave that datum — whether the symptom comes back, crosses a threshold you named, or eases with what you recommended: that is continuity, not uncertainty, so schedule a \`seguimiento\` with \`schedulePatientReminder\` instead, and do not re-arm a net you just resolved to cover it. Set \`resolves_on\` to match: \`reply\` for an answer they owe, \`observation\` for an event their next message may not carry.\n\nWaiting on the care team does NOT satisfy this test — a non-routine escalation normally arms its own net, so team follow-up is not this tool's job. A \`routine\` escalation does not — it routes to the team's ticket lane and leaves no net, so on those turns the ceiling test decides on its own merits. Do not condition it on predicting whether the patient will go quiet: that cannot be known, and a net they turn out not to need never reaches them — it steps aside every time they write. \`resolve\` when the patient's message answered what the net was waiting to observe; \`rearm\` when the net's definition went stale. Resolve a net only when its awaited datum arrived or the concern it guards was addressed. A care-team indication to book or do a visit or test does not by itself address it: if the net still awaits a grade-changing observation, keep the net as it is and do not schedule a separate seguimiento while it is active (it would not be delivered); ask about the visit or test when the patient next writes or once the net resolves. When a net is resolved and the team gave an indication, what remains open is the indication: schedule a \`seguimiento\` with \`schedulePatientReminder\` (\`utility_basis: agreed_action\`) at 24–48 h instead of treating the topic as closed — for a medication or measure, to learn whether it works; for a visit or test, to learn whether it was booked or done and when (ask about the result later, once it has happened).\n\n**When NOT to call:** \`arm\` on a target that already has an active plan (fails hard — use \`resolve\` or \`rearm\`) or whose case/cluster is closed/dissolved; \`resolve\` while the concern is still unobserved (closing the case retires its net automatically). This tool does NOT notify the care team — to reach a human, use the escalation tools.\n\n**Returns:** \`arm\`/\`rearm\` → \`{plan_id}\` (\`rearm\` adds \`superseded_plan_ids\` when it replaced a net). \`resolve\` → \`{plan_id}\`, with \`already_resolved: true\` when the net was retired earlier — an idempotent success, not an error. Fails hard with \`case_not_found_or_wrong_patient\` / \`cluster_not_found_or_wrong_patient\`, \`target_not_open\`, \`active_plan_already_exists_for_case\` / \`_for_cluster\` (arm only), \`plan_not_found_or_wrong_patient\`, \`store_failed_retry_next_turn\`, or \`stand_down_failed_retry_next_turn\`.\n\n**Side effects:** records the action on the turn trace; writes the FHIR CarePlan + patient CommunicationRequest + Provenance; arms or deactivates the dispatch row — the check-in goes out over WhatsApp only if the patient stayed silent through its window, and is pushed back each time they write. Nets also stand down when their case closes or cluster dissolves, and expire on their own after a bounded multiple of the check-in window.`,
+  description: `**Does:** Manages the contingency safety net guarding an open case or cluster, selected via \`action\`. A net is a single promise: if the patient goes quiet, you write to them again.\n- \`arm\` (default): arms a new net — a CarePlan anchor plus the follow-up check-in that goes out to the patient after true silence.\n- \`resolve\`: stands an active net down because this turn's conversation addressed the guarded concern, or it is no longer clinically relevant. Requires \`plan_id\` + \`resolution_reasoning\`.\n- \`rearm\`: replaces the target's active net with this new definition (fresh silence window anchored now) — same required fields as \`arm\`. Use when new information changes the concern, window, or message.\n\n**Required inputs:** \`arm\`/\`rearm\`: \`concern\`, \`awaiting_characterization\`; at least one of \`related_case_id\` / \`related_cluster_id\`; \`patient_followup_reminder\` \`${STEP_SHAPE}\` (message + a positive \`fires_after_silence_minutes\` <= ${MAX_PATIENT_SILENCE_MIN}, plus \`window_reasoning\`: one sentence on why that wait). \`resolve\`: \`plan_id\` + \`resolution_reasoning\`.\n\n**When to call:** \`arm\` when, read against the symptom's CTCAE grade scale, a datum is still missing that could put the case at a grade above your current read. If everything needed to settle the severity is already known, do not arm. The rubric is the test, not how alarming the symptom sounds.\n- Missing information could move it from G1 to G2/G3 → arm, and wait for exactly that datum.\n- Everything needed to rule out the higher grades is already known → do not arm.\n- Serious AND fully assessed → escalate. A finished assessment needs a person, not a check-in.\n\nFind the gap in the \`grade_scale\` you graded against: which clause of the next grade up can you neither confirm nor rule out? Name that datum in \`awaiting_characterization\`, concrete enough that the next turn can tell whether their message addressed it. It is an answer the patient still owes about the symptom as it stands now — what qualifies it is that it moves the grade, not the form it takes. A pending detail that cannot change the grade (an administrative confirmation, a name, an appointment) is not a reason to arm. Neither is a watch that starts after the patient already gave that datum — whether the symptom comes back, crosses a threshold you named, or eases with what you recommended: that is continuity, not uncertainty, so schedule a \`seguimiento\` with \`schedulePatientReminder\` instead, and do not re-arm a net you just resolved to cover it. Set \`resolves_on\` to match: \`reply\` for an answer they owe, \`observation\` for an event their next message may not carry.\n\nWaiting on the care team does NOT satisfy this test — a non-routine escalation normally arms its own net, so team follow-up is not this tool's job. A \`routine\` escalation does not — it routes to the team's ticket lane and leaves no net, so on those turns the ceiling test decides on its own merits. Do not condition it on predicting whether the patient will go quiet: that cannot be known, and a net they turn out not to need never reaches them — it steps aside every time they write. \`resolve\` when the patient's message answered what the net was waiting to observe; \`rearm\` when the net's definition went stale. Resolve a net only when its awaited datum arrived or the concern it guards was addressed. A care-team indication to book or do a visit or test does not by itself address it: if the net still awaits a grade-changing observation, keep the net as it is and also schedule the seguimiento about the visit or test — an open net does not hold it back. When a net is resolved and the team gave an indication, what remains open is the indication: schedule a \`seguimiento\` with \`schedulePatientReminder\` (\`utility_basis: agreed_action\`) at 24–48 h instead of treating the topic as closed — for a medication or measure, to learn whether it works; for a visit or test, to learn whether it was booked or done and when (ask about the result later, once it has happened).\n\n**When NOT to call:** \`arm\` on a target that already has an active plan (fails hard — use \`resolve\` or \`rearm\`) or whose case/cluster is closed/dissolved; \`resolve\` while the concern is still unobserved (closing the case retires its net automatically). This tool does NOT notify the care team — to reach a human, use the escalation tools.\n\n**Returns:** \`arm\`/\`rearm\` → \`{plan_id}\` (\`rearm\` adds \`superseded_plan_ids\` when it replaced a net). \`resolve\` → \`{plan_id}\`, with \`already_resolved: true\` when the net was retired earlier — an idempotent success, not an error. Fails hard with \`case_not_found_or_wrong_patient\` / \`cluster_not_found_or_wrong_patient\`, \`target_not_open\`, \`active_plan_already_exists_for_case\` / \`_for_cluster\` (arm only), \`plan_not_found_or_wrong_patient\`, \`store_failed_retry_next_turn\`, or \`stand_down_failed_retry_next_turn\`.\n\n**Side effects:** records the action on the turn trace; writes the FHIR CarePlan + patient CommunicationRequest + Provenance; arms or deactivates the dispatch row — the check-in goes out over WhatsApp only if the patient stayed silent through its window, and is pushed back each time they write. Nets also stand down when their case closes or cluster dissolves, and expire on their own after a bounded multiple of the check-in window.`,
   strict: false,
   parameters: {
     type: 'object',

package/lib/core/NexusMessaging.js

@@ -43,8 +43,10 @@ const {
   readPendingReminderForPatient,
   cancelPendingFollowUps,
   markReminderSent,
+  cancelFollowUp,
+  hasCheckInNear,
 } = require('../clinical/services/clinicalAirtableService');
-const { cancelContingencies, snapshotContingencies } = require('../clinical/services/contingencyDispatchService');
+const { cancelContingencies } = require('../clinical/services/contingencyDispatchService');
 const { isContingencyCancelOnReplyLive } = require('../clinical/flags/contingencyFlags');
 const { isLlmMonitorEnabled } = require('../clinical/flags/llmMonitorConfig');
 
@@ -56,6 +58,8 @@ const { invokeInteractiveRoute } = require('./interactiveRouteService');
 
 const { PhiProcessor } = require('./PhiProcessor');
 
+const FOLLOW_UP_SPACING_MIN = 180;
+
 const unbatchedRoutes = {
   __proto__: null,
   flow: 'handleFlow',
@@ -597,9 +601,10 @@ class NexusMessaging {
         const plainText = messageData.body;
         messageData = { ...messageData, body };
         if (chatId) {
-          // This is the common ingress for text, media, buttons, lists, and flows. Retire routine
-          // follow-ups here, before specialized handlers split off, so all patient activity counts.
-          await cancelPendingFollowUps({ code: chatId }).catch(error =>
+          // This is the common ingress for text, media, buttons, lists, and flows. Retire turn-loss
+          // recovery here, before specialized handlers split off, so all patient activity counts.
+          // A seguimiento survives: the next turn shows it to the agent, who keeps, updates or cancels it.
+          await cancelPendingFollowUps({ code: chatId, recoveryOnly: true }).catch(error =>
             logger.error('[processIncomingMessage] Follow-up stand-down failed', { code: chatId, error: error.message })
           );
           if (isContingencyCancelOnReplyLive()) {
@@ -1045,7 +1050,7 @@ class NexusMessaging {
    * Delivers a message the agent previously authored and scheduled with schedulePatientReminder.
    * The clock only wakes this method; it does not choose copy or timing. Running inside the same
    * patient queue as inbound WhatsApp traffic prevents an already-received message from crossing
-   * the follow-up. A clinical contingency always outranks this routine engagement plan.
+   * the follow-up.
    */
   async processScheduledFollowUp(code, { reminderId, firstName, now = new Date() } = {}) {
     if (!code || !reminderId) throw new Error('code and reminderId are required');
@@ -1068,19 +1073,20 @@ class NexusMessaging {
       }
       const expiresAt = plan.expiresAt ? new Date(plan.expiresAt) : null;
       if (expiresAt && !Number.isNaN(expiresAt.getTime()) && expiresAt.getTime() <= startedAt.getTime()) {
+        await cancelFollowUp({ code, reminderId, reason: 'expired' });
         result = { decision: 'skipped', holdReason: 'expired', accepted: false, delivered: false };
         return result;
       }
 
-      const contingencies = await snapshotContingencies({ patientCode: code });
-      if ((contingencies?.surviving || []).length > 0) {
-        result = { decision: 'skipped', holdReason: 'active_contingency', accepted: false, delivered: false };
-        return result;
-      }
-
-      const collision = await routineOutreachCollisionReason(code, { now: startedAt });
-      if (collision) {
-        result = { decision: 'skipped', holdReason: collision, accepted: false, delivered: false };
+      // An open net alone does not hold a seguimiento: the two ask different things. Hold only when
+      // another check-in is about to reach the patient. The fire trigger does not come back for a
+      // skipped row, so a skip retires it with its reason instead of leaving a plan that never sends.
+      const holdReason = await hasCheckInNear({ code, withinMinutes: FOLLOW_UP_SPACING_MIN, excludeReminderId: reminderId })
+        ? 'check_in_near'
+        : await routineOutreachCollisionReason(code, { now: startedAt });
+      if (holdReason) {
+        await cancelFollowUp({ code, reminderId, reason: `skipped_${holdReason}` });
+        result = { decision: 'skipped', holdReason, accepted: false, delivered: false };
         return result;
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "5.67.2",
+  "version": "5.68.0-dev.12044",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",