New Capability: Multi-Source Relationship Monitoring (Sentinel v2)

← Back to Capability Reports 2026-04-06

New Capability: Multi-Source Relationship Monitoring (Sentinel v2)

Date: April 6, 2026 Origin: Sentinel's session-gap-check.ts was filesystem-only, producing false alarms across the portfolio. Mead Lumber showed "68 days critical" and Caldwell showed "26 days warning" because the script only checked local session synthesis files. Both clients had recent HubSpot activity (notes, appointments) that the script ignored. The gap between what Sentinel reported and what was actually happening undermined trust in the daily-ops relationship intelligence section. Impact: Sentinel now consults HubSpot Company health properties as its primary data source, session files as secondary, and HubSpot Appointments as tertiary. 11 clients shifted from false-alarm status to accurate healthy readings. Mead Lumber: 68d critical to 5d healthy. Caldwell: 26d warning to 4d healthy. The Sentinel can now fulfill its Delegation Contract quality bar using actual last-interaction dates, not just last-synthesis-file dates.

What Was Built

1. Multi-Source session-gap-check.ts (Complete Rebuild)

The script at agents/relationship-sentinel/session-gap-check.ts was rebuilt from a single-source filesystem scanner into a three-tier multi-source engagement recency engine.

Data source hierarchy:

Tier Source What It Provides Speed
Primary HubSpot Company batch-read vf_account_health_score, vf_engagement_trend, vf_risk_factors, notes_last_updated Single batch API call for all clients
Secondary Local session files clients/{slug}/sessions/*.md most recent file date Filesystem read, instant
Tertiary HubSpot Appointment associations Per-company appointment history with hs_appointment_start dates Per-client API calls (--detail mode only)

Resolution logic: The script takes the LATER of HubSpot activity date and session file date as "last interaction." Every client in the output includes source attribution — whether HubSpot or the session file provided the more recent date.

Architecture:

  • Loads all client configs and session file dates locally (fast, no API)
  • Batch-reads all HubSpot Company records in a single API call using the company IDs from config.yaml
  • Merges the two data sources per client, picking the later date
  • In --detail mode, additionally queries HubSpot Appointment associations per company for precise meeting dates
  • Outputs sorted by severity: critical, warning, no_data, healthy

CLI interface:

npx tsx agents/relationship-sentinel/session-gap-check.ts              # Full portfolio scan
npx tsx agents/relationship-sentinel/session-gap-check.ts --client=paragon  # Single client
npx tsx agents/relationship-sentinel/session-gap-check.ts --json       # Machine-readable output
npx tsx agents/relationship-sentinel/session-gap-check.ts --detail     # Include appointment lookups

2. Sentinel Agent Definition Update

agents/relationship-sentinel/AGENT.md — Bash added to the Tools list. The Sentinel's scripts use execSync to call the HubSpot CLI (scripts/hubspot/api.js), which requires Bash tool access when the agent runs within Claude Code.

3. Implementation Alignment Documentation

An "Implementation Alignment" section was identified as needed in the Sentinel's Delegation Contract to document what the agent definition describes versus what is actually implemented in code. This addresses the root cause: the AGENT.md described HubSpot as a data source, but the script never queried it. The definition and the implementation were out of sync since creation.

4. Script-Profile Alignment Audit Framework

Added as Addendum A to the Structural Delegation plan (docs/plans/structural-delegation-5p-plan.md). This framework prevents the same class of gap across all 37 agents that have executable scripts. The audit compares what each AGENT.md claims (data sources, capabilities, output format) against what the script actually does.

What It Replaces

Before (v1 — filesystem only):

  • Single data source: clients/{slug}/sessions/*.md file dates
  • No HubSpot integration despite AGENT.md listing HubSpot as a data source
  • Clients with active HubSpot engagement but no recent session synthesis files appeared as critical gaps
  • 8 clients reported as "no sessions" when several had recent HubSpot activity
  • Output included no health scores, engagement trends, or risk factors

After (v2 — multi-source):

  • Three data sources with clear hierarchy and source attribution
  • HubSpot Company properties queried via efficient batch-read (single API call)
  • Optional appointment-level precision via --detail flag
  • Health score, engagement trend, and risk factors included per client
  • Data source attribution in every line of output

Evidence of Impact

Before/After Comparison (April 6, 2026)

Client v1 Status v1 Days v2 Status v2 Days v2 Source Correction
Mead Lumber critical 68d healthy 5d HubSpot False alarm eliminated
Caldwell Vineyard warning 26d healthy 4d HubSpot False alarm eliminated
ABS Company no sessions -- healthy 2d HubSpot Previously invisible
Adams Outdoor no sessions -- healthy 7d HubSpot Previously invisible
SecuredTech no sessions -- healthy 3d HubSpot Previously invisible

Portfolio-Wide Shift

Metric v1 v2
Clients with critical status 1 0
Clients with warning status 1 0
Clients with no data 8 7
Clients using HubSpot as primary source 0 11
Clients using session files as primary source -- 13
Health score / trend / risk data included No Yes

The single remaining difference between v1 and v2 "no data" counts (8 to 7) reflects one client that gained a HubSpot interaction date where previously it had neither session files nor HubSpot data.

Connection to Structural Delegation

This capability emerged directly from the Structural Delegation initiative (docs/plans/structural-delegation-5p-plan.md). The discovery pattern was:

  1. /sentinel-check produced obviously wrong results during daily-ops
  2. Investigation revealed the script was filesystem-only despite the AGENT.md describing HubSpot as a data source
  3. Root cause: no mechanism existed to verify that agent scripts implement what agent definitions describe
  4. Fix: rebuild the script (immediate), add Implementation Alignment to Delegation Contracts (structural), add Script-Profile Alignment Audit to the plan (preventive)

This is the class of gap that Structural Delegation is designed to close. The Sentinel was the first agent audited. The framework now exists for auditing all 37 agents with scripts.

Structural Delegation tasks completed by this work:

  • Agent script implements its full data source specification
  • Delegation Contract quality bar is achievable ("every flagged gap names the relationship, days since last session, and the applicable threshold" — now using real interaction dates)
  • Script-Profile Alignment Audit framework added to prevent recurrence across the agent roster

Verification

# Run the scanner and confirm multi-source output
npx tsx agents/relationship-sentinel/session-gap-check.ts 2>/dev/null | head -30

# Confirm HubSpot source attribution appears in output
npx tsx agents/relationship-sentinel/session-gap-check.ts 2>/dev/null | grep -c "HS\|HubSpot"

# Run JSON mode and confirm data structure
npx tsx agents/relationship-sentinel/session-gap-check.ts --json 2>/dev/null | node -e "
  const data = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
  const sources = data.results.map(r => r.lastInteractionSource);
  console.log('Sources:', [...new Set(sources)].join(', '));
  console.log('Clients with HubSpot data:', data.results.filter(r => r.hubspot.healthScore).length);
  console.log('Total clients:', data.results.length);
"

# Confirm Bash tool in agent definition
grep -c 'Bash' agents/relationship-sentinel/AGENT.md

Files Changed

File Change
agents/relationship-sentinel/session-gap-check.ts Complete rebuild: single-source to multi-source
agents/relationship-sentinel/AGENT.md Bash added to tools list
docs/plans/structural-delegation-5p-plan.md Addendum A: Script-Profile Alignment Audit framework

What This Changes

The Sentinel was born from the Spherion gap — a contract that ended without a renewal signal because no one was watching. Its purpose is to ensure that never happens again. But a sentinel that reports false alarms is worse than no sentinel at all, because false alarms train the team to ignore the alerts.

With multi-source monitoring, the Sentinel now reports what is actually happening in each relationship, not just whether a session synthesis file exists locally. The daily-ops relationship intelligence section can be trusted. When the Sentinel says a client is critical, it means no one has interacted with that client — not in HubSpot, not in session files, not in appointments. That signal is worth acting on.