AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
feat(watchlist): research watch policy — grounded watches go straight in, uncertain ones become suggestions
Rufus0fad05697a3b
diff --git a/.env.example b/.env.exampleindex 8664a555..eb338637 100644--- a/.env.example+++ b/.env.example@@ -257,3 +257,15 @@ NUDGE_MAX_PER_SCOPE=3# Force a research-council re-run at most this often when internal state is# unchanged (was daily; a daily forced run re-filed the same findings).WATCHLIST_RESEARCH_MAX_STALENESS_HOURS=168+# Research watchlist policy: the research pass only proposes watches. A+# proposal grounded in company data (a named competitor / vendor / ticker /+# initiative) and corroborated is added on its own, quietly (at most+# MAX_DIRECT_ADDS per run); anything the Executive is not sure about lands+# as a dry-run SUGGESTION on /watchlist for you to approve or decline (at+# most MAX_PROPOSALS per run). Above WATCHLIST_MAX_ENABLED enabled watches+# every add becomes a suggestion; suggestions nobody reviews within+# WATCHLIST_PROPOSAL_TTL_DAYS are removed (re-proposable after 90 days).+WATCHLIST_RESEARCH_MAX_DIRECT_ADDS=2+WATCHLIST_RESEARCH_MAX_PROPOSALS=2+WATCHLIST_MAX_ENABLED=40+WATCHLIST_PROPOSAL_TTL_DAYS=14diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 47ff47f2..189762df 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- **Research watchlist policy — grounded watches go straight in, uncertain+ ones become suggestions.** The research council's watchlist pass no longer+ adds watches itself; its only tool is `propose_watch`, and deterministic+ policy (`monitoring.research.watch_policy`) decides from company data. A+ proposal tied to a named competitor, vendor, ticker, initiative or+ priority (the profile gains `vendors` and `tickers` for this) and+ corroborated (own source, high-confidence / verified finding, consensus,+ the policy's own track record) is added on its own — quietly: daily+ cadence, medium severity floor, a keyword trigger for feeds, 5 % for+ stocks — and shows up in the brief's "handled overnight" block as+ *watching*. Anything the Executive is not sure about lands as a dry-run+ **suggestion** (polls, never alerts) in a "Suggested by the Executive"+ section on `/watchlist` with Approve / Decline (reason: not relevant, too+ noisy, wrong source); the morning brief mentions the pending count in one+ line, and a single nudge alert fires only once ≥3 suggestions have waited+ ≥7 days. Declines are remembered by target and enforced in the tool+ handler, so a declined source is never re-proposed under a new slug;+ "Stop watching…" on a research-added card, `remove_watchlist_entry` and+ `DELETE /watchlist/{slug}?reason=` on research rows record one too.+ Approvals, declines, expiries and auto-disables feed the policy's history+ and the research turn ("stock watches grounded in a competitor: 4+ approved / 1 declined"). Research-added watches retire themselves: the+ scheduler sweep disables one that fired ≥5 alerts with ≥2 dismissed and+ low trust, a feed/page/status watch with no signal in 30 days, or one with+ 3 consecutive poll failures (audited; re-enable from `/watchlist`).+ Endpoints: `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline`.+ Settings: `WATCHLIST_RESEARCH_MAX_DIRECT_ADDS=2`,+ `WATCHLIST_RESEARCH_MAX_PROPOSALS=2`, `WATCHLIST_MAX_ENABLED=40`,+ `WATCHLIST_PROPOSAL_TTL_DAYS=14`.- **Self-maintaining alert feed.** Alerts get a per-category time-to-live(`ALERT_TTL_DAYS_ACTION=14`, `ALERT_TTL_DAYS_MONITORING=3`); a schedulersweep expires past-TTL rows (audited, reversible via@@ -47,6 +76,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0ranking and is shown to the review as evidence.### Changed+- Watchlist rows carry an `origin` (`manual` | `executive` | `research` |+ `research_proposed`); the research skip-if-unchanged fingerprint hashes+ only enabled, active rows so approving or declining a suggestion never+ triggers a fresh 7-specialist run; the research turn shows each watch's+ origin, fired/dismissed counts and trust, plus declined targets.- Daily briefs are bounded to "since the last delivered brief": what's new,what the Executive handled overnight, who we're waiting on, one top call,and a one-line carried-over count. An unchanged day sends@@ -62,8 +96,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0triage-born alert fell to the principal as "unrouted").### Upgrading-- All schema changes are additive columns with defaults (`alerts` table);- rolling the image back is safe. No config changes are required.+- All schema changes are additive columns with defaults (`alerts` table;+ `watchlist.origin`, plus two new tables `watchlist_declines` and+ `watchlist_policy_outcomes`); rolling the image back is safe. No config+ changes are required.+- The research council now adds a watch on its own only when it is grounded+ in your company data. Name your vendors and tickers on the Company+ Profile page ("External Dependencies") so status pages and filings for+ them land without asking; everything else arrives as a suggestion on+ `/watchlist`. Existing watches are untouched (`origin=manual`) and never+ auto-disabled.- After upgrading, the first scheduler sweep expires alerts past their TTL(audited as `alert_sweep`, reversible with `reopen`); raise`ALERT_TTL_DAYS_*` (or set `0`) beforehand to keep an old backlog. Thediff --git a/packages/core/openexecutive/api/models.py b/packages/core/openexecutive/api/models.pyindex 77eb29ed..a7272711 100644--- a/packages/core/openexecutive/api/models.py+++ b/packages/core/openexecutive/api/models.py@@ -202,6 +202,8 @@ class CompanyProfileResponse(BaseModel):strategic_priorities: StrategicPrioritiesDataculture: CultureDatafinancials: FinancialsData+ vendors: list[str] = Field(default_factory=list)+ tickers: list[str] = Field(default_factory=list)class CompanyProfileUpdateRequest(BaseModel):@@ -219,3 +221,5 @@ class CompanyProfileUpdateRequest(BaseModel):strategic_priorities: StrategicPrioritiesData | None = Noneculture: CultureData | None = Nonefinancials: FinancialsData | None = None+ vendors: list[str] | None = None+ tickers: list[str] | None = Nonediff --git a/packages/core/openexecutive/api/routes/watchlist.py b/packages/core/openexecutive/api/routes/watchlist.pyindex 33c949ae..98bcb9c8 100644--- a/packages/core/openexecutive/api/routes/watchlist.py+++ b/packages/core/openexecutive/api/routes/watchlist.py@@ -21,7 +21,15 @@ from openexecutive.alerts.models import AlertSeverityfrom openexecutive.audit import log_event as audit_logfrom openexecutive.monitoring import store as msfrom openexecutive.monitoring.models import (+ DECLINE_KIND_EXPLICIT,+ DECLINE_REASON_NOT_RELEVANT,+ DECLINE_REASON_TOO_NOISY,MODE_ACTIVE,+ MODE_DRY_RUN,+ ORIGIN_RESEARCH,+ ORIGIN_RESEARCH_PROPOSED,+ RESEARCH_ORIGINS,+ VALID_DECLINE_REASONS,WatchlistItem,is_valid_cadence,is_valid_mode,@@ -34,6 +42,7 @@ from openexecutive.monitoring.target_validation import (from openexecutive.monitoring.validation import (VALID_SEVERITY_VALUES,is_valid_watchlist_slug,+ normalize_target,)logger = logging.getLogger(__name__)@@ -88,6 +97,23 @@ class WatchlistPatch(BaseModel):notes: str | None = Field(default=None, max_length=500)+class DeclineBody(BaseModel):+ model_config = ConfigDict(extra="forbid")++ # not_relevant → the entity is blacklisted; too_noisy → the watch goes+ # live anyway but quieter (high floor); wrong_source → only this target+ # is blacklisted. See monitoring.research.watch_policy.+ reason: str = DECLINE_REASON_NOT_RELEVANT+++class DeclineResponse(BaseModel):+ slug: str+ reason: str+ # "removed" (declined + deleted) or "kept_quiet" (too_noisy: converted+ # to an active watch with a high severity floor instead).+ result: str++class SignalRow(BaseModel):"""Shape of one row in /watchlist/{slug}/signals.@@ -353,12 +379,30 @@ def patch_watchlist_entry(slug: str, body: WatchlistPatch) -> WatchlistItem:return updated+def _record_decline(item: WatchlistItem, reason: str) -> None:+ """Remember that the principal said no to this research source, so the+ research pass never re-proposes it under a new slug."""+ from openexecutive.monitoring.research import watch_policy++ ms.insert_decline(+ normalized_target=normalize_target(item.signal_type, item.target),+ kind=DECLINE_KIND_EXPLICIT,+ reason=reason,+ entity=str(watch_policy.policy_stamp_of(item).get("entity", "")),+ signal_type=item.signal_type,+ slug=item.slug,+ )+ watch_policy.record_outcome_for(item, watch_policy.OUTCOME_DECLINED)++@router.delete("/watchlist/{slug}", status_code=status.HTTP_204_NO_CONTENT)-def delete_watchlist_entry(slug: str) -> Response:+def delete_watchlist_entry(slug: str, reason: str | None = None) -> Response:item = ms.get_watchlist_item_by_slug(slug)if item is None:raise HTTPException(status_code=404, detail=f"Watchlist entry {slug!r} not found")assert item.id is not None+ if reason is not None and reason not in VALID_DECLINE_REASONS:+ raise HTTPException(status_code=400, detail=f"unknown reason {reason!r}")try:removed = ms.delete_watchlist_item(item.id)except Exception as exc:@@ -370,9 +414,93 @@ def delete_watchlist_entry(slug: str) -> Response:logger.exception("watchlist.delete: failed slug=%s", slug)raise HTTPException(status_code=500, detail="delete failed") from exc+ if removed and item.origin in RESEARCH_ORIGINS:+ # "Stop watching" a research-added source is feedback.+ try:+ _record_decline(item, reason or DECLINE_REASON_NOT_RELEVANT)+ except Exception:+ logger.exception("watchlist.delete: decline record failed slug=%s", slug)+_audit("watchlist.delete", removed,f"watchlist.delete: {slug} ({'deleted' if removed else 'no-op'})",- {"slug": slug, "watchlist_id": item.id, "removed": removed},+ {"slug": slug, "watchlist_id": item.id, "removed": removed, "reason": reason},)return Response(status_code=status.HTTP_204_NO_CONTENT)+++# --------------------------------------------------------------------------- #+# Research suggestions: approve / decline+# --------------------------------------------------------------------------- #+++def _pending_suggestion_or_409(slug: str) -> WatchlistItem:+ item = ms.get_watchlist_item_by_slug(slug)+ if item is None:+ raise HTTPException(status_code=404, detail=f"Watchlist entry {slug!r} not found")+ if item.origin != ORIGIN_RESEARCH_PROPOSED or item.mode != MODE_DRY_RUN:+ raise HTTPException(+ status_code=409,+ detail=f"{slug!r} is not a pending research suggestion",+ )+ return item++[email protected]("/watchlist/{slug}/approve", response_model=WatchlistItem)+def approve_watchlist_suggestion(slug: str) -> WatchlistItem:+ """Turn a research suggestion into a live watch (origin=research)."""+ from openexecutive.monitoring.research import watch_policy++ item = _pending_suggestion_or_409(slug)+ assert item.id is not None+ if not ms.approve_suggestion(item.id):+ raise HTTPException(status_code=409, detail=f"{slug!r} is not a pending research suggestion")+ watch_policy.record_outcome_for(item, watch_policy.OUTCOME_APPROVED)+ audit_log(+ watch_policy.EVENT_SUGGESTION_APPROVED,+ f"Approved watching {slug} — {item.notes[:120] or item.target}",+ actor=_API_ACTOR,+ details={"slug": slug, "watchlist_id": item.id, "target": item.target,+ "signal_type": item.signal_type},+ )+ updated = ms.get_watchlist_item(item.id)+ if updated is None:+ raise HTTPException(status_code=500, detail="watchlist entry vanished after approve")+ return updated++[email protected]("/watchlist/{slug}/decline", response_model=DeclineResponse)+def decline_watchlist_suggestion(slug: str, body: DeclineBody | None = None) -> DeclineResponse:+ """Decline a research suggestion. The reason picks the remedy:+ not_relevant / wrong_source remove it and blacklist (entity / target);+ too_noisy keeps it, live, with a high severity floor."""+ from openexecutive.monitoring.research import watch_policy++ reason = (body.reason if body else DECLINE_REASON_NOT_RELEVANT)+ if reason not in VALID_DECLINE_REASONS:+ raise HTTPException(status_code=400, detail=f"unknown reason {reason!r}")+ item = _pending_suggestion_or_409(slug)+ assert item.id is not None++ if reason == DECLINE_REASON_TOO_NOISY:+ ms.update_watchlist_fields(item.id, {+ "mode": MODE_ACTIVE, "origin": ORIGIN_RESEARCH,+ "severity_floor": "high", "enabled": 1,+ })+ watch_policy.record_outcome_for(item, watch_policy.OUTCOME_APPROVED)+ result = "kept_quiet"+ else:+ try:+ _record_decline(item, reason)+ except Exception:+ logger.exception("watchlist.decline: decline record failed slug=%s", slug)+ ms.delete_watchlist_item(item.id)+ result = "removed"+ audit_log(+ watch_policy.EVENT_SUGGESTION_DECLINED,+ f"Declined watching {slug} ({reason}) — {result}",+ actor=_API_ACTOR,+ details={"slug": slug, "watchlist_id": item.id, "target": item.target,+ "signal_type": item.signal_type, "reason": reason, "result": result},+ )+ return DeclineResponse(slug=slug, reason=reason, result=result)diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex a2befe9d..5ace2763 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -1152,7 +1152,7 @@ scheduler:- "principal_brief_eod — same shape as morning_brief, fires once per day at `PRINCIPAL_BRIEF_EOD_TIME` (default 18:00 UTC). Runs `end_of_day_digest` workflow. Both brief kinds bypass the per-channel anti-spam guards because the principal is by definition deliverable (channel_ref=`principal`, channel=`__internal__` triggers the workflow run rather than a direct send)."- "executive_reflection — Shift 5 recurring row. Seeded alongside the principal briefs (idempotent via `_has_pending_brief`), default 07:30 UTC, override via `PRINCIPAL_REFLECTION_TIME`. The scheduler runs `_run_executive_reflection`: invokes the `executive_reflection` workflow, stores the artifact via `complete_run`, audits the outcome, then chains the next occurrence — same crash-survival pattern as principal briefs. Unlike the briefs, the artifact is NOT delivered to the principal — the morning brief that fires 30 minutes later surfaces what reflection decided via the existing /today/activity rail."- "external_monitor_scan — heartbeat owned by the external-condition monitoring layer. Default every 5 min via EXTERNAL_MONITOR_SCAN_INTERVAL_MINUTES. The runner calls `monitoring.pipeline.run_external_monitor_scan()` which walks enabled watchlist rows whose `last_polled_at` is stale enough, fires the matching adapter (vendor_status, rss, stock, the billed standing-query `query` adapter, the `edgar` SEC-filings adapter, and the stateful `page_watch` change-detector), enriches promotable signals with capture-time relevance, writes `external_signals` rows, and promotes qualifying signals into the alerts pipeline. Bypasses outbound dispatch (channel=`__internal__`, channel_ref=`external_monitor`). Chains the next tick via `enqueue_next_external_monitor_scan` after firing — same idempotent / crash-resilient pattern as `nudge_scan`."- - "watchlist_research_scan — periodic cron for the executive_research workflow (default every 120 min via WATCHLIST_RESEARCH_INTERVAL_MINUTES). The handler short-circuits when the company profile / initiatives / watchlist haven't changed since the last successful run, so quiet days cost zero tokens — except that a staleness floor (WATCHLIST_RESEARCH_MAX_STALENESS_HOURS, default 168 — weekly; a daily forced run re-derived the same findings from unchanged state and re-filed them as fresh alerts every morning) forces a run once that long has elapsed since the last successful run, so a static internal state can't keep the council blind to external change indefinitely. Does NOT write its own Alert — the workflow's Executive synthesis step routes findings directly via DMs / send_department_message / create_alert / add_watchlist_entry, so a separate cron Alert would duplicate the briefing. After routing, a DEDICATED watchlist-analysis pass (its own budget, separate from the routing budget) explicitly decides which findings are ongoing monitorable conditions and calls add_watchlist_entry for each; the run's markdown artifact is also persisted into the separate `recent_research` knowledge collection (keep-latest) so future runs + chat can recall it. The cron's only side-effects on success are the audit row (`watchlist_research_periodic_ran`) and whatever routing tools the synthesis fired. The scheduled-action kind keeps the legacy `watchlist_research_scan` name (matched by the env var WATCHLIST_RESEARCH_INTERVAL_MINUTES + the three audit event_types) even though the workflow itself is registered as `executive_research` — naming is mixed intentionally to avoid a migration on already-pending heartbeat rows. Bypasses outbound dispatch (channel=`__internal__`, channel_ref=`watchlist_research`)."+ - "watchlist_research_scan — periodic cron for the executive_research workflow (default every 120 min via WATCHLIST_RESEARCH_INTERVAL_MINUTES). The handler short-circuits when the company profile / initiatives / watchlist haven't changed since the last successful run, so quiet days cost zero tokens — except that a staleness floor (WATCHLIST_RESEARCH_MAX_STALENESS_HOURS, default 168 — weekly; a daily forced run re-derived the same findings from unchanged state and re-filed them as fresh alerts every morning) forces a run once that long has elapsed since the last successful run, so a static internal state can't keep the council blind to external change indefinitely. Does NOT write its own Alert — the workflow's Executive synthesis step routes findings directly via DMs / send_department_message / create_alert / add_watchlist_entry, so a separate cron Alert would duplicate the briefing. After routing, a DEDICATED watchlist-analysis pass (its own budget, separate from the routing budget) PROPOSES ongoing monitors via `propose_watch`; deterministic policy (`monitoring.research.watch_policy`, see external_monitoring) adds a proposal on its own only when it is grounded in company data and corroborated, files the rest as dry-run suggestions the principal approves on /watchlist, and refuses declined targets; the run's markdown artifact is also persisted into the separate `recent_research` knowledge collection (keep-latest) so future runs + chat can recall it. The cron's only side-effects on success are the audit row (`watchlist_research_periodic_ran`) and whatever routing tools the synthesis fired. The scheduled-action kind keeps the legacy `watchlist_research_scan` name (matched by the env var WATCHLIST_RESEARCH_INTERVAL_MINUTES + the three audit event_types) even though the workflow itself is registered as `executive_research` — naming is mixed intentionally to avoid a migration on already-pending heartbeat rows. Bypasses outbound dispatch (channel=`__internal__`, channel_ref=`watchlist_research`)."- "notion_sync_scan — optional heartbeat (NOTION_SYNC_ENABLED, default off) that incrementally re-indexes Notion pages shared with an internal integration into the isolated `notion_wiki` collection (NOT COMPANY — synced pages are multi-writer and unreviewed). Interval NOTION_SYNC_INTERVAL_MINUTES (default 60). Caps ingest per tick via NOTION_MAX_PAGES_PER_SCAN; overflow is retried and the watermark does not advance past failed or uningested pages. Each tick reconciles: un-shared/deleted pages have files + chunks purged. Bypasses outbound dispatch (channel=`__internal__`, channel_ref=`notion_sync`). Chains the next tick via enqueue_next_notion_sync_scan. See knowledge.collections NOTION_WIKI."channel_routing: |The delivery channel is stored ON the scheduled_actions row itself@@ -1332,6 +1332,9 @@ audit:- watchlist_research_periodic_ran — emitted by the periodic cron whenever the workflow actually fires. Carries `state_hash` (the input fingerprint at run time), `trigger` (`cold_start`, `state_changed`, or `staleness_floor`), `findings` count, `tool_calls` count, `ok_tool_calls`, `run_id`. The next tick reads the most recent row to decide skip-or-run (its `state_hash` for the fingerprint compare, its `ts` for the staleness floor). These three research run-history rows are the ONLY audit_log rows a fixture load/unload clears (via `monitoring.research.scheduler.clear_research_run_history`, called from `cli.fixture_loader._apply_state_from_source`): load wipes the profile/initiatives/watchlist that feed the fingerprint but otherwise preserves audit_log, so without this reset a same-fixture reload within the staleness floor would make the freshly-seeded scan skip itself and surface zero findings. A full reset still wipes all of audit_log.- watchlist_research_periodic_skipped — emitted when the state_hash matches the last `_ran` row. Carries `state_hash`. Visible cost-saving signal in the audit log.- watchlist_research_periodic_failed — emitted on workflow timeout / crash. Carries `state_hash` + `error` or `reason`.+ - watchlist_research_added / watchlist_research_suggested / watchlist_research_rejected — one row per `propose_watch` the research watch policy decided (`monitoring.research.watch_policy`). Carries `slug`, `target`, `signal_type`, `rationale`, `entity`, `grounding_kind`, `score`, `reasons`, and for adds the quiet defaults applied (`cadence`, `severity_floor`, `trigger`). `_added` also renders in the brief's HANDLED block as `watching`.+ - watchlist_suggestion_approved / watchlist_suggestion_declined / watchlist_suggestion_expired — the principal's verdict on a research suggestion (`POST /watchlist/{slug}/approve|decline`, reason on decline) or the sweep removing one unreviewed after WATCHLIST_PROPOSAL_TTL_DAYS. Each also writes a `watchlist_policy_outcomes` row so the policy calibrates.+ - watchlist_auto_disabled — the sweep disabled a research-origin watch (`reason`: dismissed N of M alerts with low trust; no signals in 30 days; 3 consecutive poll failures). Renders in the HANDLED block as `stopped_watching`; re-enable from /watchlist.- auth_login / auth_logout — admin auth eventsturn_id: Set per Executive turn (`f"t-{uuid12}"`) and propagated automatically to retriever / specialist / tool / cache / committee emits via `openexecutive.audit.context` ContextVars. Groups every row in one user-assistant exchange under the same `turn_id`; the session view derives causal edges from this.writer: openexecutive.audit.AuditLogger — synchronous SQLite writer; uses WAL + 5s busy_timeout so concurrent webhook/scheduler/poller threads don't see "database is locked".@@ -1358,6 +1361,54 @@ external_monitoring:+ stock adapters and the chat tools (add_watchlist_entry, ...). PR-Cextends executive_reflection to include external signals in itscontext and the briefing UI to badge external:* topic_tags.+ research_watch_policy: |+ The executive_research watchlist pass only PROPOSES (tool `propose_watch`:+ slug, signal_type, target, grounding_entity, rationale, certainty,+ finding_index). `monitoring.research.watch_policy` decides deterministically:+ - grounding vocabulary = company name + competitive_landscape.primary_competitors+ + profile.vendors + profile.tickers + active initiative titles ++ strategic_priorities.current_year (+ existing watch labels, which only+ corroborate). The entity MUST match a company-data term for a direct add.+ - score ledger: +2 entity in company data (mandatory), +1 entity already+ watched under another source, +1 target is the entity's own source (its+ ticker / its domain / a primary-source host: sec.gov, federalregister.gov,+ eur-lex), +1 finding confidence high, +1 verification confirmed, +1+ cross-specialist consensus, ±1 policy history for (signal_type,+ grounding_kind) at >= 5 samples (>= 0.7 / <= 0.3 approval rate).+ - direct add at score >= 4 with the mandatory match; model `certainty`+ can only downgrade; `query` never direct; above WATCHLIST_MAX_ENABLED+ (40) enabled rows every add is a suggestion; WATCHLIST_RESEARCH_MAX_DIRECT_ADDS+ (2) and WATCHLIST_RESEARCH_MAX_PROPOSALS (2) per run.+ - quiet defaults on every research row (model cannot loosen): cadence+ daily (vendor_status hourly; page_watch/query weekly), severity_floor+ medium, feed keyword trigger = entity tokens + material-event words ++ priority terms, stock abs_change_pct_gte=5.+ - direct → mode=active, origin=research; suggestion → mode=dry_run,+ origin=research_proposed; rationale in `notes`; policy stamp (entity,+ grounding_kind, specialist, score, reasons, source_url) in+ config_json._policy. Reject: invalid target, same site + signal_type+ already watched, declined target, spent budget.+ - declines (`watchlist_declines`, keyed by normalized target): explicit+ (Decline button, "Stop watching…", remove_watchlist_entry / DELETE on a+ research-origin row) is permanent; expired_unreviewed retries once+ after 90 days. Enforced in the propose_watch handler, rendered to the+ model as DECLINED. Decline reasons: not_relevant (blacklist entity),+ wrong_source (blacklist target), too_noisy (keep live at floor=high).+ - outcomes (`watchlist_policy_outcomes`: approved / declined / expired /+ auto_disabled by signal_type, grounding_kind, specialist) feed the+ history term and are rendered to the model as HOW PAST PROPOSALS TURNED OUT.+ - sweep (watch_policy.sweep, on the scheduler's 15-min alert sweep):+ expire suggestions older than WATCHLIST_PROPOSAL_TTL_DAYS (14);+ auto-disable research-origin watches (fired >= 5 & dismissed >= 2 &+ trust <= 0.5; rss/page_watch/vendor_status with no signal in 30 days;+ 3 consecutive failed polls); one `watchlist_suggestions` nudge alert+ when >= 3 suggestions have waited >= 7 days (keyed on the oldest slug).+ - the research state fingerprint hashes only enabled + active rows, so+ approving / declining a suggestion never triggers a fresh research run.+ - surfaces: /watchlist "Suggested by the Executive" (Approve / Decline…+ with reason), "Added by the Executive · rationale" on research cards+ with "Stop watching…", the morning brief's HANDLED block (watching /+ stopped_watching) and a one-line WATCH SUGGESTIONS WAITING count.data_model:watchlist (in episodic_memory.db): |One row per condition the user wants monitored. Mutable per-row@@ -1368,7 +1419,15 @@ external_monitoring:cadence, severity_floor, severity_ceiling, route_to_specialist,route_to_department, route_to_person_id, mode ('active' | 'dry_run'),enabled, created_at, last_polled_at, baselined_at, last_fired_at,- fired_count, dismiss_count, trust_score, notes.+ fired_count, dismiss_count, trust_score, notes, origin ('manual' |+ 'executive' | 'research' | 'research_proposed'; additive ALTER,+ default 'manual').+ watchlist_declines / watchlist_policy_outcomes (in episodic_memory.db): |+ Research watch policy memory — see research_watch_policy above.+ watchlist_declines(normalized_target PK, entity, signal_type, slug,+ kind 'declined_explicit' | 'expired_unreviewed', reason, declined_at);+ watchlist_policy_outcomes(id, signal_type, grounding_kind, specialist,+ outcome 'approved' | 'declined' | 'expired' | 'auto_disabled', at).baselined_at (nullable, additive ALTER; backfilled fromlast_polled_at for rows that were already being polled when thecolumn landed) is set once a seeding source's first poll that@@ -1777,7 +1836,7 @@ external_monitoring:triggers:- "Manual chat — the principal asks 'what should we look into?'; the Executive calls the `run_executive_research` chat tool. The tool runs the workflow, which both researches AND routes; the chat tool returns the structured summary so the Executive can describe to the principal what it researched and what it did with each finding."- "Onboarding completion — when the wizard finishes (build_and_save_profile fires), `api/routes/onboarding._fire_post_onboarding_research` schedules the workflow as a background task. The workflow's synthesis step fires whatever routing tools it deems necessary (DMs to heads, briefing alert, watchlist additions) — the wrapper just runs the workflow with a wall-clock ceiling and creates / completes the workflow_run row."- - "Periodic cron — `watchlist_research_scan` scheduled-action kind (default every 120 min via `WATCHLIST_RESEARCH_INTERVAL_MINUTES`). Each tick computes a state fingerprint (company profile + active initiatives + watchlist slugs/targets) and SKIPS the run when nothing has changed since the last successful periodic research. Quiet days cost zero tokens; first tick after any material profile / initiative / watchlist change fires immediately. A staleness floor (`WATCHLIST_RESEARCH_MAX_STALENESS_HOURS`, default 168, i.e. weekly) overrides the skip once that many hours have elapsed since the last successful run, so a static internal state cannot keep the council blind to purely-external change forever (set <= 0 to disable). The cron does NOT write its own Alert — the workflow's synthesis step already routes findings directly. After routing, a dedicated watchlist-analysis pass (separate budget) explicitly adds ongoing monitors via add_watchlist_entry, and the run artifact is persisted into the separate `recent_research` knowledge collection (keep-latest). Cron's only side-effects on success are the `watchlist_research_periodic_ran` audit row + whatever the workflow's Executive synthesis + watchlist pass fired."+ - "Periodic cron — `watchlist_research_scan` scheduled-action kind (default every 120 min via `WATCHLIST_RESEARCH_INTERVAL_MINUTES`). Each tick computes a state fingerprint (company profile + active initiatives + watchlist slugs/targets) and SKIPS the run when nothing has changed since the last successful periodic research. Quiet days cost zero tokens; first tick after any material profile / initiative / watchlist change fires immediately. A staleness floor (`WATCHLIST_RESEARCH_MAX_STALENESS_HOURS`, default 168, i.e. weekly) overrides the skip once that many hours have elapsed since the last successful run, so a static internal state cannot keep the council blind to purely-external change forever (set <= 0 to disable). The cron does NOT write its own Alert — the workflow's synthesis step already routes findings directly. After routing, a dedicated watchlist-analysis pass (separate budget) proposes ongoing monitors via `propose_watch`; `monitoring.research.watch_policy` decides per proposal — direct add (grounded in company data: competitor / vendor / ticker / initiative / priority, score >= 4 on a fixed ledger, quiet defaults) vs dry-run suggestion for the principal vs reject — and the run artifact is persisted into the separate `recent_research` knowledge collection (keep-latest). Cron's only side-effects on success are the `watchlist_research_periodic_ran` audit row + whatever the workflow's Executive synthesis + watchlist pass fired."skip_if_unchanged: |The periodic cron handler (`monitoring.research.scheduler.run_watchlist_research_scan`)computes a sha256 over (`CompanyProfile.to_prompt_block()`,@@ -1793,7 +1852,7 @@ external_monitoring:The `state_hash` stored on a successful run is recomputed *after*the workflow finishes, NOT the pre-run hash used for the skip- decision. The workflow's watchlist pass calls `add_watchlist_entry`,+ decision. The workflow's watchlist pass adds watches (via the watch policy),mutating a fingerprint input; storing the pre-run hash would leaveevery later tick seeing a "changed" state and re-running a fullresearch pass each interval. Capturing the post-run state as thediff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.jsonindex 9f4dcdf0..1a56464a 100644--- a/packages/core/openexecutive/architecture/prebuilt/api.json+++ b/packages/core/openexecutive/architecture/prebuilt/api.json@@ -1,7 +1,7 @@{"section_id": "api","title": "API Reference",- "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. |\n| `talent` | `GET|POST|PATCH /engagements`, `GET|POST|PATCH /candidates`, `POST /candidates/{id}/stage`, `GET /engagements/{id}/matches`, `GET /candidates/{id}/similar`, `POST /talent/reindex`, `GET|POST|PATCH /offers`, `POST /offers/{id}/{extend,decision,archive}` | Executive-search pipeline: searches, candidates, semantic matching, and the offer lifecycle (extend/decision return the offer plus approval state, scheduled/cancelled expiry nudges, side effects, and warnings; lifecycle conflicts are 409s). |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist` | External-monitoring watchlist + signals. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats` | Knowledge review queue and annotations. |\n| `onboarding` | `/onboard/start`, `/onboard/answer` | Company-profile setup wizard. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Allowed sign-in emails. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",+ "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. |\n| `talent` | `GET|POST|PATCH /engagements`, `GET|POST|PATCH /candidates`, `POST /candidates/{id}/stage`, `GET /engagements/{id}/matches`, `GET /candidates/{id}/similar`, `POST /talent/reindex`, `GET|POST|PATCH /offers`, `POST /offers/{id}/{extend,decision,archive}` | Executive-search pipeline: searches, candidates, semantic matching, and the offer lifecycle (extend/decision return the offer plus approval state, scheduled/cancelled expiry nudges, side effects, and warnings; lifecycle conflicts are 409s). |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats` | Knowledge review queue and annotations. |\n| `onboarding` | `/onboard/start`, `/onboard/answer` | Company-profile setup wizard. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Allowed sign-in emails. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |","mermaid": null,- "generated_at": "2026-09-11T19:47:55+00:00"+ "generated_at": "2026-09-12T10:44:45.779442+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/external_monitoring.json b/packages/core/openexecutive/architecture/prebuilt/external_monitoring.jsonindex 906688e9..5611fa7f 100644--- a/packages/core/openexecutive/architecture/prebuilt/external_monitoring.json+++ b/packages/core/openexecutive/architecture/prebuilt/external_monitoring.json@@ -1,7 +1,7 @@{"section_id": "external_monitoring","title": "External Monitoring",- "markdown": "`openexecutive.monitoring` watches the outside world on a heartbeat and turns detected changes into briefing proposals via the same alert pipeline that handles inbound email and Slack.\n\nThe `external_monitor_scan` heartbeat (`__internal__` channel, default every 5 min) walks `list_watchlist(enabled_only=True)`, skipping rows fresher than their per-source cadence floor. For each due row it fires a read-only source adapter resolved from `_REGISTRY` by `signal_type`:\n\n- `vendor_status` — Statuspage Atom/RSS incident feeds (AWS, Stripe, GitHub, …). Reads each incident's current status out of the entry body, parses `<updated>` into `published_at`, and keys its dedup on `(entry id, <updated>)`; a **seeding** source (see below).\n- `rss` — generic Atom/RSS via feedparser (changelogs, layoffs.fyi, filings). Parses each entry's `<pubDate>`/`<updated>` into `published_at`; a **seeding** source (see below).\n- `stock` — Yahoo Finance chart endpoint; fires on `abs_change_pct_gte` moves.\n- `page_watch` — change-detection on a feed-less page. Fetches via the keyless httpx fetcher by default, or via xcrawl's scrape API when the row carries `config.fetch = \"xcrawl\"` — so JS-rendered / bot-blocked pages that publish no RSS (most modern news / marketing sites) are still monitorable.\n- `edgar` and the BILLED `query` web-search adapter.\n\nEach `Signal` is trigger-filtered, severity-clamped to the row's `[floor, ceiling]`, and INSERTed into `external_signals` where `UNIQUE(dedup_key)` drops replays. Survivors pass a suppression cascade (`baseline` → `stale` → `dry_run` → `below_floor` → capture-time relevance enrichment → promote), then `promote_signal_to_alert` builds an `AlertEvent` handed to `alerts.pipeline.schedule_evaluation` and surfaced as a `/today` proposal.\n\nEvery signal carries two timestamps that are never conflated: `captured_at` (when the monitor first saw it) and `published_at` (when the upstream says it happened — RSS `<pubDate>`, EDGAR filing date; null for `stock`, `page_watch`, `query`). Two freshness gates run first in the cascade, before anything that costs an LLM call. **Baseline:** the first poll that returns entries for a row whose adapter declares `seed_on_first_poll` (`rss`, `edgar`) records every entry already in the feed — trigger misses included, so the first entry that ever matches a keyword is news and a later, wider trigger can't resurface old ones — as `suppressed_baseline`, promotes nothing, and stamps `watchlist.baselined_at`, so a new watch reports what changes from now on instead of replaying the feed's back-catalogue (the same idea as `page_watch`'s first-observation baseline). It is keyed on `baselined_at` rather than `last_polled_at`, so a failed first fetch can't forfeit it; the claim and the recording are one transaction (a compare-and-swap on the stamp plus the rows, all-or-nothing), so of two overlapping scans exactly one records the back-catalogue and a failure part-way leaves nothing behind to replay; the other scan promotes only entries dated after that stamp (undated entries count as baseline, since the feed controls the date; entries dated more than a few minutes past its own clock are deferred rather than recorded); and baseline rows don't count against `max_signals_per_scan`, so a large feed can't be half-baselined. `vendor_status` used to sit outside both gates for a structural reason: its dedup key was `sha256(slug, entry id)`, and an incident's id never changes across its updates, so any suppressed insert muted that incident for good. Keying on `(entry id, <updated>)` instead (issue #90) makes a suppression cost one *state* of an incident rather than the incident, so both gates now apply to vendor feeds too — and an incident moving Investigating → Resolved mints a new key and surfaces, while re-polling an unchanged feed still dedups. Because a history feed's archive is mostly incidents resolved months ago, the adapter also carves live news out of its own baseline: it reads each incident's current status from the entry body (Statuspage renders the newest update first as `<strong>Resolved</strong>` / `Investigating` / `Monitoring` / … — the body is parsed by a real HTML parser, off the event loop, and the reading is deliberately asymmetric: any sign that the incident is over closes it, wherever it appears, while only a marked-up label can say it is still open. Working out which update is newest turned out to be something tag soup cannot be trusted to express, and every attempt reported a long-resolved incident as live) and exempts the ones still OPEN via the optional `promote_on_baseline` hook, so a watch added during an outage reports that outage on its first poll while the resolved archive is recorded as `suppressed_baseline`. An unrecognised status counts as closed — a vendor changing feed format must not be able to promote its whole archive at HIGH, and nothing is lost, since the next `<updated>` bump surfaces normally. An exempt entry must still pass the row's trigger filter (one that misses stays in the baseline, so widening a trigger later cannot resurface it) and is still judged by the stale gate below: the exemption buys an entry past the baseline, never past its own timestamp, because \"this is live\" is a reading of vendor-controlled markup and an entry the feed dates outside the age window is not news whatever that reading says. **Stale:** a signal whose `published_at` is older than `EXTERNAL_MONITOR_MAX_SIGNAL_AGE_DAYS` (default 7; `0` disables) at capture time is recorded as `suppressed_stale` and never promoted — a January article a feed resurfaces in September is not September news. An entry dated more than `EXTERNAL_MONITOR_MAX_FUTURE_SKEW_HOURS` ahead (default 24; `0` disables; `config_json.max_future_skew_hours` overrides it per row for calendar or maintenance feeds that legitimately date entries ahead) is deferred instead: skipped for the tick and not recorded (recording would burn its dedup key and let a feed mute an announcement for good by post-dating it), with one aggregated `external_signal_deferred` audit row per poll — carrying each held-back entry's summary and link, and emitted even if the poll later raises — then judged normally once the date passes. Inside the window, the alert body handed to triage carries `Published:` and `Discovered:` lines so the item is judged on when it happened. Adapters prefer a plausible date key over one more than a day in the future (and keep the future value when every key is implausible, so the pipeline defers it rather than waving an undated entry through), and the alert body collapses whitespace in the summary so no source can forge its own labeled body line.\n\nThe `query` adapter is a special case: it emits every web hit flat-LOW (it can't judge materiality per-hit), so for query signals enrichment runs BEFORE the floor gate and `_grade_query_severity` regrades from the relevance read (≥0.8 HIGH, ≥0.5 MEDIUM, else LOW). Without this, any query watch item with a `severity_floor` above LOW would suppress every hit — which is what left the Monitoring section empty even while standing queries were returning material findings.\n\nWhich lane a proposal lands in is decided by `briefing.ranking.categorize`: an unrouted, low/medium signal from a monitoring source (`stock`, `vendor_status`, `rss`, `query`, `edgar`, `page_watch`, or any `external:*` topic tag) is `monitoring` (the collapsible Monitoring section); a routed or high/urgent one is `action` (the \"Needs you\" queue). The triage prompt's External Signals rule covers all six source kinds so it trusts the source and emits the `external:*` tags that drive this split.\n\nThe watchlist is editable from chat (`add_watchlist_entry`, `tune_watchlist_entry`) and HTTP (`/watchlist`); the `executive_research` workflow proposes what to watch. Because that workflow is LLM-driven and historically proposed feed URLs it never verified (most were dead — 404 / 403 / not-actually-a-feed), every `rss` target is validated at insert time (`monitoring.target_validation`): a URL that fetches and parses as a feed is kept; a public page that isn't a feed is converted to a scrape-backed `page_watch` when xcrawl can read it, otherwise rejected (HTTP 422 / tool error); SSRF-blocked or unparseable URLs are rejected outright and never handed to xcrawl. Non-`rss` types insert unchanged with no network I/O.\n\n### One watch, one card — and dismissals teach the watch\n\n`promote_signal_to_alert` stamps the `AlertEvent` with `dedup_hint=\"watch:<slug>\"`, which `alerts.pipeline` uses as the *alert* dedup key. A repeat from the same watch coalesces into the open card (`occurrence_count`, `last_seen_at`, severity max) rather than minting another, and re-pings only when severity rose into high/urgent — so a ticker that stays over its threshold or an incident that keeps updating no longer produces a new \"Needs you\" item every day. The signal-level `dedup_key` (stock's UTC-date bucket, vendor_status's `<updated>`) is untouched, so every observation still lands in `external_signals`. Dismissing a watch-sourced alert calls `store.record_dismissal(slug)` (`dismiss_count += 1`, `trust_score = max(0.2, trust × 0.8)`); approving calls `record_confirmation` (+0.05). `trust_score` discounts the briefing ranking and is shown to the Executive's alert review as evidence, alongside the newer signals for that watch (a \"Resolved\" incident state, a reversed move) that let it close the card with evidence.\n\n### Invariants\n\n- Adapters are read-only — they never write upstream and never auto-execute.\n- Every `Signal` carries a deterministic `dedup_key` and a mandatory `provenance_url`.\n- Fetches are SSRF-guarded and bounded by `external_monitor_max_fetch_bytes`; xcrawl scrape (off by default, gated by `XCRAWL_ENABLED` + `XCRAWL_API_KEY`) is the one path that delegates the fetch to an external API.\n- Suppressed signals are still persisted so audits show the full picture.\n- A repeat from the same watch never becomes a second open card: the alert-level `watch:<slug>` key coalesces it, and only a severity escalation re-dispatches.",+ "markdown": "`openexecutive.monitoring` watches the outside world on a heartbeat and turns detected changes into briefing proposals via the same alert pipeline that handles inbound email and Slack.\n\nThe `external_monitor_scan` heartbeat (`__internal__` channel, default every 5 min) walks `list_watchlist(enabled_only=True)`, skipping rows fresher than their per-source cadence floor. For each due row it fires a read-only source adapter resolved from `_REGISTRY` by `signal_type`:\n\n- `vendor_status` — Statuspage Atom/RSS incident feeds (AWS, Stripe, GitHub, …). Reads each incident's current status out of the entry body, parses `<updated>` into `published_at`, and keys its dedup on `(entry id, <updated>)`; a **seeding** source (see below).\n- `rss` — generic Atom/RSS via feedparser (changelogs, layoffs.fyi, filings). Parses each entry's `<pubDate>`/`<updated>` into `published_at`; a **seeding** source (see below).\n- `stock` — Yahoo Finance chart endpoint; fires on `abs_change_pct_gte` moves.\n- `page_watch` — change-detection on a feed-less page. Fetches via the keyless httpx fetcher by default, or via xcrawl's scrape API when the row carries `config.fetch = \"xcrawl\"` — so JS-rendered / bot-blocked pages that publish no RSS (most modern news / marketing sites) are still monitorable.\n- `edgar` and the BILLED `query` web-search adapter.\n\nEach `Signal` is trigger-filtered, severity-clamped to the row's `[floor, ceiling]`, and INSERTed into `external_signals` where `UNIQUE(dedup_key)` drops replays. Survivors pass a suppression cascade (`baseline` → `stale` → `dry_run` → `below_floor` → capture-time relevance enrichment → promote), then `promote_signal_to_alert` builds an `AlertEvent` handed to `alerts.pipeline.schedule_evaluation` and surfaced as a `/today` proposal.\n\nEvery signal carries two timestamps that are never conflated: `captured_at` (when the monitor first saw it) and `published_at` (when the upstream says it happened — RSS `<pubDate>`, EDGAR filing date; null for `stock`, `page_watch`, `query`). Two freshness gates run first in the cascade, before anything that costs an LLM call. **Baseline:** the first poll that returns entries for a row whose adapter declares `seed_on_first_poll` (`rss`, `edgar`) records every entry already in the feed — trigger misses included, so the first entry that ever matches a keyword is news and a later, wider trigger can't resurface old ones — as `suppressed_baseline`, promotes nothing, and stamps `watchlist.baselined_at`, so a new watch reports what changes from now on instead of replaying the feed's back-catalogue (the same idea as `page_watch`'s first-observation baseline). It is keyed on `baselined_at` rather than `last_polled_at`, so a failed first fetch can't forfeit it; the claim and the recording are one transaction (a compare-and-swap on the stamp plus the rows, all-or-nothing), so of two overlapping scans exactly one records the back-catalogue and a failure part-way leaves nothing behind to replay; the other scan promotes only entries dated after that stamp (undated entries count as baseline, since the feed controls the date; entries dated more than a few minutes past its own clock are deferred rather than recorded); and baseline rows don't count against `max_signals_per_scan`, so a large feed can't be half-baselined. `vendor_status` used to sit outside both gates for a structural reason: its dedup key was `sha256(slug, entry id)`, and an incident's id never changes across its updates, so any suppressed insert muted that incident for good. Keying on `(entry id, <updated>)` instead (issue #90) makes a suppression cost one *state* of an incident rather than the incident, so both gates now apply to vendor feeds too — and an incident moving Investigating → Resolved mints a new key and surfaces, while re-polling an unchanged feed still dedups. Because a history feed's archive is mostly incidents resolved months ago, the adapter also carves live news out of its own baseline: it reads each incident's current status from the entry body (Statuspage renders the newest update first as `<strong>Resolved</strong>` / `Investigating` / `Monitoring` / … — the body is parsed by a real HTML parser, off the event loop, and the reading is deliberately asymmetric: any sign that the incident is over closes it, wherever it appears, while only a marked-up label can say it is still open. Working out which update is newest turned out to be something tag soup cannot be trusted to express, and every attempt reported a long-resolved incident as live) and exempts the ones still OPEN via the optional `promote_on_baseline` hook, so a watch added during an outage reports that outage on its first poll while the resolved archive is recorded as `suppressed_baseline`. An unrecognised status counts as closed — a vendor changing feed format must not be able to promote its whole archive at HIGH, and nothing is lost, since the next `<updated>` bump surfaces normally. An exempt entry must still pass the row's trigger filter (one that misses stays in the baseline, so widening a trigger later cannot resurface it) and is still judged by the stale gate below: the exemption buys an entry past the baseline, never past its own timestamp, because \"this is live\" is a reading of vendor-controlled markup and an entry the feed dates outside the age window is not news whatever that reading says. **Stale:** a signal whose `published_at` is older than `EXTERNAL_MONITOR_MAX_SIGNAL_AGE_DAYS` (default 7; `0` disables) at capture time is recorded as `suppressed_stale` and never promoted — a January article a feed resurfaces in September is not September news. An entry dated more than `EXTERNAL_MONITOR_MAX_FUTURE_SKEW_HOURS` ahead (default 24; `0` disables; `config_json.max_future_skew_hours` overrides it per row for calendar or maintenance feeds that legitimately date entries ahead) is deferred instead: skipped for the tick and not recorded (recording would burn its dedup key and let a feed mute an announcement for good by post-dating it), with one aggregated `external_signal_deferred` audit row per poll — carrying each held-back entry's summary and link, and emitted even if the poll later raises — then judged normally once the date passes. Inside the window, the alert body handed to triage carries `Published:` and `Discovered:` lines so the item is judged on when it happened. Adapters prefer a plausible date key over one more than a day in the future (and keep the future value when every key is implausible, so the pipeline defers it rather than waving an undated entry through), and the alert body collapses whitespace in the summary so no source can forge its own labeled body line.\n\nThe `query` adapter is a special case: it emits every web hit flat-LOW (it can't judge materiality per-hit), so for query signals enrichment runs BEFORE the floor gate and `_grade_query_severity` regrades from the relevance read (≥0.8 HIGH, ≥0.5 MEDIUM, else LOW). Without this, any query watch item with a `severity_floor` above LOW would suppress every hit — which is what left the Monitoring section empty even while standing queries were returning material findings.\n\nWhich lane a proposal lands in is decided by `briefing.ranking.categorize`: an unrouted, low/medium signal from a monitoring source (`stock`, `vendor_status`, `rss`, `query`, `edgar`, `page_watch`, or any `external:*` topic tag) is `monitoring` (the collapsible Monitoring section); a routed or high/urgent one is `action` (the \"Needs you\" queue). The triage prompt's External Signals rule covers all six source kinds so it trusts the source and emits the `external:*` tags that drive this split.\n\nThe watchlist is editable from chat (`add_watchlist_entry`, `tune_watchlist_entry`) and HTTP (`/watchlist`); the `executive_research` workflow proposes what to watch through a deterministic policy (next section). Because that workflow is LLM-driven and historically proposed feed URLs it never verified (most were dead — 404 / 403 / not-actually-a-feed), every `rss` target is validated at insert time (`monitoring.target_validation`): a URL that fetches and parses as a feed is kept; a public page that isn't a feed is converted to a scrape-backed `page_watch` when xcrawl can read it, otherwise rejected (HTTP 422 / tool error); SSRF-blocked or unparseable URLs are rejected outright and never handed to xcrawl. Non-`rss` types insert unchanged with no network I/O.\n\n### One watch, one card — and dismissals teach the watch\n\n`promote_signal_to_alert` stamps the `AlertEvent` with `dedup_hint=\"watch:<slug>\"`, which `alerts.pipeline` uses as the *alert* dedup key. A repeat from the same watch coalesces into the open card (`occurrence_count`, `last_seen_at`, severity max) rather than minting another, and re-pings only when severity rose into high/urgent — so a ticker that stays over its threshold or an incident that keeps updating no longer produces a new \"Needs you\" item every day. The signal-level `dedup_key` (stock's UTC-date bucket, vendor_status's `<updated>`) is untouched, so every observation still lands in `external_signals`. Dismissing a watch-sourced alert calls `store.record_dismissal(slug)` (`dismiss_count += 1`, `trust_score = max(0.2, trust × 0.8)`); approving calls `record_confirmation` (+0.05). `trust_score` discounts the briefing ranking and is shown to the Executive's alert review as evidence, alongside the newer signals for that watch (a \"Resolved\" incident state, a reversed move) that let it close the card with evidence.\n\n### What the research pass may put on the watchlist\n\nEvery watchlist row carries an `origin`: `manual` (the principal, via UI/API), `executive` (the chat tool acting on a request), `research` (the research pass added it on its own) or `research_proposed` (a pending suggestion). The `executive_research` workflow's watchlist pass no longer calls `add_watchlist_entry`; its only tool is `propose_watch` (slug, signal_type, target, `grounding_entity`, `rationale`, `certainty`), and `monitoring.research.watch_policy` decides what happens to each proposal from company data, not from the model's confidence in itself:\n\n- **Direct add** — the row lands live, `origin=research`, with quiet defaults the model cannot loosen (daily cadence — hourly for `vendor_status`, weekly for `page_watch`/`query` — `severity_floor=medium`, a keyword trigger built from the grounding entity + material-event words + the current-year priorities for feeds, `abs_change_pct_gte=5` for stocks). Requires the `grounding_entity` to match the **grounding vocabulary** (the company name, `competitive_landscape.primary_competitors`, the profile's `vendors` and `tickers`, active initiative titles, current-year priorities) *and* a score ≥ 4 on a fixed ledger: +2 entity in company data (mandatory), +1 entity already watched under another source, +1 target is the entity's own source (its ticker, its domain, or a primary-source host such as sec.gov), +1 finding confidence high, +1 verification confirmed, +1 cross-specialist consensus, ±1 from the policy's own approval history for that `(signal_type, grounding kind)` once it has ≥5 samples. The model's `certainty` can only downgrade a direct add to a suggestion; a `query` watch is always a suggestion; above `WATCHLIST_MAX_ENABLED` (40) enabled watches every add becomes a suggestion. At most `WATCHLIST_RESEARCH_MAX_DIRECT_ADDS` (2) per run.\n- **Suggestion** — anything that validates but misses the bar is inserted in `dry_run` (polls and records signals, never alerts) with `origin=research_proposed` and the rationale in `notes`, at most `WATCHLIST_RESEARCH_MAX_PROPOSALS` (2) per run. `/watchlist` shows them in a \"Suggested by the Executive\" section with Approve (`POST /watchlist/{slug}/approve` → `active`, `origin=research`) and Decline (`POST /watchlist/{slug}/decline` with a reason: `not_relevant` blacklists the entity, `wrong_source` blacklists only this target, `too_noisy` keeps it live with `severity_floor=high`). A suggestion nobody reviews within `WATCHLIST_PROPOSAL_TTL_DAYS` (14) is removed. The morning brief mentions the pending count in one line; a `watchlist_suggestions` alert nudges only once ≥3 suggestions have waited ≥7 days.\n- **Reject** — an invalid target, a second watch on the same site + signal type, a declined target, or a spent budget. Every decision is audited (`watchlist_research_added` / `_suggested` / `_rejected`) with the score and reasons; the stamp also lives in the row's `config_json._policy` so approve/decline/auto-disable can attribute the outcome.\n\n**Declines are remembered and enforced.** `watchlist_declines` is keyed by the normalized target (upper-cased ticker; lower-cased URL without fragment or trailing slash). An explicit decline — the Decline button, \"Stop watching…\" on a research-added card, `remove_watchlist_entry` or `DELETE /watchlist/{slug}` on a research-origin row — is permanent; an unreviewed expiry may be re-proposed once after 90 days. The `propose_watch` handler refuses a declined target before the model sees a result, so a new slug cannot route around a decline; the list is also rendered to the model as DECLINED.\n\n**The policy learns from outcomes.** Approve, decline, expiry and auto-disable write `watchlist_policy_outcomes` rows keyed by `(signal_type, grounding kind, specialist)`; the pass renders the tallies (\"stock watches grounded in a competitor: 4 approved / 1 declined\"; \"proposals from cso: …\") and the score ledger reads them. The research turn also shows each existing watch's `origin`, `fired_count`, `dismiss_count` and `trust_score`.\n\n**Research watches retire themselves.** The scheduler's 15-minute sweep (`watch_policy.sweep`, alongside the alert expiry sweep) disables a `research`-origin watch — audited as `watchlist_auto_disabled`, re-enable from `/watchlist` — when it fired ≥5 alerts of which ≥2 were dismissed and trust ≤ 0.5, when a feed/page/status watch produced no signal in 30 days, or after 3 consecutive poll failures. Direct adds and auto-disables appear in the brief's \"handled overnight\" block as `watching` / `stopped_watching`. The research skip-if-unchanged fingerprint hashes only enabled, `active` rows, so approving or declining a suggestion never triggers a fresh 7-specialist run.\n\n### Invariants\n\n- Adapters are read-only — they never write upstream and never auto-execute.\n- Every `Signal` carries a deterministic `dedup_key` and a mandatory `provenance_url`.\n- Fetches are SSRF-guarded and bounded by `external_monitor_max_fetch_bytes`; xcrawl scrape (off by default, gated by `XCRAWL_ENABLED` + `XCRAWL_API_KEY`) is the one path that delegates the fetch to an external API.\n- Suppressed signals are still persisted so audits show the full picture.\n- A repeat from the same watch never becomes a second open card: the alert-level `watch:<slug>` key coalesces it, and only a severity escalation re-dispatches.\n- The research model never writes the watchlist: it proposes, deterministic policy adds (only when grounded in company data) or suggests, and a target the principal declined is refused at the handler.","mermaid": "flowchart TD\n ADD[\"add (chat tool / POST /watchlist / research)\"]\n VAL[\"target_validation: rss feed? → keep / convert→page_watch(xcrawl) / reject\"]\n WL[(\"watchlist\")]\n HB[\"external_monitor_scan heartbeat (~5 min)\"]\n AD[\"read-only adapters: vendor_status / rss / stock / query / edgar / page_watch (httpx | xcrawl)\"]\n SIG[(\"external_signals UNIQUE(dedup_key)\")]\n ENRICH[\"capture-time enrichment<br/>(relevance score + why_it_matters)\"]\n PROMO[\"promote_signal_to_alert\"]\n PIPE[\"alert pipeline (triage)\"]\n TODAY[\"/today proposals\"]\n ADD --> VAL\n VAL -->|\"insert valid rows\"| WL\n HB -->|\"walk enabled rows\"| WL\n WL -->|\"poll due rows\"| AD\n AD -->|\"emit Signal\"| SIG\n SIG -->|\"baseline / stale / dry_run / floor gates\"| ENRICH\n ENRICH -->|\"≥ relevance floor\"| PROMO\n PROMO --> PIPE\n PIPE --> TODAY\n class HB hot\n class WL storage\n class VAL compute\n class AD external\n class SIG storage\n class ENRICH compute\n class PROMO compute\n class PIPE compute\n class TODAY entry\n class ADD compute",- "generated_at": "2026-09-11T19:18:55+00:00"+ "generated_at": "2026-09-12T10:42:31.179581+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/scheduler.json b/packages/core/openexecutive/architecture/prebuilt/scheduler.jsonindex b738fa4c..2f2fc0d6 100644--- a/packages/core/openexecutive/architecture/prebuilt/scheduler.json+++ b/packages/core/openexecutive/architecture/prebuilt/scheduler.json@@ -1,7 +1,7 @@{"section_id": "scheduler","title": "Scheduler & Cadences",- "markdown": "The scheduler is an asyncio task started in the FastAPI lifespan (`openexecutive.scheduler.runner.run_scheduler`). It polls every 30s and reads due rows from `scheduled_actions` (in `episodic_memory.db`). The due query uses `claim_due_actions`, an UPDATE…RETURNING claim, so each row fires at most once per process — this assumes a single scheduler instance per database. Polls are gated on an active company profile via `_company_profile_active()`; before onboarding, due rows stay `pending`.\n\n### Cadence DSL\n\n`openexecutive.departments.cadence` supports, all in UTC:\n\n- `daily@HH:MM`\n- `weekly@DOW@HH:MM` or `weekly@DOW-HH:MM` (DOW is a 3-letter day, e.g. `weekly@thu@09:00`)\n- `quarterly@DD-HH:MM`\n\nWhen a department cadence is due, the runner invokes the `department_check_in` workflow and chains the following occurrence via `cadence.enqueue_next()`. Deleting a department cancels its pending `dept_cadence` rows, and `cancel_orphaned_cadences()` sweeps orphans on boot.\n\nUser-created (dynamic) workflows can carry the same cadence DSL. A cadence-enabled definition enqueues a `dynamic_workflow` action (`workflows.dynamic_cadence`); when due, the runner runs the stored `DynamicWorkflow`, DMs the artifact to the definition's `cadence_person_id`, and re-chains the next occurrence. Saving/updating/deleting the definition reconciles its pending `dynamic_workflow` rows.\n\n### Channel routing & nudges\n\nThe delivery channel lives on the `scheduled_actions` row (`channel` / `channel_ref`); the runner dispatches through whichever was set at enqueue time — `telegram`, `slack_dm`, `discord_dm`, `email`, or `__internal__` (workflow steps and heartbeats bypass outbound dispatch). The nudge engine (`scheduler.nudge_engine`, default 15 min) scans stalled `awaiting_human` runs, stale commitments, and idle initiatives, then emits `proactive_nudge` rows routed via `people.channel.prefer_channel_for` — honouring each Person's preferred (last-used) channel and availability windows, deferring those outside their window and skipping those with no reachable channel. Emission is capped per `scope_key` (`NUDGE_MAX_PER_SCOPE`, default 3 delivered nudges) so a parked item is not chased forever.\n\n### Alert lifecycle: expiry sweep and the review heartbeat\n\nTwo alert-maintenance jobs live here. The **expiry sweep** is loop-level, not a heartbeat row: `_maybe_sweep_alerts` runs `alerts.lifecycle.expire_stale_alerts` once at boot and every 15 minutes at the top of the tick — before the company-profile and rotation gates, so an old backlog expires even before onboarding completes, flipping `unread` alerts past their category TTL to `expired` and auditing `alert_sweep`. Pure DB hygiene, no model call, reversible via `POST /alerts/{id}/reopen`.\n\nThe **Executive alert review** is a real heartbeat — kind `alert_review_scan`, `__internal__` channel, bootstrapped idempotently at startup when `ALERT_REVIEW_ENABLED` and chained every `ALERT_REVIEW_INTERVAL_HOURS` (6) with the same crash-resilient run → mark-done → chain shape as `nudge_scan`. `_run_principal_brief` also runs a `pre_brief` pass right before the morning brief (a review failure never blocks the brief). Each pass re-examines open alerts with evidence and, within department authority and the privacy rule, routes, nudges, escalates, drafts, merges or resolves them — see the Today section for the policy. The moves go through the real handlers (`message_person`, `draft_artifact`), so the outbound anti-spam guard applies, and `ALERT_REVIEW_MAX_MOVES_PER_SCAN` bounds side effects per pass.\n\n### Bounded onboarding ramp drip\n\nStaff onboarding adds the `onboarding_ramp` action kind — the one *self-terminating* recurring action (every other recurring kind chains forever). `staff_onboarding.service.activate_plan` enqueues the first occurrence; on each fire the runner claims the plan's next pre-generated ramp segment via an atomic compare-and-swap on `ramp_next_index` (`store.claim_next_ramp_segment`), DMs it to the hire with `message_person`, and chains the next **business-day** occurrence ONLY while segments remain — then stops. It no-ops unless the plan has a roster `person_id` and generated `ramp_segments`.\n\n### Onboarding orchestration & check-ins\n\n`activate_plan` also enqueues two more kinds (idempotently, via `staff_onboarding.orchestration`):\n\n- `onboarding_kickoff` — one-shot, fires the next tick: a welcome notice to the hire's **department channel only when one is configured** (no accidental broadcast — routed through the privacy-gated, audited `broadcast_tools.post_department_notice`, which applies the same length cap + privacy backstop + audit trail as `send_department_message`, to the first configured Slack/Discord/Telegram channel), plus intro-1:1 nudge DMs to the manager and buddy.\n- `onboarding_checkin` — milestone check-ins at **day 7 / 30 / 60 / 90**. Each milestone is its own pre-scheduled row (no self-chaining); milestones already in the past at activation are skipped. On fire it DMs the hire + manager a check-in and advances the plan's phase deterministically (forward-only). Because `wait_for_human` resume is a Phase-7 item, replies aren't auto-resumed — they land in chat, where the Executive's onboarding tools fold them into task/plan progress.\n\n## Client rotation claim pause\n\nThe `client_rotation` kind (multi-client practice mode, opt-in via `CLIENT_ROTATION_ENABLED`) adds one loop-level behavior: while a rotation's `.rotation_in_progress` marker exists, the scheduler **skips claiming entirely** for that tick. Rotation switches the live company context between parked clients; claiming during the window would fire the just-activated client's overdue outbound follow-ups from a context nobody is watching. Everything due fires on the first tick after the original client is restored. Stale markers (crash mid-rotation) are reconciled at scheduler startup, and the rotation row is idempotently re-seeded both at boot and after every slot activation (scheduled rows swap with the client). See the Client Companies section for the rotation's full design.\n\nAn optional `notion_sync_scan` heartbeat (`NOTION_SYNC_ENABLED`, off by default) incrementally re-indexes Notion pages the workspace integration can see into the isolated `notion_wiki` collection (not COMPANY), reconciles un-shared pages, then chains the next tick.",+ "markdown": "The scheduler is an asyncio task started in the FastAPI lifespan (`openexecutive.scheduler.runner.run_scheduler`). It polls every 30s and reads due rows from `scheduled_actions` (in `episodic_memory.db`). The due query uses `claim_due_actions`, an UPDATE…RETURNING claim, so each row fires at most once per process — this assumes a single scheduler instance per database. Polls are gated on an active company profile via `_company_profile_active()`; before onboarding, due rows stay `pending`.\n\n### Cadence DSL\n\n`openexecutive.departments.cadence` supports, all in UTC:\n\n- `daily@HH:MM`\n- `weekly@DOW@HH:MM` or `weekly@DOW-HH:MM` (DOW is a 3-letter day, e.g. `weekly@thu@09:00`)\n- `quarterly@DD-HH:MM`\n\nWhen a department cadence is due, the runner invokes the `department_check_in` workflow and chains the following occurrence via `cadence.enqueue_next()`. Deleting a department cancels its pending `dept_cadence` rows, and `cancel_orphaned_cadences()` sweeps orphans on boot.\n\nUser-created (dynamic) workflows can carry the same cadence DSL. A cadence-enabled definition enqueues a `dynamic_workflow` action (`workflows.dynamic_cadence`); when due, the runner runs the stored `DynamicWorkflow`, DMs the artifact to the definition's `cadence_person_id`, and re-chains the next occurrence. Saving/updating/deleting the definition reconciles its pending `dynamic_workflow` rows.\n\n### Channel routing & nudges\n\nThe delivery channel lives on the `scheduled_actions` row (`channel` / `channel_ref`); the runner dispatches through whichever was set at enqueue time — `telegram`, `slack_dm`, `discord_dm`, `email`, or `__internal__` (workflow steps and heartbeats bypass outbound dispatch). The nudge engine (`scheduler.nudge_engine`, default 15 min) scans stalled `awaiting_human` runs, stale commitments, and idle initiatives, then emits `proactive_nudge` rows routed via `people.channel.prefer_channel_for` — honouring each Person's preferred (last-used) channel and availability windows, deferring those outside their window and skipping those with no reachable channel. Emission is capped per `scope_key` (`NUDGE_MAX_PER_SCOPE`, default 3 delivered nudges) so a parked item is not chased forever.\n\n### Alert lifecycle: expiry sweep and the review heartbeat\n\nTwo alert-maintenance jobs live here. The **expiry sweep** is loop-level, not a heartbeat row: `_maybe_sweep_alerts` runs `alerts.lifecycle.expire_stale_alerts` (and, on the same 15-minute throttle, `monitoring.research.watch_policy.sweep` — expiring unreviewed research watch suggestions, auto-disabling research-added watches that proved noisy or dead, and filing one `watchlist_suggestions` nudge when ≥3 suggestions have waited ≥7 days; see External monitoring) once at boot and every 15 minutes at the top of the tick — before the company-profile and rotation gates, so an old backlog expires even before onboarding completes, flipping `unread` alerts past their category TTL to `expired` and auditing `alert_sweep`. Pure DB hygiene, no model call, reversible via `POST /alerts/{id}/reopen`.\n\nThe **Executive alert review** is a real heartbeat — kind `alert_review_scan`, `__internal__` channel, bootstrapped idempotently at startup when `ALERT_REVIEW_ENABLED` and chained every `ALERT_REVIEW_INTERVAL_HOURS` (6) with the same crash-resilient run → mark-done → chain shape as `nudge_scan`. `_run_principal_brief` also runs a `pre_brief` pass right before the morning brief (a review failure never blocks the brief). Each pass re-examines open alerts with evidence and, within department authority and the privacy rule, routes, nudges, escalates, drafts, merges or resolves them — see the Today section for the policy. The moves go through the real handlers (`message_person`, `draft_artifact`), so the outbound anti-spam guard applies, and `ALERT_REVIEW_MAX_MOVES_PER_SCAN` bounds side effects per pass.\n\n### Bounded onboarding ramp drip\n\nStaff onboarding adds the `onboarding_ramp` action kind — the one *self-terminating* recurring action (every other recurring kind chains forever). `staff_onboarding.service.activate_plan` enqueues the first occurrence; on each fire the runner claims the plan's next pre-generated ramp segment via an atomic compare-and-swap on `ramp_next_index` (`store.claim_next_ramp_segment`), DMs it to the hire with `message_person`, and chains the next **business-day** occurrence ONLY while segments remain — then stops. It no-ops unless the plan has a roster `person_id` and generated `ramp_segments`.\n\n### Onboarding orchestration & check-ins\n\n`activate_plan` also enqueues two more kinds (idempotently, via `staff_onboarding.orchestration`):\n\n- `onboarding_kickoff` — one-shot, fires the next tick: a welcome notice to the hire's **department channel only when one is configured** (no accidental broadcast — routed through the privacy-gated, audited `broadcast_tools.post_department_notice`, which applies the same length cap + privacy backstop + audit trail as `send_department_message`, to the first configured Slack/Discord/Telegram channel), plus intro-1:1 nudge DMs to the manager and buddy.\n- `onboarding_checkin` — milestone check-ins at **day 7 / 30 / 60 / 90**. Each milestone is its own pre-scheduled row (no self-chaining); milestones already in the past at activation are skipped. On fire it DMs the hire + manager a check-in and advances the plan's phase deterministically (forward-only). Because `wait_for_human` resume is a Phase-7 item, replies aren't auto-resumed — they land in chat, where the Executive's onboarding tools fold them into task/plan progress.\n\n## Client rotation claim pause\n\nThe `client_rotation` kind (multi-client practice mode, opt-in via `CLIENT_ROTATION_ENABLED`) adds one loop-level behavior: while a rotation's `.rotation_in_progress` marker exists, the scheduler **skips claiming entirely** for that tick. Rotation switches the live company context between parked clients; claiming during the window would fire the just-activated client's overdue outbound follow-ups from a context nobody is watching. Everything due fires on the first tick after the original client is restored. Stale markers (crash mid-rotation) are reconciled at scheduler startup, and the rotation row is idempotently re-seeded both at boot and after every slot activation (scheduled rows swap with the client). See the Client Companies section for the rotation's full design.\n\nAn optional `notion_sync_scan` heartbeat (`NOTION_SYNC_ENABLED`, off by default) incrementally re-indexes Notion pages the workspace integration can see into the isolated `notion_wiki` collection (not COMPANY), reconciles un-shared pages, then chains the next tick.","mermaid": "flowchart TD\n Loop[\"run_scheduler<br/>poll every 30s\"]\n Claim[\"claim_due_actions<br/>(status=pending, by kind)\"]\n Table[(\"scheduled_actions\")]\n Dispatch[\"dispatch via row channel<br/>(ad_hoc / proactive_nudge)\"]\n Dept[\"dept_cadence →<br/>department_check_in\"]\n Nudge[\"nudge_scan →<br/>nudge_engine scan\"]\n Brief[\"principal_brief_morning / _eod →<br/>morning_brief / end_of_day_digest\"]\n Reflect[\"executive_reflection →<br/>reflection (artifact only)\"]\n ExtMon[\"external_monitor_scan →<br/>monitoring pipeline\"]\n Research[\"watchlist_research_scan →<br/>executive_research (skip-if-unchanged)\"]\n Notion[\"notion_sync_scan →<br/>isolated wiki ingest\"]\n Chain[\"enqueue_next<br/>(re-arm recurring tick)\"]\n Prefer[\"prefer_channel_for<br/>(availability + last-used)\"]\n Channels[\"Slack / Discord<br/>Telegram / Email\"]\n Principal[\"DM principal\"]\n Alerts[\"alerts pipeline → /today\"]\n Loop --> Claim\n Claim -- \"claim due rows\" --> Table\n Claim -- \"ad_hoc / proactive_nudge\" --> Dispatch\n Claim -- \"dept_cadence\" --> Dept\n Claim -- \"nudge_scan\" --> Nudge\n Claim -- \"principal_brief_*\" --> Brief\n Claim -- \"executive_reflection\" --> Reflect\n Claim -- \"external_monitor_scan\" --> ExtMon\n Claim -- \"watchlist_research_scan\" --> Research\n Claim -- \"notion_sync_scan\" --> Notion\n Nudge -- \"prefer_channel_for\" --> Prefer\n Prefer -- \"emits proactive_nudge\" --> Table\n Dispatch --> Channels\n Brief --> Principal\n ExtMon --> Alerts\n Dept --> Chain\n Nudge --> Chain\n Brief --> Chain\n Reflect --> Chain\n ExtMon --> Chain\n Research --> Chain\n Notion --> Chain\n Chain --> Table\n class Loop entry\n class Claim compute\n class Table storage\n class Dispatch compute\n class Dept compute\n class Nudge compute\n class Brief compute\n class Reflect compute\n class ExtMon compute\n class Research compute\n class Notion compute\n class Chain compute\n class Prefer compute\n class Channels external\n class Principal external\n class Alerts hot",- "generated_at": "2026-09-11T19:36:35+00:00"+ "generated_at": "2026-09-12T10:45:28.240804+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/today.json b/packages/core/openexecutive/architecture/prebuilt/today.jsonindex 7b4fe208..2d4715a4 100644--- a/packages/core/openexecutive/architecture/prebuilt/today.json+++ b/packages/core/openexecutive/architecture/prebuilt/today.json@@ -1,7 +1,7 @@{"section_id": "today","title": "Today / Morning Brief",- "markdown": "`openexecutive.api.routes.today` serves the morning brief — a one-screen, read-only view of what is happening across the org. It is the default landing surface (the Next.js root renders `<Briefing>`).\n\n`GET /today` returns `TodayResponse` assembled by `_build_today()`, which is synchronous and caller-agnostic:\n\n- **`departments`** — per-department goal health, rolling up each department's goal counts (`total`, `at_risk`, `off_track`) plus its awaiting-workflow count, and `attention_goals`: the actual off-track/at-risk goals (worst first, capped at 3) with `key_result`, `current`, `target`, and `status`, so the briefing's Department card shows *which* goal is off and how far without a click. Empty for healthy/inactive departments.\n- **`people`** — an attention-ranked roster. Each person carries `awaiting_action` count, soonest SLA, a `status` (`on_leave` / `needs_reply` / `awaiting` / `clear`), reachability, `overdue`, a server `priority` sort key, and a cached one-line `insight`. Sorted by `(-priority, full_name)`.\n- **`proposals`** — the *live* unread alerts (workflow approvals, triage-classified inbound, Executive signals, flagged artifacts, and gated calendar bookings): unread, inside their category TTL, not snoozed — see *Alert lifecycle* below. Each carries `score`, `category` (`action` vs `monitoring`), `surfaced_reason` from `openexecutive.briefing.ranking`, the lifecycle fields (`occurrence_count`, `last_seen_at`, `last_reviewed_at`, `review_verdict`, `review_note`, `recommended_move`, `why_now`, `due_at`, `superseded_count`, `suggested_workflow`), and `decision_instance_id` (set only when the proposal is backed by a decision-ledger row — a calendar booking awaiting approval). The UI splits them into 'mine' vs 'across the team' using `caller_person_id`. For decision-backed proposals the card's Approve/Reject call the `/decisions` endpoints (which book or cancel the event server-side and clear the alert) instead of the ack-and-hand-off-to-chat flow — so meeting bookings are reviewed in the briefing itself rather than on a separate page.\n- **`narrative`** — a per-viewer Executive-voice header synthesized by `synthesize_briefing_narrative`; the principal gets the whole-company scope, teammates a role-scoped one. In the web UI each bullet of this narrative is a click target: clicking one hands off to chat (the same `onContinue` path as the proposal cards) seeded to discuss that item. The Executive recognizes it because every chat turn now carries a `<briefing>` digest of open alerts (see Memory).\n- **`in_flight`** / **`awaiting`** — upcoming Executive commitments and people we are waiting on.\n- **`handled_overnight`** — the autonomous moves the Executive's alert review made since the last delivered morning brief (routed, nudged, escalated, drafted, merged, closed, updated), each with the alert id so the UI can offer Undo.\n- **`talent`** — the active executive-search pipeline, rolled up by `briefing.talent_digest.build_talent_brief_items`: one item per non-terminal engagement (FILLED/CANCELLED dropped) with role, department, status, candidate count, per-stage counts, and four attention signals — `offers_expiring_soon` (extended offers within 72h of `expires_at`, or past it with no decision recorded — computed straight from the offers table so a missed nudge can't make the briefing stale), `needs_screening` (leads), `offers_out` (offers), and `stalled_count` (active candidates not touched in ≥7 days). Items sort expiring → offers → stalled → leads → size. It renders as the briefing's **Executive search** card (one per search; click-to-discuss hands off to chat via the same `onContinue` path), feeds the narrative (an offer landing or a search going cold re-writes the header — the narrative cache hash folds a talent fingerprint), and the same digest's `format_talent_for_prompt` is appended to the chat `<briefing>` block so the Executive can discuss live searches by client or role. One rollup, shared by all four surfaces, so the card / header / chat never disagree. See the Talent section.\n\nThe route resolves the caller from `x-caller-email`, then attaches the viewer-scoped narrative in a `BackgroundTask` so the request never blocks on an LLM call. `GET /today/activity` returns the recent self-initiated action rail — merged from fired scheduled actions (DMs, follow-ups, nudges, cadences), logged decisions, saved advice, completed workflow runs (briefings/check-ins/research), kicked-off initiatives, resolved gated decisions, and raised alerts, so it reflects all of the Executive's activity rather than just dispatched messages. The Pulse page (`/memories`) polls it (limit 100) every ~20s so new events stream into the 'Recent activity' card, which scrolls internally at a fixed height instead of growing the page. The `morning_brief` workflow calls `_build_today()` directly to build the standalone DM (via a different, enumerated prompt). `GET /morning-brief` is a deprecated alias.\n\n## Alert lifecycle & the Executive review\n\nAlerts used to be write-once: raised, then never looked at again, so the \"Needs you\" queue grew without bound and the briefs re-listed it daily. Three things now keep it live:\n\n- **Time-to-live** (`openexecutive.alerts.lifecycle`). Action items expire after `ALERT_TTL_DAYS_ACTION` (14 d), unrouted low/medium monitoring signals after `ALERT_TTL_DAYS_MONITORING` (3 d). Every surface reads `list_live_alerts` (the same predicate the scheduler's 15-minute sweep persists as status `expired`), so `/today` is right even before the sweep runs. Artifacts and decision-backed alerts are exempt. `POST /alerts/{id}/reopen` is the Undo.\n- **Coalescing** (`alerts.pipeline` + `store.coalesce_alert`). A repeat of an open alert with the same `(source, dedup_key)` updates that row — `occurrence_count`, `last_seen_at`, severity max — instead of stacking a second card, and only re-pings when severity rose to high/urgent. Monitoring alerts carry a stable `watch:<slug>` key, so one watch means one card.\n- **The review** (`openexecutive.alerts.review`, heartbeat `alert_review_scan`, every 6 h and right before the morning brief). For each open alert the Executive sees what changed since it was raised — newer signals from the same watch, related alerts, activity since, the roster with SLAs, department authority — and returns a verdict (relevant / changed / resolved / stale) plus a recommended move. Deterministic policy then acts: **route** (assign + DM the owner; `propose_via_alert` for propose-only departments), **nudge**, **escalate** (severity + `due_at` + DM the principal only), **draft** (`draft_artifact`), **suggest a workflow** (a link, never a run), **merge** (`superseded_by_alert_id`), or **resolve** — only on high confidence citing a server-minted evidence ref (a newer signal, a related alert, an activity item shown for that alert); free text never closes a card, and anything weaker is annotated `likely_stale`, demoted 30 ranking points, and left for one click. Everything that came from outside is rendered as inert data inside the review prompt, so an injected email body cannot steer the batch. Board / comp / legal matters only ever go to a scope-holder or the principal and keep their text. Route and escalate are idempotent across passes, every DM carries an \"[Alert review] Re: …\" header, outbound moves are capped per pass, passes are single-flight, `ALERT_REVIEW_ENABLED=false` stops every caller, every move is audited with its evidence and prior state, and a distinct `resolved` status keeps Executive closes separate from `ack` (user approved).\n\nOn the page, cards read as decisions: the one-line \"what changed since you last looked\" (`review_note`) leads, the recommended move is the primary control (Nudge <owner> → chat; Run <workflow> → `/jobs/<name>`), with chips for age, seen ×N, why-now / due, folded-in and draft-ready, a \"Reviewed <ago>\" footer, and an amber Likely-stale treatment with one-click Dismiss. \"Needs you\" shows *Start here* + 8 cards + \"Show N more\", a \"Dismiss N older than 7 days\" footer (explicit ids to `POST /alerts/bulk-ack` — never a server-side age sweep, which would hit teammates' routed items), and \"Re-check relevance\" (`POST /alerts/review`). The \"Handled overnight\" rail and the \"Executive handled N overnight\" pill show what the review did, with Undo. Dismissing a watch-sourced alert lowers that watch's `trust_score` (which discounts ranking and is shown to the review as evidence); the ack body may carry `mute_topic`.\n\n## Multi-client practice section\n\nIn multi-client practice mode (2+ client slots — see the Client Companies section), the response gains an additive `practice_clients` list: rollup cards for the **parked** clients (overdue follow-ups, awaiting replies, unread alerts, onboarding due soon, renewal countdowns), each stamped with the save point its data reflects. Single-company installs always receive an empty list and the UI renders nothing.",+ "markdown": "`openexecutive.api.routes.today` serves the morning brief — a one-screen, read-only view of what is happening across the org. It is the default landing surface (the Next.js root renders `<Briefing>`).\n\n`GET /today` returns `TodayResponse` assembled by `_build_today()`, which is synchronous and caller-agnostic:\n\n- **`departments`** — per-department goal health, rolling up each department's goal counts (`total`, `at_risk`, `off_track`) plus its awaiting-workflow count, and `attention_goals`: the actual off-track/at-risk goals (worst first, capped at 3) with `key_result`, `current`, `target`, and `status`, so the briefing's Department card shows *which* goal is off and how far without a click. Empty for healthy/inactive departments.\n- **`people`** — an attention-ranked roster. Each person carries `awaiting_action` count, soonest SLA, a `status` (`on_leave` / `needs_reply` / `awaiting` / `clear`), reachability, `overdue`, a server `priority` sort key, and a cached one-line `insight`. Sorted by `(-priority, full_name)`.\n- **`proposals`** — the *live* unread alerts (workflow approvals, triage-classified inbound, Executive signals, flagged artifacts, and gated calendar bookings): unread, inside their category TTL, not snoozed — see *Alert lifecycle* below. Each carries `score`, `category` (`action` vs `monitoring`), `surfaced_reason` from `openexecutive.briefing.ranking`, the lifecycle fields (`occurrence_count`, `last_seen_at`, `last_reviewed_at`, `review_verdict`, `review_note`, `recommended_move`, `why_now`, `due_at`, `superseded_count`, `suggested_workflow`), and `decision_instance_id` (set only when the proposal is backed by a decision-ledger row — a calendar booking awaiting approval). The UI splits them into 'mine' vs 'across the team' using `caller_person_id`. For decision-backed proposals the card's Approve/Reject call the `/decisions` endpoints (which book or cancel the event server-side and clear the alert) instead of the ack-and-hand-off-to-chat flow — so meeting bookings are reviewed in the briefing itself rather than on a separate page.\n- **`narrative`** — a per-viewer Executive-voice header synthesized by `synthesize_briefing_narrative`; the principal gets the whole-company scope, teammates a role-scoped one. In the web UI each bullet of this narrative is a click target: clicking one hands off to chat (the same `onContinue` path as the proposal cards) seeded to discuss that item. The Executive recognizes it because every chat turn now carries a `<briefing>` digest of open alerts (see Memory).\n- **`in_flight`** / **`awaiting`** — upcoming Executive commitments and people we are waiting on.\n- **`handled_overnight`** — the autonomous moves the Executive made since the last delivered morning brief: the alert review's (routed, nudged, escalated, drafted, merged, closed, updated), each with the alert id so the UI can offer Undo, plus the research watch policy's (`watching` — a watch added on its own because it was grounded in company data; `stopped_watching` — a research watch auto-disabled as noisy or dead; no alert id, re-enable from `/watchlist`). The morning brief also carries a one-line count of research watch suggestions waiting on `/watchlist`.\n- **`talent`** — the active executive-search pipeline, rolled up by `briefing.talent_digest.build_talent_brief_items`: one item per non-terminal engagement (FILLED/CANCELLED dropped) with role, department, status, candidate count, per-stage counts, and four attention signals — `offers_expiring_soon` (extended offers within 72h of `expires_at`, or past it with no decision recorded — computed straight from the offers table so a missed nudge can't make the briefing stale), `needs_screening` (leads), `offers_out` (offers), and `stalled_count` (active candidates not touched in ≥7 days). Items sort expiring → offers → stalled → leads → size. It renders as the briefing's **Executive search** card (one per search; click-to-discuss hands off to chat via the same `onContinue` path), feeds the narrative (an offer landing or a search going cold re-writes the header — the narrative cache hash folds a talent fingerprint), and the same digest's `format_talent_for_prompt` is appended to the chat `<briefing>` block so the Executive can discuss live searches by client or role. One rollup, shared by all four surfaces, so the card / header / chat never disagree. See the Talent section.\n\nThe route resolves the caller from `x-caller-email`, then attaches the viewer-scoped narrative in a `BackgroundTask` so the request never blocks on an LLM call. `GET /today/activity` returns the recent self-initiated action rail — merged from fired scheduled actions (DMs, follow-ups, nudges, cadences), logged decisions, saved advice, completed workflow runs (briefings/check-ins/research), kicked-off initiatives, resolved gated decisions, and raised alerts, so it reflects all of the Executive's activity rather than just dispatched messages. The Pulse page (`/memories`) polls it (limit 100) every ~20s so new events stream into the 'Recent activity' card, which scrolls internally at a fixed height instead of growing the page. The `morning_brief` workflow calls `_build_today()` directly to build the standalone DM (via a different, enumerated prompt). `GET /morning-brief` is a deprecated alias.\n\n## Alert lifecycle & the Executive review\n\nAlerts used to be write-once: raised, then never looked at again, so the \"Needs you\" queue grew without bound and the briefs re-listed it daily. Three things now keep it live:\n\n- **Time-to-live** (`openexecutive.alerts.lifecycle`). Action items expire after `ALERT_TTL_DAYS_ACTION` (14 d), unrouted low/medium monitoring signals after `ALERT_TTL_DAYS_MONITORING` (3 d). Every surface reads `list_live_alerts` (the same predicate the scheduler's 15-minute sweep persists as status `expired`), so `/today` is right even before the sweep runs. Artifacts and decision-backed alerts are exempt. `POST /alerts/{id}/reopen` is the Undo.\n- **Coalescing** (`alerts.pipeline` + `store.coalesce_alert`). A repeat of an open alert with the same `(source, dedup_key)` updates that row — `occurrence_count`, `last_seen_at`, severity max — instead of stacking a second card, and only re-pings when severity rose to high/urgent. Monitoring alerts carry a stable `watch:<slug>` key, so one watch means one card.\n- **The review** (`openexecutive.alerts.review`, heartbeat `alert_review_scan`, every 6 h and right before the morning brief). For each open alert the Executive sees what changed since it was raised — newer signals from the same watch, related alerts, activity since, the roster with SLAs, department authority — and returns a verdict (relevant / changed / resolved / stale) plus a recommended move. Deterministic policy then acts: **route** (assign + DM the owner; `propose_via_alert` for propose-only departments), **nudge**, **escalate** (severity + `due_at` + DM the principal only), **draft** (`draft_artifact`), **suggest a workflow** (a link, never a run), **merge** (`superseded_by_alert_id`), or **resolve** — only on high confidence citing a server-minted evidence ref (a newer signal, a related alert, an activity item shown for that alert); free text never closes a card, and anything weaker is annotated `likely_stale`, demoted 30 ranking points, and left for one click. Everything that came from outside is rendered as inert data inside the review prompt, so an injected email body cannot steer the batch. Board / comp / legal matters only ever go to a scope-holder or the principal and keep their text. Route and escalate are idempotent across passes, every DM carries an \"[Alert review] Re: …\" header, outbound moves are capped per pass, passes are single-flight, `ALERT_REVIEW_ENABLED=false` stops every caller, every move is audited with its evidence and prior state, and a distinct `resolved` status keeps Executive closes separate from `ack` (user approved).\n\nOn the page, cards read as decisions: the one-line \"what changed since you last looked\" (`review_note`) leads, the recommended move is the primary control (Nudge <owner> → chat; Run <workflow> → `/jobs/<name>`), with chips for age, seen ×N, why-now / due, folded-in and draft-ready, a \"Reviewed <ago>\" footer, and an amber Likely-stale treatment with one-click Dismiss. \"Needs you\" shows *Start here* + 8 cards + \"Show N more\", a \"Dismiss N older than 7 days\" footer (explicit ids to `POST /alerts/bulk-ack` — never a server-side age sweep, which would hit teammates' routed items), and \"Re-check relevance\" (`POST /alerts/review`). The \"Handled overnight\" rail and the \"Executive handled N overnight\" pill show what the review did, with Undo. Dismissing a watch-sourced alert lowers that watch's `trust_score` (which discounts ranking and is shown to the review as evidence); the ack body may carry `mute_topic`.\n\n## Multi-client practice section\n\nIn multi-client practice mode (2+ client slots — see the Client Companies section), the response gains an additive `practice_clients` list: rollup cards for the **parked** clients (overdue follow-ups, awaiting replies, unread alerts, onboarding due soon, renewal countdowns), each stamped with the save point its data reflects. Single-company installs always receive an empty list and the UI renders nothing.","mermaid": "flowchart TD\n REQ[\"GET /today\"]\n BUILD[\"_build_today()\"]\n DEPTS[\"departments<br/>(per-dept goal health)\"]\n ROSTER[\"people<br/>(attention-ranked roster)\"]\n PROPS[\"proposals<br/>(unread alerts, routed)\"]\n INFLIGHT[\"in_flight<br/>(pending follow-ups / nudges)\"]\n AWAIT[\"awaiting<br/>(replies we await)\"]\n TALENT[\"talent<br/>(open searches, by stage)\"]\n NARR[\"viewer-scoped narrative (BackgroundTask)\"]\n MB[\"morning_brief workflow\"]\n REQ --> BUILD\n BUILD --> DEPTS\n BUILD --> ROSTER\n BUILD --> PROPS\n BUILD --> INFLIGHT\n BUILD --> AWAIT\n BUILD --> TALENT\n REQ -->|\"resolve caller, attach\"| NARR\n MB -->|\"calls directly for standalone DM\"| BUILD\n class REQ entry\n class BUILD compute\n class DEPTS storage\n class ROSTER storage\n class PROPS storage\n class INFLIGHT storage\n class AWAIT storage\n class TALENT storage\n class NARR compute\n class MB compute",- "generated_at": "2026-09-11T19:36:35+00:00"+ "generated_at": "2026-09-12T10:49:14.352822+00:00"}diff --git a/packages/core/openexecutive/briefing/brief_state.py b/packages/core/openexecutive/briefing/brief_state.pyindex 1cfcf956..2a2d7e62 100644--- a/packages/core/openexecutive/briefing/brief_state.py+++ b/packages/core/openexecutive/briefing/brief_state.py@@ -52,6 +52,15 @@ REVIEW_EVENT_TYPES: tuple[str, ...] = ("alert_review_changed",)+# Every audit event type the handled block reads, mapped to the short kind+# the brief and the /today rail render. The research watch policy's+# autonomous moves ride alongside the alert review's.+HANDLED_EVENT_KINDS: dict[str, str] = {+ **{t: t.removeprefix("alert_review_") for t in REVIEW_EVENT_TYPES},+ "watchlist_research_added": "watching",+ "watchlist_auto_disabled": "stopped_watching",+}+def scope_for(kind: str) -> str:return f"{SCOPE_PREFIX}{kind}"@@ -123,11 +132,11 @@ def handled_since(since: datetime, limit: int = 20) -> list[dict[str, Any]]:logger_ = get_audit_logger()out: list[dict[str, Any]] = []- for event_type in REVIEW_EVENT_TYPES:+ for event_type, kind in HANDLED_EVENT_KINDS.items():for ev in logger_.query(event_type=event_type, since=since.isoformat(), limit=limit):details = ev.details if isinstance(ev.details, dict) else {}out.append({- "kind": event_type.removeprefix("alert_review_"),+ "kind": kind,"summary": ev.summary,"at": ev.ts,"alert_id": details.get("alert_id"),@@ -145,6 +154,7 @@ def build_brief_fingerprint(activity: list[dict[str, Any]],handled: list[dict[str, Any]],since: datetime | None,+ pending_watch_suggestions: int = 0,) -> str:"""Stable hash of everything the brief would say. Deliberately free ofdates and timestamps so an unchanged day yields the same fingerprint@@ -166,6 +176,7 @@ def build_brief_fingerprint("awaiting": sorted(int(p.get("id", 0)) for p in today_data.get("people", []) if p.get("awaiting_count", 0)),+ "watch_suggestions": int(pending_watch_suggestions),}blob = json.dumps(payload, sort_keys=True, default=str)return hashlib.sha256(blob.encode("utf-8")).hexdigest()@@ -186,12 +197,26 @@ def suppressed_line(n_waiting: int) -> str:return SUPPRESSED_TEMPLATE.format(n=n_waiting, s="" if n_waiting == 1 else "s")+def pending_watch_suggestions() -> int:+ """Research watch suggestions awaiting the principal on /watchlist.+ Zero when the monitoring store is unavailable."""+ try:+ from openexecutive.monitoring import store as monitoring_store++ return len(monitoring_store.list_pending_suggestions())+ except Exception:+ logger.debug("brief_state: pending_watch_suggestions unavailable", exc_info=True)+ return 0++__all__ = [+ "HANDLED_EVENT_KINDS","REVIEW_EVENT_TYPES","SUPPRESSED_TEMPLATE","build_brief_fingerprint","handled_since","last_delivered",+ "pending_watch_suggestions","record_delivered","scope_for","since_for",diff --git a/packages/core/openexecutive/briefing/narrative.py b/packages/core/openexecutive/briefing/narrative.pyindex b645dcf7..38b87fb5 100644--- a/packages/core/openexecutive/briefing/narrative.py+++ b/packages/core/openexecutive/briefing/narrative.py@@ -139,6 +139,7 @@ def render_briefing_context(activity: list[dict[str, Any]],since: datetime | None = None,handled: list[dict[str, Any]] | None = None,+ pending_watch_suggestions: int = 0,) -> str:"""Pack the structured /today + activity inputs into a single user-turn block.@@ -197,6 +198,14 @@ def render_briefing_context(for h in handled[:15]:parts.append(f"- [{str(h.get('at', ''))[:10]}] {h.get('kind', '')}: {str(h.get('summary', ''))[:140]}")parts.append("")+ if pending_watch_suggestions > 0:+ n = pending_watch_suggestions+ parts.append(+ f"WATCH SUGGESTIONS WAITING: {n} source{'s' if n != 1 else ''} the Executive "+ "would like to monitor but is not sure about — approve or decline on /watchlist "+ "(mention in one line, never list them)"+ )+ parts.append("")people = today_data.get("people", [])awaiting = [p for p in people if p.get("awaiting_count", 0)]@@ -255,6 +264,7 @@ async def synthesize_briefing_narrative(standalone: bool = False,since: datetime | None = None,handled: list[dict[str, Any]] | None = None,+ pending_watch_suggestions: int = 0,) -> str:"""Synthesize the briefing narrative. Returns Markdown, or "" when empty.@@ -283,6 +293,7 @@ async def synthesize_briefing_narrative(user_content = render_briefing_context(period_label=period_label, today_data=today_data, activity=activity,since=since, handled=handled,+ pending_watch_suggestions=pending_watch_suggestions,)model = get_fast_model()response = await get_provider(model).messages_create(diff --git a/packages/core/openexecutive/config.py b/packages/core/openexecutive/config.pyindex 5a826994..db352036 100644--- a/packages/core/openexecutive/config.py+++ b/packages/core/openexecutive/config.py@@ -748,6 +748,22 @@ class Settings(BaseSettings):watchlist_research_max_staleness_hours: int = Field(168, alias="WATCHLIST_RESEARCH_MAX_STALENESS_HOURS")+ # Research watchlist policy (monitoring/research/watch_policy.py). The+ # research pass only PROPOSES watches; deterministic policy adds a watch+ # on its own when it is grounded in company data and corroborated+ # (max_direct_adds per run), and otherwise files it as a dry-run+ # SUGGESTION the principal approves or declines on /watchlist+ # (max_proposals per run). Above max_enabled enabled watches every add+ # becomes a suggestion; a suggestion nobody reviews within+ # proposal_ttl_days is removed (re-proposable after 90 days).+ watchlist_research_max_direct_adds: int = Field(+ 2, alias="WATCHLIST_RESEARCH_MAX_DIRECT_ADDS"+ )+ watchlist_research_max_proposals: int = Field(+ 2, alias="WATCHLIST_RESEARCH_MAX_PROPOSALS"+ )+ watchlist_max_enabled: int = Field(40, alias="WATCHLIST_MAX_ENABLED")+ watchlist_proposal_ttl_days: int = Field(14, alias="WATCHLIST_PROPOSAL_TTL_DAYS")# Notion → isolated wiki-collection sync. OFF by default. When on, a# scheduler heartbeat incrementally re-indexes pages shared with thediff --git a/packages/core/openexecutive/memory/company_profile.py b/packages/core/openexecutive/memory/company_profile.pyindex e639e703..12fbb387 100644--- a/packages/core/openexecutive/memory/company_profile.py+++ b/packages/core/openexecutive/memory/company_profile.py@@ -63,6 +63,11 @@ class CompanyProfile(BaseModel):)culture: Culture = Field(default_factory=Culture)financials: Financials = Field(default_factory=Financials)+ # External entities the company depends on or tracks. Named here so the+ # research watchlist policy can treat a watch on them as grounded in+ # company data (auto-added) rather than inferred (needs approval).+ vendors: list[str] = Field(default_factory=list) # e.g. ["Stripe", "AWS"]+ tickers: list[str] = Field(default_factory=list) # own + competitor tickers@classmethoddef load_from_yaml(cls, path: Path | str) -> CompanyProfile:@@ -181,6 +186,13 @@ class CompanyProfile(BaseModel):+ "; ".join(self.competitive_landscape.competitive_advantages))+ if self.vendors or self.tickers:+ lines.extend(["", "**External Dependencies**:"])+ if self.vendors:+ lines.append(" Vendors: " + ", ".join(self.vendors))+ if self.tickers:+ lines.append(" Tracked tickers: " + ", ".join(self.tickers))+if self.strategic_priorities.current_year:lines.extend(["", "**Strategic Priorities (Current Year)**:"])for p in self.strategic_priorities.current_year:diff --git a/packages/core/openexecutive/monitoring/models.py b/packages/core/openexecutive/monitoring/models.pyindex d0a09e7c..ff4f628f 100644--- a/packages/core/openexecutive/monitoring/models.py+++ b/packages/core/openexecutive/monitoring/models.py@@ -49,6 +49,40 @@ MODE_ACTIVE = "active"MODE_DRY_RUN = "dry_run"_VALID_MODES = frozenset({MODE_ACTIVE, MODE_DRY_RUN})+# Who put a row on the watchlist. ``manual`` = the principal (UI / API);+# ``executive`` = the chat tool acting on a request; ``research`` = the+# research pass auto-added it (grounded in company data); and+# ``research_proposed`` = the research pass was unsure, so the row sits in+# ``dry_run`` as a SUGGESTION until the principal approves or declines it.+ORIGIN_MANUAL = "manual"+ORIGIN_EXECUTIVE = "executive"+ORIGIN_RESEARCH = "research"+ORIGIN_RESEARCH_PROPOSED = "research_proposed"+_VALID_ORIGINS = frozenset({+ ORIGIN_MANUAL, ORIGIN_EXECUTIVE, ORIGIN_RESEARCH, ORIGIN_RESEARCH_PROPOSED,+})+# Rows the research policy owns: subject to auto-disable and to the declines+# memory when removed.+RESEARCH_ORIGINS = frozenset({ORIGIN_RESEARCH, ORIGIN_RESEARCH_PROPOSED})++# Declines memory (``watchlist_declines``). ``declined_explicit`` is+# permanent: the principal said no. ``expired_unreviewed`` means a suggestion+# aged out without anyone looking; it may be re-proposed once after+# DECLINE_EXPIRED_RETRY_DAYS so a timer never blacklists a good source.+DECLINE_KIND_EXPLICIT = "declined_explicit"+DECLINE_KIND_EXPIRED = "expired_unreviewed"+DECLINE_EXPIRED_RETRY_DAYS = 90+# Why the principal declined — each maps to a different remedy in the+# research policy (see monitoring.research.watch_policy).+DECLINE_REASON_NOT_RELEVANT = "not_relevant" # blacklist the entity+DECLINE_REASON_TOO_NOISY = "too_noisy" # keep, but quieter+DECLINE_REASON_WRONG_SOURCE = "wrong_source" # blacklist this target only+DECLINE_REASON_EXPIRED = "expired" # aged out unreviewed+VALID_DECLINE_REASONS = frozenset({+ DECLINE_REASON_NOT_RELEVANT, DECLINE_REASON_TOO_NOISY,+ DECLINE_REASON_WRONG_SOURCE, DECLINE_REASON_EXPIRED,+})+# Watchlist row "cadence" hints — used by the briefing/digest layer in# PR-C to decide whether a signal surfaces real-time vs in a digest.# Kept as opaque strings here; pipeline ignores them in PR-A.@@ -98,12 +132,31 @@ class WatchlistItem(BaseModel):dismiss_count: int = 0trust_score: float = 1.0 # 0..1, decays on dismiss; full trust at creationnotes: str = ""+ origin: str = ORIGIN_MANUAL+++class WatchlistDecline(BaseModel):+ """A target the principal declined (or a suggestion that aged out)."""++ model_config = ConfigDict(extra="forbid")++ normalized_target: str+ entity: str = ""+ signal_type: str = ""+ slug: str = ""+ kind: str = DECLINE_KIND_EXPLICIT+ reason: str = ""+ declined_at: str = ""def is_valid_mode(mode: str) -> bool:return mode in _VALID_MODES+def is_valid_origin(origin: str) -> bool:+ return origin in _VALID_ORIGINS++def is_valid_cadence(cadence: str) -> bool:return cadence in _VALID_CADENCESdiff --git a/packages/core/openexecutive/monitoring/research/scheduler.py b/packages/core/openexecutive/monitoring/research/scheduler.pyindex b1c665a5..ae3baa13 100644--- a/packages/core/openexecutive/monitoring/research/scheduler.py+++ b/packages/core/openexecutive/monitoring/research/scheduler.py@@ -13,7 +13,7 @@ immediately; quiet days are free.That fingerprint only sees *internal* state, so a static profile wouldotherwise let the council sit blind to purely-external change (acompetitor move, a regulation shift) indefinitely. A staleness floor-(``watchlist_research_max_staleness_hours``, default 24) bounds that:+(``watchlist_research_max_staleness_hours``, default 168) bounds that:once the floor has elapsed since the last successful run, the next tickruns even when the fingerprint is unchanged. Set the floor <= 0 todisable it and rely solely on skip-if-unchanged.@@ -76,9 +76,14 @@ def compute_research_state_hash(db_path: Path | None = None) -> str:The inputs are: the company profile's prompt-form text, thetitles + statuses of every active initiative, and the slug+target- list of every enabled watchlist row. A change to any of these+ list of every enabled, ACTIVE watchlist row. A change to any of theseinvalidates the prior research; everything else is irrelevant.+ Dry-run rows are excluded on purpose: the research pass files its own+ suggestions as dry-run rows, and the principal approving or declining+ one must not read as "state changed" and trigger another full+ 7-specialist run within the hour.+Failure on any source is logged + returns a sentinel hash thatdiffers from every real run — so a transient profile-load errortriggers a fresh research rather than silently masking a real@@ -125,12 +130,15 @@ def compute_research_state_hash(db_path: Path | None = None) -> str:try:from openexecutive.monitoring import store as monitoring_store+ from openexecutive.monitoring.models import MODE_ACTIVEparts.append("WATCHLIST:")for item in sorted(- monitoring_store.list_watchlist(db_path=db_path),+ monitoring_store.list_watchlist(enabled_only=True, db_path=db_path),key=lambda x: x.slug,):+ if item.mode != MODE_ACTIVE:+ continueparts.append(f"{item.slug}::{item.signal_type}::{item.target}")except Exception:logger.exception("research.scheduler: watchlist load failed")diff --git a/packages/core/openexecutive/monitoring/research/watch_policy.py b/packages/core/openexecutive/monitoring/research/watch_policy.pynew file mode 100644index 00000000..0f29c01b--- /dev/null+++ b/packages/core/openexecutive/monitoring/research/watch_policy.py@@ -0,0 +1,786 @@+"""Deterministic policy for what the research pass may put on the watchlist.++The research workflow's watchlist pass used to call ``add_watchlist_entry``+directly: whatever the model proposed landed, live, with no rationale, at+``cadence=15min`` / ``severity_floor=low`` and (for feeds) no keyword+trigger — so one unfiltered competitor blog could out-noise the whole+watchlist. The model now only *proposes* (``propose_watch``); this module+decides, and it decides from company data, not from the model's confidence+in itself.++Two tiers:++- **direct** — added live, quietly (daily cadence, medium floor, keyword+ trigger). Requires the grounding entity to be *in company data* (a named+ competitor / vendor / ticker / initiative / priority / the company itself)+ plus enough corroboration (see :func:`classify`). This is the "high+ likelihood, worth watching — just add it" case.+- **suggest** — inserted in ``dry_run`` (polls, never alerts) with+ ``origin=research_proposed``; the principal approves or declines it on+ ``/watchlist``. This is the "not sure" case.++Everything else is rejected, and a target the principal declined is+rejected in the tool handler before the model can route around it with a+new slug. Every decision is audited with its score and reasons.+"""+from __future__ import annotations++import logging+import re+from dataclasses import dataclass, field+from datetime import UTC, datetime, timedelta+from pathlib import Path+from typing import Any++from openexecutive.alerts.models import AlertSeverity+from openexecutive.audit import log_event as audit_log+from openexecutive.monitoring import store as ms+from openexecutive.monitoring.models import (+ DECLINE_KIND_EXPIRED,+ DECLINE_REASON_EXPIRED,+ MODE_ACTIVE,+ MODE_DRY_RUN,+ ORIGIN_RESEARCH,+ ORIGIN_RESEARCH_PROPOSED,+ SOURCE_KIND_EDGAR,+ SOURCE_KIND_PAGE_WATCH,+ SOURCE_KIND_QUERY,+ SOURCE_KIND_RSS,+ SOURCE_KIND_STOCK,+ SOURCE_KIND_VENDOR_STATUS,+ WatchlistItem,+)+from openexecutive.monitoring.research.models import ResearchFinding+from openexecutive.monitoring.validation import normalize_target, registrable_domain++logger = logging.getLogger(__name__)++# Audit event types. The brief's "handled overnight" block renders the first+# two (see briefing.brief_state.HANDLED_EVENT_KINDS).+EVENT_ADDED = "watchlist_research_added"+EVENT_AUTO_DISABLED = "watchlist_auto_disabled"+EVENT_SUGGESTED = "watchlist_research_suggested"+EVENT_REJECTED = "watchlist_research_rejected"+EVENT_SUGGESTION_EXPIRED = "watchlist_suggestion_expired"+EVENT_SUGGESTION_APPROVED = "watchlist_suggestion_approved"+EVENT_SUGGESTION_DECLINED = "watchlist_suggestion_declined"++# Policy outcomes recorded in watchlist_policy_outcomes.+OUTCOME_APPROVED = "approved"+OUTCOME_DECLINED = "declined"+OUTCOME_EXPIRED = "expired"+OUTCOME_AUTO_DISABLED = "auto_disabled"++TIER_DIRECT = "direct"+TIER_SUGGEST = "suggest"+TIER_REJECT = "reject"++# Score needed to add without asking. See classify() for the ledger.+DIRECT_THRESHOLD = 4+# History only moves the score once the policy has a real sample.+_HISTORY_MIN_SAMPLES = 5++# Hosts that are primary sources in their own right: a watch there is+# "the entity's own source" even though the host isn't the entity's domain.+PRIMARY_SOURCE_HOSTS: frozenset[str] = frozenset({+ "sec.gov", "efts.sec.gov", "data.sec.gov",+ "federalregister.gov", "eur-lex.europa.eu",+})++# Grounding-vocabulary kinds, in the order a term is attributed when it+# appears in more than one source.+KIND_COMPANY = "company"+KIND_COMPETITOR = "competitor"+KIND_VENDOR = "vendor"+KIND_TICKER = "ticker"+KIND_INITIATIVE = "initiative"+KIND_PRIORITY = "priority"+KIND_WATCH = "watch" # already watched (label/target) — corroborates, never grounds+GROUNDING_KINDS: frozenset[str] = frozenset({+ KIND_COMPANY, KIND_COMPETITOR, KIND_VENDOR, KIND_TICKER, KIND_INITIATIVE, KIND_PRIORITY,+})++# Material-event words every research feed trigger carries, so a competitor+# blog surfaces "we raised / we launched / pricing" and not every post.+_EVENT_KEYWORDS: tuple[str, ...] = (+ "pricing", "launch", "acqui", "funding", "raises", "layoff", "outage",+ "breach", "partnership", "ceo", "lawsuit", "regulat",+)+_STOPWORDS: frozenset[str] = frozenset({+ "the", "and", "for", "with", "our", "into", "from", "that", "this", "year",+ "grow", "growth", "build", "expand", "increase", "improve", "drive", "launch",+ "new", "more", "across", "team", "company", "inc", "corp", "ltd", "llc",+})+_TOKEN_RE = re.compile(r"[a-z0-9]+")++# Auto-add defaults per source kind: (cadence, severity_floor).+_QUIET_DEFAULTS: dict[str, tuple[str, AlertSeverity]] = {+ SOURCE_KIND_STOCK: ("daily", AlertSeverity.MEDIUM),+ SOURCE_KIND_EDGAR: ("daily", AlertSeverity.MEDIUM),+ SOURCE_KIND_RSS: ("daily", AlertSeverity.MEDIUM),+ SOURCE_KIND_VENDOR_STATUS: ("hourly", AlertSeverity.MEDIUM),+ SOURCE_KIND_PAGE_WATCH: ("weekly", AlertSeverity.MEDIUM),+ SOURCE_KIND_QUERY: ("weekly", AlertSeverity.MEDIUM),+}+_STOCK_DEFAULT_PCT = 5++# Deterministic auto-disable thresholds (research-origin rows only).+_DISABLE_MIN_FIRED = 5+_DISABLE_MIN_DISMISSED = 2+_DISABLE_MAX_TRUST = 0.5+_DEAD_SOURCE_DAYS = 30+_DEAD_SOURCE_KINDS: frozenset[str] = frozenset({+ SOURCE_KIND_RSS, SOURCE_KIND_PAGE_WATCH, SOURCE_KIND_VENDOR_STATUS,+})+_POLL_FAILURES_TO_DISABLE = 3+# Nudge the principal only when suggestions have piled up unreviewed.+_NUDGE_MIN_PENDING = 3+_NUDGE_MIN_AGE_DAYS = 7+NUDGE_ALERT_SOURCE = "watchlist_suggestions"+++# --------------------------------------------------------------------- #+# Inputs+# --------------------------------------------------------------------- #+++@dataclass+class WatchProposal:+ """One validated ``propose_watch`` call, before policy."""++ slug: str+ signal_type: str+ target: str+ normalized_target: str+ rationale: str = ""+ grounding_entity: str = ""+ finding_index: int | None = None+ certainty: str = "unsure"+ config: dict[str, Any] = field(default_factory=dict)+ trigger: dict[str, Any] = field(default_factory=dict)+ route_to_specialist: str = ""+ display_label: str = ""+++@dataclass+class PolicySettings:+ max_direct_adds: int = 2+ max_suggestions: int = 2+ max_enabled: int = 40+ suggestion_ttl_days: int = 14++ @classmethod+ def load(cls) -> PolicySettings:+ try:+ from openexecutive.config import get_settings++ s = get_settings()+ return cls(+ max_direct_adds=int(s.watchlist_research_max_direct_adds),+ max_suggestions=int(s.watchlist_research_max_proposals),+ max_enabled=int(s.watchlist_max_enabled),+ suggestion_ttl_days=int(s.watchlist_proposal_ttl_days),+ )+ except Exception:+ logger.debug("watch_policy: settings unavailable — using defaults", exc_info=True)+ return cls()+++@dataclass+class PolicyContext:+ """Everything classify() needs, gathered once per run."""++ vocabulary: dict[str, str] # normalized term -> kind+ priority_terms: list[str]+ existing: list[WatchlistItem]+ outcome_counts: dict[tuple[str, str], dict[str, int]] = field(default_factory=dict)+ settings: PolicySettings = field(default_factory=PolicySettings)+ now: datetime = field(default_factory=lambda: datetime.now(UTC))+++@dataclass+class Decision:+ tier: str+ score: int+ entity: str+ grounding_kind: str+ reasons: list[str]+++# --------------------------------------------------------------------- #+# Grounding vocabulary+# --------------------------------------------------------------------- #+++def _norm(term: str) -> str:+ return " ".join(_TOKEN_RE.findall((term or "").lower()))+++def grounding_vocabulary(+ profile: Any,+ initiatives: list[Any],+ existing: list[WatchlistItem],+) -> dict[str, str]:+ """Normalized term → kind. Company-data kinds win over ``watch`` when a+ term appears in both (a competitor that is already watched still grounds+ a new watch on a *different* source of theirs)."""+ vocab: dict[str, str] = {}++ def add(term: str, kind: str) -> None:+ n = _norm(term)+ if len(n) < 2:+ return+ if n not in vocab or (vocab[n] == KIND_WATCH and kind != KIND_WATCH):+ vocab[n] = kind++ for item in existing:+ for label_key in ("display_name", "feed_label", "vendor_label", "label"):+ label = item.config_json.get(label_key) if isinstance(item.config_json, dict) else None+ if label:+ add(str(label), KIND_WATCH)+ add(item.target, KIND_WATCH)+ add(item.slug.replace("-", " "), KIND_WATCH)+ for i in initiatives:+ add(str(getattr(i, "title", "") or ""), KIND_INITIATIVE)+ if profile is not None:+ for p in list(getattr(getattr(profile, "strategic_priorities", None), "current_year", []) or []):+ add(str(p), KIND_PRIORITY)+ for t in list(getattr(profile, "tickers", []) or []):+ add(str(t), KIND_TICKER)+ for v in list(getattr(profile, "vendors", []) or []):+ add(str(v), KIND_VENDOR)+ for c in list(getattr(getattr(profile, "competitive_landscape", None), "primary_competitors", []) or []):+ add(str(c), KIND_COMPETITOR)+ add(str(getattr(profile, "name", "") or ""), KIND_COMPANY)+ return vocab+++def priority_terms(profile: Any) -> list[str]:+ """Distinctive words from the current-year priorities (feed triggers)."""+ out: list[str] = []+ for p in list(getattr(getattr(profile, "strategic_priorities", None), "current_year", []) or []):+ for tok in _TOKEN_RE.findall(str(p).lower()):+ if len(tok) >= 5 and tok not in _STOPWORDS and tok not in out:+ out.append(tok)+ return out[:6]+++def match_entity(entity: str, vocabulary: dict[str, str]) -> tuple[str, str] | None:+ """``(term, kind)`` for the vocabulary term the entity names, else None.++ Token containment both ways, so "Acme Corp" matches "Acme" and "Acme"+ matches "Acme Corp"; single-token matches must be a whole token."""+ n = _norm(entity)+ if len(n) < 2:+ return None+ exact = vocabulary.get(n)+ if exact is not None and exact != KIND_WATCH:+ return n, exact+ tokens = set(n.split())+ # An exact hit on a watch label is only the fallback: a company-data term+ # that contains (or is contained by) the entity still wins.+ best: tuple[str, str] | None = (n, exact) if exact is not None else None+ for term, kind in vocabulary.items():+ term_tokens = set(term.split())+ if not term_tokens or not (term_tokens <= tokens or tokens <= term_tokens):+ continue+ # Prefer a company-data kind over a watch label, then the longer term.+ if best is None or (best[1] == KIND_WATCH and kind != KIND_WATCH) or (+ best[1] == kind and len(term) > len(best[0])+ ):+ best = (term, kind)+ return best+++# --------------------------------------------------------------------- #+# Classification+# --------------------------------------------------------------------- #+++def _is_own_source(proposal: WatchProposal, entity_term: str, vocabulary: dict[str, str]) -> bool:+ """The target is the entity's own primary source: its ticker for+ stock/edgar, its own domain for a URL, or an allowlisted primary host."""+ if proposal.signal_type in (SOURCE_KIND_STOCK, SOURCE_KIND_EDGAR):+ return vocabulary.get(_norm(proposal.target)) in (KIND_TICKER, KIND_WATCH) or (+ _norm(proposal.target) == entity_term+ )+ host = registrable_domain(proposal.target)+ if not host:+ return False+ if host in PRIMARY_SOURCE_HOSTS or any(host.endswith("." + h) for h in PRIMARY_SOURCE_HOSTS):+ return True+ host_tokens = set(_TOKEN_RE.findall(host.replace(".", " ")))+ entity_tokens = {t for t in entity_term.split() if len(t) >= 3}+ return bool(entity_tokens & host_tokens)+++def _history_adjustment(+ signal_type: str, grounding_kind: str, counts: dict[tuple[str, str], dict[str, int]],+) -> tuple[int, str]:+ tally = counts.get((signal_type, grounding_kind)) or {}+ good = tally.get(OUTCOME_APPROVED, 0)+ bad = tally.get(OUTCOME_DECLINED, 0) + tally.get(OUTCOME_AUTO_DISABLED, 0)+ n = good + bad+ if n < _HISTORY_MIN_SAMPLES:+ return 0, ""+ rate = good / n+ if rate >= 0.7:+ return 1, f"history {good}/{n} approved"+ if rate <= 0.3:+ return -1, f"history {good}/{n} approved"+ return 0, ""+++def _same_source_already_watched(proposal: WatchProposal, existing: list[WatchlistItem]) -> bool:+ host = registrable_domain(proposal.target)+ for item in existing:+ if not item.enabled:+ continue+ if normalize_target(item.signal_type, item.target) == proposal.normalized_target:+ return True+ if host and item.signal_type == proposal.signal_type and registrable_domain(item.target) == host:+ return True+ return False+++def classify(+ proposal: WatchProposal, finding: ResearchFinding | None, ctx: PolicyContext,+) -> Decision:+ """Score a proposal. The ledger:++ +2 grounding entity names something in company data (mandatory for direct)+ +1 entity is already watched under another source (corroboration)+ +1 target is the entity's own source (its ticker / its domain / a primary host)+ +1 finding confidence is high+ +1 finding verification is 'confirmed'+ +1 cross-specialist consensus on the finding+ ±1 policy history for (signal_type, grounding kind) at >=5 samples++ Direct at >= DIRECT_THRESHOLD with the mandatory entity match; the model's+ own ``certainty`` can only downgrade. ``query`` is never direct.+ """+ reasons: list[str] = []+ score = 0+ match = match_entity(proposal.grounding_entity, ctx.vocabulary)+ entity_term, kind = (match if match else ("", ""))+ grounded = kind in GROUNDING_KINDS+ if grounded:+ score += 2+ reasons.append(f"entity '{proposal.grounding_entity}' is a company {kind}")+ elif kind == KIND_WATCH:+ score += 1+ reasons.append(f"entity '{proposal.grounding_entity}' matches an existing watch")+ else:+ reasons.append(f"entity '{proposal.grounding_entity}' is not in company data")++ if entity_term and _is_own_source(proposal, entity_term, ctx.vocabulary):+ score += 1+ reasons.append("target is the entity's own source")+ if finding is not None:+ if finding.confidence == "high":+ score += 1+ reasons.append("finding confidence high")+ if finding.verification == "confirmed":+ score += 1+ reasons.append("source verified")+ if "," in (finding.source_specialist or ""):+ score += 1+ reasons.append("cross-specialist consensus")+ adj, why = _history_adjustment(proposal.signal_type, kind, ctx.outcome_counts)+ if adj:+ score += adj+ reasons.append(why)++ if _same_source_already_watched(proposal, ctx.existing):+ reasons.append("same source already watched")+ return Decision(TIER_REJECT, score, entity_term, kind, reasons)++ tier = TIER_SUGGEST+ if grounded and score >= DIRECT_THRESHOLD:+ tier = TIER_DIRECT+ if tier == TIER_DIRECT and proposal.signal_type == SOURCE_KIND_QUERY:+ tier = TIER_SUGGEST+ reasons.append("standing web queries are always suggestions")+ if tier == TIER_DIRECT and proposal.certainty != "confident":+ tier = TIER_SUGGEST+ reasons.append("model marked it unsure")+ enabled_count = sum(1 for i in ctx.existing if i.enabled)+ if tier == TIER_DIRECT and enabled_count >= ctx.settings.max_enabled:+ tier = TIER_SUGGEST+ reasons.append(f"watchlist at its ceiling ({enabled_count})")+ return Decision(tier, score, entity_term, kind, reasons)+++# --------------------------------------------------------------------- #+# Quiet defaults+# --------------------------------------------------------------------- #+++def quiet_defaults(+ proposal: WatchProposal, entity_term: str, priority_words: list[str],+) -> tuple[str, AlertSeverity, dict[str, Any]]:+ """``(cadence, severity_floor, trigger)`` a research row lands with.++ The model's cadence/floor are ignored: a research watch must be quiet+ by construction and the principal can loosen it on /watchlist."""+ cadence, floor = _QUIET_DEFAULTS.get(proposal.signal_type, ("daily", AlertSeverity.MEDIUM))+ trigger: dict[str, Any] = dict(proposal.trigger or {})+ if proposal.signal_type == SOURCE_KIND_STOCK:+ if not isinstance(trigger.get("abs_change_pct_gte"), (int, float)):+ trigger["abs_change_pct_gte"] = _STOCK_DEFAULT_PCT+ elif proposal.signal_type in (SOURCE_KIND_RSS, SOURCE_KIND_PAGE_WATCH, SOURCE_KIND_QUERY):+ existing_kw = trigger.get("keywords")+ keywords: list[str] = [str(k) for k in existing_kw] if isinstance(existing_kw, list) else []+ for tok in entity_term.split():+ if len(tok) >= 3 and tok not in keywords:+ keywords.append(tok)+ for kw in list(_EVENT_KEYWORDS) + priority_words:+ if kw not in keywords:+ keywords.append(kw)+ trigger["keywords"] = keywords[:20]+ return cadence, floor, trigger+++# --------------------------------------------------------------------- #+# Apply+# --------------------------------------------------------------------- #+++def _policy_stamp(decision: Decision, proposal: WatchProposal, finding: ResearchFinding | None) -> dict[str, Any]:+ return {+ "entity": decision.entity,+ "grounding_kind": decision.grounding_kind,+ "specialist": (finding.source_specialist if finding else ""),+ "score": decision.score,+ "reasons": decision.reasons[:6],+ "source_url": (finding.relevant_urls[0] if finding and finding.relevant_urls else ""),+ }+++def policy_stamp_of(item: WatchlistItem) -> dict[str, Any]:+ stamp = item.config_json.get("_policy") if isinstance(item.config_json, dict) else None+ return dict(stamp) if isinstance(stamp, dict) else {}+++def apply_proposals(+ proposals: list[WatchProposal],+ findings: list[ResearchFinding],+ ctx: PolicyContext,+ *,+ db_path: Path | None = None,+) -> list[dict[str, Any]]:+ """Classify and persist. Returns tool-call-shaped summaries+ (``tool='propose_watch'``, plus ``outcome`` = added | suggested | rejected)+ so the run's artifact and audit accounting stay uniform."""+ summaries: list[dict[str, Any]] = []+ direct_left = max(0, ctx.settings.max_direct_adds)+ suggest_left = max(0, ctx.settings.max_suggestions)+ seen_targets: set[str] = set()+ live_existing = list(ctx.existing)++ for proposal in proposals:+ finding = (+ findings[proposal.finding_index]+ if proposal.finding_index is not None and 0 <= proposal.finding_index < len(findings)+ else None+ )+ if proposal.normalized_target in seen_targets:+ summaries.append(_summary(proposal, "rejected", "duplicate target in this run"))+ continue+ seen_targets.add(proposal.normalized_target)++ ctx.existing = live_existing+ decision = classify(proposal, finding, ctx)+ if decision.tier == TIER_DIRECT and direct_left <= 0:+ decision.tier = TIER_SUGGEST+ decision.reasons.append("direct-add budget spent this run")+ if decision.tier == TIER_SUGGEST and suggest_left <= 0:+ decision.tier = TIER_REJECT+ decision.reasons.append("suggestion budget spent this run")++ if decision.tier == TIER_REJECT:+ audit_log(+ EVENT_REJECTED,+ f"Research watch rejected: {proposal.slug} — {'; '.join(decision.reasons[-2:])}",+ actor="executive",+ details={"slug": proposal.slug, "target": proposal.target,+ "signal_type": proposal.signal_type, **_policy_stamp(decision, proposal, finding)},+ )+ summaries.append(_summary(proposal, "rejected", decision.reasons[-1] if decision.reasons else ""))+ continue++ cadence, floor, trigger = quiet_defaults(proposal, decision.entity, ctx.priority_terms)+ config = dict(proposal.config)+ config["_policy"] = _policy_stamp(decision, proposal, finding)+ is_direct = decision.tier == TIER_DIRECT+ try:+ new_id = ms.insert_watchlist_item(+ slug=proposal.slug,+ signal_type=proposal.signal_type,+ target=proposal.target,+ config=config,+ trigger=trigger,+ cadence=cadence,+ severity_floor=floor,+ severity_ceiling=AlertSeverity.URGENT,+ route_to_specialist=proposal.route_to_specialist,+ mode=MODE_ACTIVE if is_direct else MODE_DRY_RUN,+ notes=proposal.rationale[:500],+ origin=ORIGIN_RESEARCH if is_direct else ORIGIN_RESEARCH_PROPOSED,+ db_path=db_path,+ )+ except Exception as exc:+ logger.exception("watch_policy: insert failed for %s", proposal.slug)+ summaries.append(_summary(proposal, "rejected", f"insert failed: {exc}"[:120]))+ continue++ inserted = ms.get_watchlist_item(new_id, db_path=db_path)+ if inserted is not None:+ live_existing.append(inserted)+ details = {+ "watchlist_id": new_id, "slug": proposal.slug, "target": proposal.target,+ "signal_type": proposal.signal_type, "rationale": proposal.rationale[:240],+ "cadence": cadence, "severity_floor": floor.value, "trigger": trigger,+ **_policy_stamp(decision, proposal, finding),+ }+ if is_direct:+ direct_left -= 1+ audit_log(+ EVENT_ADDED,+ f"Started watching {proposal.slug} — {proposal.rationale[:120] or decision.entity}",+ actor="executive", details=details,+ )+ summaries.append(_summary(+ proposal, "added",+ f"added (score {decision.score}; {decision.reasons[0] if decision.reasons else ''})",+ ))+ else:+ suggest_left -= 1+ audit_log(+ EVENT_SUGGESTED,+ f"Suggested watching {proposal.slug} — {'; '.join(decision.reasons[-2:])}",+ actor="executive", details=details,+ )+ summaries.append(_summary(+ proposal, "suggested",+ f"suggested for approval (score {decision.score}; {decision.reasons[-1] if decision.reasons else ''})",+ ))+ return summaries+++def _summary(proposal: WatchProposal, outcome: str, detail: str) -> dict[str, Any]:+ return {+ "tool": "propose_watch",+ "input_preview": f"{proposal.slug} [{proposal.signal_type}] {proposal.target}"[:120],+ "result_preview": f"{proposal.slug}: {detail}"[:160],+ "ok": outcome != "rejected",+ "outcome": outcome,+ "slug": proposal.slug,+ }+++# --------------------------------------------------------------------- #+# Approve / decline (called by the API routes)+# --------------------------------------------------------------------- #+++def record_outcome_for(item: WatchlistItem, outcome: str, *, db_path: Path | None = None) -> None:+ stamp = policy_stamp_of(item)+ try:+ ms.record_policy_outcome(+ signal_type=item.signal_type,+ grounding_kind=str(stamp.get("grounding_kind", "")),+ specialist=str(stamp.get("specialist", "")),+ outcome=outcome,+ db_path=db_path,+ )+ except Exception:+ logger.debug("watch_policy: outcome record failed", exc_info=True)+++# --------------------------------------------------------------------- #+# Sweep (scheduler, every 15 min alongside the alert expiry sweep)+# --------------------------------------------------------------------- #+++def _parse(ts: str | None) -> datetime | None:+ if not ts:+ return None+ try:+ dt = datetime.fromisoformat(ts)+ except ValueError:+ return None+ return dt if dt.tzinfo else dt.replace(tzinfo=UTC)+++def _consecutive_poll_failures(slug: str) -> int:+ """How many of the most recent polls of ``slug`` failed, counting back+ from the newest until one succeeded."""+ try:+ from openexecutive.audit.logger import get_audit_logger++ rows = get_audit_logger().query(+ event_type="external_monitor_poll", q=f"Polled {slug} (", limit=_POLL_FAILURES_TO_DISABLE,+ )+ except Exception:+ return 0+ n = 0+ for ev in rows:+ details = ev.details if isinstance(ev.details, dict) else {}+ if details.get("watchlist_slug") not in (None, slug):+ continue+ if not details.get("failed"):+ break+ n += 1+ return n+++def _auto_disable_reason(item: WatchlistItem, now: datetime, db_path: Path | None) -> str:+ if (+ item.fired_count >= _DISABLE_MIN_FIRED+ and item.dismiss_count >= _DISABLE_MIN_DISMISSED+ and item.trust_score <= _DISABLE_MAX_TRUST+ ):+ return f"dismissed {item.dismiss_count} of {item.fired_count} alerts (trust {item.trust_score:.2f})"+ created = _parse(item.created_at)+ if (+ item.signal_type in _DEAD_SOURCE_KINDS+ and created is not None+ and now - created >= timedelta(days=_DEAD_SOURCE_DAYS)+ and item.id is not None+ and ms.count_signals_since(item.id, now - timedelta(days=_DEAD_SOURCE_DAYS), db_path=db_path) == 0+ ):+ return f"no signals in {_DEAD_SOURCE_DAYS} days"+ if _consecutive_poll_failures(item.slug) >= _POLL_FAILURES_TO_DISABLE:+ return f"{_POLL_FAILURES_TO_DISABLE} consecutive poll failures"+ return ""+++def sweep(now: datetime | None = None, *, db_path: Path | None = None) -> dict[str, int]:+ """Expire stale suggestions, auto-disable research watches that proved+ noisy or dead, and nudge the principal when suggestions pile up. Never+ raises. Returns counts for logging."""+ now = now or datetime.now(UTC)+ counts = {"expired": 0, "disabled": 0, "nudged": 0}+ settings = PolicySettings.load()+ try:+ counts["expired"] = _expire_suggestions(now, settings, db_path)+ except Exception:+ logger.exception("watch_policy.sweep: expire failed")+ try:+ counts["disabled"] = _auto_disable(now, db_path)+ except Exception:+ logger.exception("watch_policy.sweep: auto-disable failed")+ try:+ counts["nudged"] = _nudge_if_piled_up(now, db_path)+ except Exception:+ logger.exception("watch_policy.sweep: nudge failed")+ return counts+++def _expire_suggestions(now: datetime, settings: PolicySettings, db_path: Path | None) -> int:+ ttl = timedelta(days=max(1, settings.suggestion_ttl_days))+ n = 0+ for item in ms.list_pending_suggestions(db_path=db_path):+ created = _parse(item.created_at)+ if created is None or now - created < ttl or item.id is None:+ continue+ ms.insert_decline(+ normalized_target=normalize_target(item.signal_type, item.target),+ kind=DECLINE_KIND_EXPIRED, reason=DECLINE_REASON_EXPIRED,+ entity=str(policy_stamp_of(item).get("entity", "")),+ signal_type=item.signal_type, slug=item.slug, db_path=db_path,+ )+ record_outcome_for(item, OUTCOME_EXPIRED, db_path=db_path)+ ms.delete_watchlist_item(item.id, db_path=db_path)+ audit_log(+ EVENT_SUGGESTION_EXPIRED,+ f"Watch suggestion {item.slug} expired unreviewed after {settings.suggestion_ttl_days}d",+ actor="scheduler",+ details={"slug": item.slug, "target": item.target, "signal_type": item.signal_type},+ )+ n += 1+ return n+++def _auto_disable(now: datetime, db_path: Path | None) -> int:+ n = 0+ for item in ms.list_watchlist(enabled_only=True, db_path=db_path):+ if item.origin != ORIGIN_RESEARCH or item.mode != MODE_ACTIVE or item.id is None:+ continue+ reason = _auto_disable_reason(item, now, db_path)+ if not reason:+ continue+ ms.set_enabled(item.id, False, db_path=db_path)+ record_outcome_for(item, OUTCOME_AUTO_DISABLED, db_path=db_path)+ audit_log(+ EVENT_AUTO_DISABLED,+ f"Stopped watching {item.slug} — {reason}",+ actor="scheduler",+ details={"watchlist_id": item.id, "slug": item.slug, "target": item.target,+ "signal_type": item.signal_type, "reason": reason},+ )+ n += 1+ return n+++def _nudge_if_piled_up(now: datetime, db_path: Path | None) -> int:+ pending = ms.list_pending_suggestions(db_path=db_path)+ if len(pending) < _NUDGE_MIN_PENDING:+ return 0+ oldest = pending[0]+ created = _parse(oldest.created_at)+ if created is None or now - created < timedelta(days=_NUDGE_MIN_AGE_DAYS):+ return 0+ from openexecutive.alerts.store import insert_alert++ key = f"{NUDGE_ALERT_SOURCE}:{oldest.slug}"+ lines = [f"- {i.slug} ({i.signal_type}) — {i.notes or i.target}"[:200] for i in pending[:10]]+ alert_id = insert_alert(+ source=NUDGE_ALERT_SOURCE,+ external_id=key,+ severity="medium",+ headline=f"{len(pending)} watch suggestions are waiting for you",+ body=(+ "The Executive suggested these sources to monitor and is not sure "+ "enough to add them on its own. Approve or decline them on the "+ "Watch list page.\n\n" + "\n".join(lines)+ ),+ suggested_action="Review the suggestions on /watchlist",+ topic_tags=["watchlist"],+ dedup_key=key,+ db_path=db_path,+ )+ return 1 if alert_id else 0+++__all__ = [+ "DIRECT_THRESHOLD",+ "EVENT_ADDED",+ "EVENT_AUTO_DISABLED",+ "EVENT_REJECTED",+ "EVENT_SUGGESTED",+ "EVENT_SUGGESTION_APPROVED",+ "EVENT_SUGGESTION_DECLINED",+ "EVENT_SUGGESTION_EXPIRED",+ "OUTCOME_APPROVED",+ "OUTCOME_AUTO_DISABLED",+ "OUTCOME_DECLINED",+ "OUTCOME_EXPIRED",+ "TIER_DIRECT",+ "TIER_REJECT",+ "TIER_SUGGEST",+ "Decision",+ "PolicyContext",+ "PolicySettings",+ "WatchProposal",+ "apply_proposals",+ "classify",+ "grounding_vocabulary",+ "match_entity",+ "policy_stamp_of",+ "priority_terms",+ "quiet_defaults",+ "record_outcome_for",+ "sweep",+]diff --git a/packages/core/openexecutive/monitoring/store.py b/packages/core/openexecutive/monitoring/store.pyindex f67808b3..9ff15ded 100644--- a/packages/core/openexecutive/monitoring/store.py+++ b/packages/core/openexecutive/monitoring/store.py@@ -25,18 +25,26 @@ import loggingimport sqlite3from collections.abc import Generatorfrom contextlib import contextmanager-from datetime import UTC, datetime+from datetime import UTC, datetime, timedeltafrom pathlib import Pathfrom typing import Anyfrom openexecutive.alerts.models import AlertSeverityfrom openexecutive.memory.episodic import DB_PATH, _resolve_db_pathfrom openexecutive.monitoring.models import (+ DECLINE_EXPIRED_RETRY_DAYS,+ DECLINE_KIND_EXPIRED,MODE_ACTIVE,+ MODE_DRY_RUN,+ ORIGIN_MANUAL,+ ORIGIN_RESEARCH,+ ORIGIN_RESEARCH_PROPOSED,OUTCOME_SUPPRESSED_BASELINE,Signal,+ WatchlistDecline,WatchlistItem,is_valid_mode,+ is_valid_origin,is_valid_outcome,)@@ -133,6 +141,31 @@ def initialize_db(db_path: Path | None = None) -> None:name TEXT PRIMARY KEY,applied_at TEXT NOT NULL);++ -- Targets the principal declined (or research suggestions that+ -- aged out). Keyed by the normalized target so a re-proposal+ -- under a new slug still hits. Read by the research watch policy.+ CREATE TABLE IF NOT EXISTS watchlist_declines (+ normalized_target TEXT PRIMARY KEY,+ entity TEXT NOT NULL DEFAULT '',+ signal_type TEXT NOT NULL DEFAULT '',+ slug TEXT NOT NULL DEFAULT '',+ kind TEXT NOT NULL,+ reason TEXT NOT NULL DEFAULT '',+ declined_at TEXT NOT NULL+ );++ -- How the research watch policy's guesses turned out+ -- (approved / declined / auto_disabled), keyed by the shape of+ -- the guess so the policy can calibrate itself over time.+ CREATE TABLE IF NOT EXISTS watchlist_policy_outcomes (+ id INTEGER PRIMARY KEY AUTOINCREMENT,+ signal_type TEXT NOT NULL,+ grounding_kind TEXT NOT NULL DEFAULT '',+ specialist TEXT NOT NULL DEFAULT '',+ outcome TEXT NOT NULL,+ at TEXT NOT NULL+ );""")# Additive migration for DBs created before enrichment landed.# ``CREATE TABLE IF NOT EXISTS`` above is a no-op on an existing@@ -161,6 +194,10 @@ def initialize_db(db_path: Path | None = None) -> None:_migrate_baselined_at(conn)# Add future migrations BELOW, not inside the guard above._migrate_vendor_status_rekey(conn)+ # Provenance of a watch (manual / executive / research /+ # research_proposed). Pre-existing rows are 'manual': nothing the+ # research policy owns predates the column.+ _ensure_column(conn, "watchlist", "origin", "TEXT NOT NULL DEFAULT 'manual'")def _migrate_baselined_at(conn: sqlite3.Connection) -> None:@@ -302,15 +339,18 @@ def insert_watchlist_item(mode: str = MODE_ACTIVE,enabled: bool = True,notes: str = "",+ origin: str = ORIGIN_MANUAL,db_path: Path | None = None,) -> int:"""Insert a new watchlist row. Returns its id.- Raises ``ValueError`` for unknown ``mode`` so callers fail loudly- rather than silently storing a value the pipeline can't interpret.+ Raises ``ValueError`` for unknown ``mode`` / ``origin`` so callers fail+ loudly rather than silently storing a value the pipeline can't interpret."""if not is_valid_mode(mode):raise ValueError(f"Unknown watchlist mode {mode!r}")+ if not is_valid_origin(origin):+ raise ValueError(f"Unknown watchlist origin {origin!r}")now = datetime.now(UTC).isoformat()with _get_conn(db_path) as conn:cursor = conn.execute(@@ -318,8 +358,8 @@ def insert_watchlist_item("(slug, signal_type, target, config_json, trigger_json, cadence, ""severity_floor, severity_ceiling, route_to_specialist, ""route_to_department, route_to_person_id, mode, enabled, "- "created_at, notes) "- "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",+ "created_at, notes, origin) "+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",(slug,signal_type,@@ -338,6 +378,7 @@ def insert_watchlist_item(1 if enabled else 0,now,notes,+ origin,),)return int(cursor.lastrowid or 0)@@ -466,6 +507,7 @@ _ALLOWED_UPDATE_COLUMNS: frozenset[str] = frozenset({"notes","config_json","route_to_specialist",+ "origin",})@@ -502,14 +544,19 @@ def update_watchlist_fields(def delete_watchlist_item(item_id: int, db_path: Path | None = None) -> bool:- """Hard-delete a watchlist row. Returns True iff a row was removed.-- External_signals rows for this watchlist_id are NOT cascade-deleted —- the audit trail of past signals stays intact so historical alerts can- still be traced. Callers who want to suppress future surfacing should- prefer ``set_enabled(item_id, False)``.+ """Hard-delete a watchlist row and its ``external_signals`` history.+ Returns True iff a row was removed.++ The FK from external_signals is enforced (PRAGMA foreign_keys=ON), so a+ watch that has ever recorded a signal cannot be deleted on its own; the+ signals go with it, in the same transaction. Alerts already promoted+ from those signals are untouched (they live in ``alerts``), and the+ audit_log keeps the ``external_signal_*`` rows, so what the watch+ surfaced stays traceable. Callers who want to suppress future surfacing+ without losing the row should prefer ``set_enabled(item_id, False)``."""with _get_conn(db_path) as conn:+ conn.execute("DELETE FROM external_signals WHERE watchlist_id = ?", (item_id,))cursor = conn.execute("DELETE FROM watchlist WHERE id = ?", (item_id,))return cursor.rowcount > 0@@ -527,6 +574,191 @@ def set_enabled(return cursor.rowcount > 0+# --------------------------------------------------------------------- #+# Research suggestions, declines memory, policy outcomes+# --------------------------------------------------------------------- #+++def list_pending_suggestions(db_path: Path | None = None) -> list[WatchlistItem]:+ """Research suggestions awaiting the principal: ``research_proposed``+ rows still in ``dry_run``. Oldest first."""+ resolved = _resolve_db_path(db_path)+ if not resolved.exists():+ return []+ with _get_conn(db_path) as conn:+ rows = conn.execute(+ "SELECT * FROM watchlist WHERE origin = ? AND mode = ? ORDER BY id",+ (ORIGIN_RESEARCH_PROPOSED, MODE_DRY_RUN),+ ).fetchall()+ return [_row_to_watchlist(row) for row in rows]+++def approve_suggestion(item_id: int, db_path: Path | None = None) -> bool:+ """Flip a pending suggestion to a live research watch. Returns False when+ the row is not a pending suggestion (already approved, or not research)."""+ with _get_conn(db_path) as conn:+ cursor = conn.execute(+ "UPDATE watchlist SET mode = ?, origin = ?, enabled = 1 "+ "WHERE id = ? AND origin = ? AND mode = ?",+ (MODE_ACTIVE, ORIGIN_RESEARCH, item_id, ORIGIN_RESEARCH_PROPOSED, MODE_DRY_RUN),+ )+ return cursor.rowcount > 0+++def _row_to_decline(row: sqlite3.Row) -> WatchlistDecline:+ return WatchlistDecline(**dict(row))+++def insert_decline(+ *,+ normalized_target: str,+ kind: str,+ reason: str = "",+ entity: str = "",+ signal_type: str = "",+ slug: str = "",+ db_path: Path | None = None,+) -> None:+ """Record (or refresh) a decline for ``normalized_target``. An explicit+ decline always overwrites an expired one; an expiry never downgrades an+ explicit decline."""+ now = datetime.now(UTC).isoformat()+ with _get_conn(db_path) as conn:+ existing = conn.execute(+ "SELECT kind FROM watchlist_declines WHERE normalized_target = ?",+ (normalized_target,),+ ).fetchone()+ if existing is not None and existing["kind"] != DECLINE_KIND_EXPIRED and kind == DECLINE_KIND_EXPIRED:+ return+ conn.execute(+ "INSERT INTO watchlist_declines "+ "(normalized_target, entity, signal_type, slug, kind, reason, declined_at) "+ "VALUES (?, ?, ?, ?, ?, ?, ?) "+ "ON CONFLICT(normalized_target) DO UPDATE SET "+ "entity = excluded.entity, signal_type = excluded.signal_type, "+ "slug = excluded.slug, kind = excluded.kind, reason = excluded.reason, "+ "declined_at = excluded.declined_at",+ (normalized_target, entity[:200], signal_type, slug, kind, reason, now),+ )+++def list_declines(db_path: Path | None = None) -> list[WatchlistDecline]:+ resolved = _resolve_db_path(db_path)+ if not resolved.exists():+ return []+ with _get_conn(db_path) as conn:+ rows = conn.execute(+ "SELECT * FROM watchlist_declines ORDER BY declined_at DESC"+ ).fetchall()+ return [_row_to_decline(row) for row in rows]+++def delete_decline(normalized_target: str, db_path: Path | None = None) -> bool:+ with _get_conn(db_path) as conn:+ cursor = conn.execute(+ "DELETE FROM watchlist_declines WHERE normalized_target = ?",+ (normalized_target,),+ )+ return cursor.rowcount > 0+++def is_declined(+ normalized_target: str,+ *,+ now: datetime | None = None,+ db_path: Path | None = None,+) -> bool:+ """True when the target must not be proposed again: an explicit decline+ (permanent), or an unreviewed expiry younger than the retry window."""+ resolved = _resolve_db_path(db_path)+ if not resolved.exists():+ return False+ with _get_conn(db_path) as conn:+ row = conn.execute(+ "SELECT kind, declined_at FROM watchlist_declines WHERE normalized_target = ?",+ (normalized_target,),+ ).fetchone()+ if row is None:+ return False+ if row["kind"] != DECLINE_KIND_EXPIRED:+ return True+ try:+ declined_at = datetime.fromisoformat(row["declined_at"])+ except ValueError:+ return True+ if declined_at.tzinfo is None:+ declined_at = declined_at.replace(tzinfo=UTC)+ return (now or datetime.now(UTC)) - declined_at < timedelta(days=DECLINE_EXPIRED_RETRY_DAYS)+++def record_policy_outcome(+ *,+ signal_type: str,+ grounding_kind: str,+ specialist: str,+ outcome: str,+ db_path: Path | None = None,+) -> None:+ with _get_conn(db_path) as conn:+ conn.execute(+ "INSERT INTO watchlist_policy_outcomes "+ "(signal_type, grounding_kind, specialist, outcome, at) VALUES (?, ?, ?, ?, ?)",+ (signal_type, grounding_kind, specialist[:64], outcome, datetime.now(UTC).isoformat()),+ )+++def policy_outcome_counts(+ db_path: Path | None = None,+) -> dict[tuple[str, str], dict[str, int]]:+ """``{(signal_type, grounding_kind): {outcome: n}}`` — the policy's+ track record by the shape of the guess. Empty on a fresh install."""+ resolved = _resolve_db_path(db_path)+ if not resolved.exists():+ return {}+ out: dict[tuple[str, str], dict[str, int]] = {}+ with _get_conn(db_path) as conn:+ rows = conn.execute(+ "SELECT signal_type, grounding_kind, outcome, COUNT(*) AS n "+ "FROM watchlist_policy_outcomes GROUP BY signal_type, grounding_kind, outcome"+ ).fetchall()+ for row in rows:+ key = (str(row["signal_type"]), str(row["grounding_kind"]))+ out.setdefault(key, {})[str(row["outcome"])] = int(row["n"])+ return out+++def specialist_outcome_counts(db_path: Path | None = None) -> dict[str, dict[str, int]]:+ """``{specialist: {outcome: n}}`` for the research turn's calibration line."""+ resolved = _resolve_db_path(db_path)+ if not resolved.exists():+ return {}+ out: dict[str, dict[str, int]] = {}+ with _get_conn(db_path) as conn:+ rows = conn.execute(+ "SELECT specialist, outcome, COUNT(*) AS n FROM watchlist_policy_outcomes "+ "WHERE specialist != '' GROUP BY specialist, outcome"+ ).fetchall()+ for row in rows:+ out.setdefault(str(row["specialist"]), {})[str(row["outcome"])] = int(row["n"])+ return out+++def count_signals_since(+ watchlist_id: int, since: datetime, db_path: Path | None = None,+) -> int:+ """Signals (any outcome) captured for a watch since ``since``."""+ resolved = _resolve_db_path(db_path)+ if not resolved.exists():+ return 0+ with _get_conn(db_path) as conn:+ row = conn.execute(+ "SELECT COUNT(*) AS n FROM external_signals "+ "WHERE watchlist_id = ? AND captured_at >= ?",+ (watchlist_id, since.isoformat()),+ ).fetchone()+ return int(row["n"]) if row else 0++# --------------------------------------------------------------------- ## Signal CRUD# --------------------------------------------------------------------- #diff --git a/packages/core/openexecutive/monitoring/validation.py b/packages/core/openexecutive/monitoring/validation.pyindex d173e05d..cd0d88d5 100644--- a/packages/core/openexecutive/monitoring/validation.py+++ b/packages/core/openexecutive/monitoring/validation.py@@ -13,6 +13,7 @@ there.from __future__ import annotationsimport re+from urllib.parse import urlsplit, urlunsplitfrom openexecutive.alerts.models import AlertSeverity@@ -34,9 +35,43 @@ def is_valid_severity(value: str) -> bool:return value in VALID_SEVERITY_VALUES+def normalize_target(signal_type: str, target: str) -> str:+ """Canonical form of a watch target, so two spellings of one source+ compare equal (the declines memory and the duplicate-source guard key+ on this). Tickers / CIKs upper-case; URLs lower-case scheme + host and+ drop the fragment and a trailing slash. Never raises."""+ raw = (target or "").strip()+ if signal_type in ("stock", "edgar"):+ return raw.upper()+ if "://" not in raw:+ return raw.lower()+ try:+ parts = urlsplit(raw)+ except ValueError:+ return raw.lower()+ path = parts.path.rstrip("/") if parts.path not in ("", "/") else ""+ return urlunsplit((+ parts.scheme.lower(), parts.netloc.lower(), path, parts.query, "",+ ))+++def registrable_domain(url: str) -> str:+ """Host with a leading ``www.`` stripped (``""`` for non-URL targets).+ Good enough to say "same site" for the duplicate-source guard."""+ if "://" not in (url or ""):+ return ""+ try:+ host = (urlsplit(url).hostname or "").lower()+ except ValueError:+ return ""+ return host[4:] if host.startswith("www.") else host++__all__ = ["VALID_SEVERITY_VALUES","WATCHLIST_SLUG_RE","is_valid_severity","is_valid_watchlist_slug",+ "normalize_target",+ "registrable_domain",]diff --git a/packages/core/openexecutive/orchestrator/watchlist_tools.py b/packages/core/openexecutive/orchestrator/watchlist_tools.pyindex a308664a..27715f47 100644--- a/packages/core/openexecutive/orchestrator/watchlist_tools.py+++ b/packages/core/openexecutive/orchestrator/watchlist_tools.py@@ -22,7 +22,11 @@ from openexecutive.alerts.models import AlertSeverityfrom openexecutive.audit import log_event as audit_logfrom openexecutive.monitoring import store as msfrom openexecutive.monitoring.models import (+ DECLINE_KIND_EXPLICIT,+ DECLINE_REASON_NOT_RELEVANT,MODE_ACTIVE,+ ORIGIN_EXECUTIVE,+ RESEARCH_ORIGINS,is_valid_cadence,is_valid_mode,)@@ -37,6 +41,7 @@ from openexecutive.monitoring.validation import (from openexecutive.monitoring.validation import (WATCHLIST_SLUG_RE as _SLUG_RE,)+from openexecutive.monitoring.validation import normalize_targetlogger = logging.getLogger(__name__)@@ -215,16 +220,23 @@ LIST_WATCHLIST_TOOL: dict[str, Any] = {REMOVE_WATCHLIST_ENTRY_TOOL: dict[str, Any] = {"name": "remove_watchlist_entry","description": (- "Hard-delete a watchlist entry by slug. Historical "- "``external_signals`` rows that referenced this entry are KEPT for "- "audit. Use when the principal says 'stop watching X' AND wants the "- "config gone. For temporary suppression prefer "- "``tune_watchlist_entry`` with enabled=false."+ "Hard-delete a watchlist entry by slug (its recorded signal history "+ "goes with it; alerts it already raised and the audit log stay). Use "+ "when the principal says 'stop watching X' AND wants the config gone. "+ "For temporary suppression prefer ``tune_watchlist_entry`` with "+ "enabled=false. For a research-added watch, an optional ``reason`` "+ "(not_relevant | too_noisy | wrong_source) is remembered so the "+ "research pass never re-proposes it."),"input_schema": {"type": "object","properties": {"slug": {"type": "string", "description": "Slug of the entry to remove."},+ "reason": {+ "type": "string",+ "enum": ["not_relevant", "too_noisy", "wrong_source"],+ "description": "Why (research-added watches only); defaults to not_relevant.",+ },},"required": ["slug"],},@@ -278,6 +290,69 @@ TUNE_WATCHLIST_ENTRY_TOOL: dict[str, Any] = {}+# Research-only tool: the executive_research watchlist pass may only PROPOSE+# a watch. Deterministic policy (monitoring.research.watch_policy) decides+# whether it is added on its own or shown to the principal as a suggestion.+# Not part of WATCHLIST_TOOLS — the chat Executive keeps add_watchlist_entry.+PROPOSE_WATCH_TOOL: dict[str, Any] = {+ "name": "propose_watch",+ "description": (+ "Propose an ongoing external source for the company to monitor, tied "+ "to a named company entity (a competitor, vendor, ticker or initiative "+ "from the company context). Policy code decides: a proposal grounded in "+ "company data and backed by a verified finding is added on its own; "+ "anything you are not sure about becomes a suggestion the principal "+ "approves. Never re-propose a target listed as declined."+ ),+ "input_schema": {+ "type": "object",+ "properties": {+ "slug": {"type": "string", "description": "Unique kebab-case id, e.g. 'stock-acme', 'rss-acme-blog'."},+ "signal_type": {+ "type": "string",+ "enum": ["stock", "rss", "vendor_status", "edgar", "page_watch", "query"],+ },+ "target": {+ "type": "string",+ "description": (+ "Concrete, real target: a ticker (stock/edgar), a feed or page URL "+ "taken from a finding's urls (rss/vendor_status/page_watch), or a "+ "search query (query). Never invent a URL."+ ),+ },+ "grounding_entity": {+ "type": "string",+ "description": (+ "The company-context entity this watch is about, by name — a "+ "competitor, vendor, ticker, initiative or the company itself."+ ),+ },+ "rationale": {+ "type": "string",+ "description": "<=240 chars, shown to the principal: why this source is worth watching.",+ },+ "finding_index": {+ "type": "integer",+ "description": "The 1-based '#N' of the finding this proposal comes from.",+ },+ "certainty": {+ "type": "string",+ "enum": ["confident", "unsure"],+ "description": (+ "'confident' only when the entity is in the company data and the "+ "source is the entity's own (its ticker, its site, its status page). "+ "'unsure' can only turn an add into a suggestion — never the reverse."+ ),+ },+ "display_label": {"type": "string"},+ "trigger": {"type": "object", "description": "Optional adapter trigger; policy adds quiet defaults."},+ "route_to_specialist": {"type": "string"},+ },+ "required": ["slug", "signal_type", "target", "grounding_entity", "rationale", "certainty"],+ },+}++WATCHLIST_TOOLS: list[dict[str, Any]] = [ADD_WATCHLIST_ENTRY_TOOL,LIST_WATCHLIST_TOOL,@@ -310,8 +385,29 @@ def _err(tool: str, msg: str) -> str:# --------------------------------------------------------------------- #-async def handle_add_watchlist_entry(tool_input: dict[str, Any]) -> str:- tool = "add_watchlist_entry"+def _display_label_config(signal_type: str, display_label: Any) -> dict[str, Any]:+ """Map the user-facing label onto the adapter-specific config key."""+ config: dict[str, Any] = {}+ if display_label:+ if signal_type == "vendor_status":+ config["vendor_label"] = display_label+ elif signal_type == "rss":+ config["feed_label"] = display_label+ elif signal_type == "stock":+ config["display_name"] = display_label+ elif signal_type in ("query", "edgar", "page_watch"):+ config["label"] = display_label+ return config+++async def _validated_target(+ tool: str, tool_input: dict[str, Any],+) -> tuple[str, str, str, dict[str, Any], dict[str, Any]] | str:+ """Shared insert-time validation for add_watchlist_entry / propose_watch.++ Returns ``(slug, signal_type, target, config, trigger)`` with the target+ validated + normalized (a non-feed rss URL may convert to page_watch), or+ the JSON error string to return to the model."""try:slug = str(tool_input["slug"]).strip()signal_type = str(tool_input["signal_type"]).strip()@@ -321,13 +417,38 @@ async def handle_add_watchlist_entry(tool_input: dict[str, Any]) -> str:if not slug or not signal_type or not target:return _err(tool, "slug, signal_type, target are all required and non-empty")-if not _SLUG_RE.match(slug):return _err(tool, f"slug {slug!r} must match {_SLUG_RE.pattern}")-if signal_type not in list_registered_kinds():return _err(tool, f"signal_type {signal_type!r} has no registered adapter")+ trigger = tool_input.get("trigger") or {}+ if not isinstance(trigger, dict):+ return _err(tool, "trigger must be a JSON object")++ if ms.get_watchlist_item_by_slug(slug) is not None:+ return _err(tool, f"slug {slug!r} already exists; use tune_watchlist_entry to modify")++ config = _display_label_config(signal_type, tool_input.get("display_label"))+ # Validate the target before it lands: a non-feed rss URL is converted+ # to a scrape-backed page_watch (when scrapeable) or rejected, so the+ # research workflow can't seed the watchlist with dead feed rows.+ try:+ signal_type, target, config = await validate_and_normalize_target(+ signal_type, target, config,+ )+ except WatchlistTargetError as exc:+ return _err(tool, exc.reason)+ return slug, signal_type, target, config, trigger+++async def handle_add_watchlist_entry(tool_input: dict[str, Any]) -> str:+ tool = "add_watchlist_entry"+ validated = await _validated_target(tool, tool_input)+ if isinstance(validated, str):+ return validated+ slug, signal_type, target, config, trigger = validated+cadence = str(tool_input.get("cadence", "15min"))if not is_valid_cadence(cadence):return _err(tool, f"unknown cadence {cadence!r}")@@ -345,37 +466,6 @@ async def handle_add_watchlist_entry(tool_input: dict[str, Any]) -> str:floor = AlertSeverity(floor_str)ceiling = AlertSeverity(ceiling_str)- config: dict[str, Any] = {}- display_label = tool_input.get("display_label")- if display_label:- # Adapter expects vendor-specific keys; map the user-facing name.- if signal_type == "vendor_status":- config["vendor_label"] = display_label- elif signal_type == "rss":- config["feed_label"] = display_label- elif signal_type == "stock":- config["display_name"] = display_label- elif signal_type in ("query", "edgar", "page_watch"):- config["label"] = display_label-- trigger = tool_input.get("trigger") or {}- if not isinstance(trigger, dict):- return _err(tool, "trigger must be a JSON object")-- existing = ms.get_watchlist_item_by_slug(slug)- if existing is not None:- return _err(tool, f"slug {slug!r} already exists; use tune_watchlist_entry to modify")-- # Validate the target before it lands: a non-feed rss URL is converted- # to a scrape-backed page_watch (when scrapeable) or rejected, so the- # research workflow can't seed the watchlist with dead feed rows.- try:- signal_type, target, config = await validate_and_normalize_target(- signal_type, target, config,- )- except WatchlistTargetError as exc:- return _err(tool, exc.reason)-try:new_id = ms.insert_watchlist_item(slug=slug,@@ -394,6 +484,7 @@ async def handle_add_watchlist_entry(tool_input: dict[str, Any]) -> str:route_to_specialist=str(tool_input.get("route_to_specialist", "")),mode=mode,notes=str(tool_input.get("notes", ""))[:500],+ origin=ORIGIN_EXECUTIVE,)except Exception as exc:logger.exception("add_watchlist_entry: insert failed")@@ -419,6 +510,52 @@ async def handle_add_watchlist_entry(tool_input: dict[str, Any]) -> str:})+async def handle_propose_watch(tool_input: dict[str, Any], collector: list[Any]) -> str:+ """Validate a research proposal and queue it for the watch policy.++ Nothing is written here — ``watch_policy.apply_proposals`` runs after the+ model's turn and decides add / suggest / reject. A target the principal+ declined is refused HERE so a new slug cannot route around the decline.+ """+ from openexecutive.monitoring.research.watch_policy import WatchProposal++ tool = "propose_watch"+ validated = await _validated_target(tool, tool_input)+ if isinstance(validated, str):+ return validated+ slug, signal_type, target, config, trigger = validated++ normalized = normalize_target(signal_type, target)+ if ms.is_declined(normalized):+ return _err(tool, f"target {target!r} was declined by the principal — do not re-propose it")++ certainty = str(tool_input.get("certainty", "unsure")).strip().lower()+ if certainty not in ("confident", "unsure"):+ certainty = "unsure"+ raw_index = tool_input.get("finding_index")+ finding_index: int | None+ try:+ finding_index = int(raw_index) - 1 if raw_index is not None else None+ except (TypeError, ValueError):+ finding_index = None++ collector.append(WatchProposal(+ slug=slug,+ signal_type=signal_type,+ target=target,+ normalized_target=normalized,+ rationale=str(tool_input.get("rationale", ""))[:240],+ grounding_entity=str(tool_input.get("grounding_entity", ""))[:120],+ finding_index=finding_index,+ certainty=certainty,+ config=config,+ trigger=trigger,+ route_to_specialist=str(tool_input.get("route_to_specialist", ""))[:32],+ display_label=str(tool_input.get("display_label", ""))[:120],+ ))+ return json.dumps({"ok": True, "queued": slug, "signal_type": signal_type})++async def handle_list_watchlist(tool_input: dict[str, Any]) -> str:tool = "list_watchlist"signal_type = tool_input.get("signal_type")@@ -477,6 +614,20 @@ async def handle_remove_watchlist_entry(tool_input: dict[str, Any]) -> str:logger.exception("remove_watchlist_entry: delete failed")return _err(tool, f"delete failed: {exc}")+ # "Stop watching" a research-added source is feedback: remember the+ # decline so the research pass never re-proposes it under a new slug.+ if removed and item.origin in RESEARCH_ORIGINS:+ try:+ ms.insert_decline(+ normalized_target=normalize_target(item.signal_type, item.target),+ kind=DECLINE_KIND_EXPLICIT,+ reason=str(tool_input.get("reason") or DECLINE_REASON_NOT_RELEVANT),+ signal_type=item.signal_type,+ slug=item.slug,+ )+ except Exception:+ logger.exception("remove_watchlist_entry: decline record failed")+_audit(tool, removed,f"remove_watchlist_entry: {slug} ({'deleted' if removed else 'no-op'})",diff --git a/packages/core/openexecutive/scheduler/runner.py b/packages/core/openexecutive/scheduler/runner.pyindex f53823ac..12cef152 100644--- a/packages/core/openexecutive/scheduler/runner.py+++ b/packages/core/openexecutive/scheduler/runner.py@@ -71,16 +71,27 @@ def _maybe_sweep_alerts(now: datetime) -> int:):return 0_last_alert_sweep_at = now+ expired = 0try:from openexecutive.alerts.lifecycle import expire_stale_alertsexpired = expire_stale_alerts(now)if expired:logger.info("scheduler: expired %d stale alert(s)", expired)- return expiredexcept Exception:logger.exception("scheduler: alert expiry sweep failed")- return 0+ # Research watchlist housekeeping rides the same throttle: expire+ # unreviewed suggestions, auto-disable research watches that proved noisy+ # or dead, nudge when suggestions pile up. watch_policy.sweep never raises.+ try:+ from openexecutive.monitoring.research.watch_policy import sweep as sweep_watchlist++ counts = sweep_watchlist(now)+ if any(counts.values()):+ logger.info("scheduler: watchlist sweep %s", counts)+ except Exception:+ logger.exception("scheduler: watchlist sweep failed")+ return expiredasync def run_scheduler(diff --git a/packages/core/openexecutive/workflows/executive_research.py b/packages/core/openexecutive/workflows/executive_research.pyindex 7f3aaa59..34aeeb3e 100644--- a/packages/core/openexecutive/workflows/executive_research.py+++ b/packages/core/openexecutive/workflows/executive_research.py@@ -9,8 +9,10 @@ decides per finding whether to:from ``lookup_person``; the server resolves their real channel id)- Message a department channel via ``send_department_message``- Surface as a briefing card via ``create_alert``- - Add to the external monitor via ``add_watchlist_entry`` (only when- the finding is a "watch this going forward" signal — most aren't)+ - Propose an ongoing source to monitor via ``propose_watch`` (a dedicated+ pass after routing; deterministic policy in+ ``monitoring.research.watch_policy`` decides whether a proposal is added+ on its own or shown to the principal as a suggestion)- Schedule a follow-up via ``schedule_followup``- Propose a deeper workflow via ``suggest_workflow``- Ignore (passive — no tool call)@@ -113,10 +115,12 @@ def _routing_ok(calls: list[dict[str, Any]]) -> int:# Dedicated watchlist-analysis pass (runs AFTER routing). Its own budget,-# separate from the routing budget above, so adding monitors never competes-# with urgent DMs/alerts — the routing pass treats watchlist adds as rare,-# this pass treats them as the whole point.-_MAX_WATCHLIST_ADDS_PER_RUN = 4+# separate from the routing budget above, so proposing monitors never+# competes with urgent DMs/alerts. The pass only PROPOSES: the model may+# queue up to _MAX_WATCHLIST_PROPOSALS_PER_RUN candidates per run and+# `watch_policy.apply_proposals` decides add / suggest / reject under the+# settings-driven per-run budgets (direct adds + suggestions).+_MAX_WATCHLIST_PROPOSALS_PER_RUN = 6_MAX_WATCHLIST_ITERATIONS = 2@@ -202,7 +206,7 @@ def _build_synthesis_system(configured: set[str], has_roster: bool = True) -> st" (d) **Add to the watchlist** via add_watchlist_entry — ONLY ""for ongoing-monitor signals (a new competitor ticker, a vendor ""status page not yet watched). Most findings are NOT watchlist "- "material.\n"+ "material; a dedicated pass after this one proposes monitors.\n"" (e) **Schedule a follow-up** via schedule_followup for ""time-shifted chases.\n"" (f) **Suggest a deeper workflow** via suggest_workflow only "@@ -224,32 +228,48 @@ def _build_synthesis_system(configured: set[str], has_roster: bool = True) -> st)-_WATCHLIST_SYSTEM = (- "You are the user's Executive deciding what the company should "- "MONITOR going forward, based on this run's research findings.\n\n"- "This is a deliberate, forward-looking pass — distinct from routing "- "urgent items to people. Your ONLY tool is `add_watchlist_entry`.\n\n"- "## WHAT BELONGS ON THE WATCHLIST\n\n"- "An ongoing, externally-observable condition we'd want flagged when it "- "next changes — e.g. a public competitor's stock, a regulator's or "- "competitor's RSS/Atom feed, a vendor status page. A one-off event that "- "is already fully known is NOT watchlist material; the *ongoing source* "- "behind it might be.\n\n"- "## RULES\n\n"- f" - Add AT MOST {_MAX_WATCHLIST_ADDS_PER_RUN} entries this run. It is "- "normal to add several; it is also fine to add none.\n"- " - `signal_type` MUST be one of: `stock` (a ticker), `rss` (a real "- "Atom/RSS feed URL), `vendor_status` (a real status-page feed URL).\n"- " - `target` MUST be concrete and real: a ticker symbol, or a URL. "- "PREFER a URL taken from a finding's `urls` list — do NOT invent feed "- "URLs. If you cannot give a real target, do not add the entry.\n"- " - `slug` must be unique kebab-case (e.g. `stock-tsla`, "- "`rss-acme-blog`).\n"- " - SKIP anything already on the current watchlist (listed below).\n"- " - Set `route_to_specialist` to the owning specialist when obvious.\n\n"- "After your tool calls, emit ONE short line: what you added and what you "- "deliberately skipped. Be terse."-)+def _build_watchlist_system(max_direct: int, max_suggest: int) -> str:+ """System prompt for the watchlist pass. Built per call because the+ budgets come from settings; static per deployment, so it caches."""+ return (+ "You are the user's Executive deciding what the company should "+ "MONITOR going forward, based on this run's research findings.\n\n"+ "This is a deliberate, forward-looking pass — distinct from routing "+ "urgent items to people. Your ONLY tool is `propose_watch`. You do "+ "not add anything yourself: policy code adds a proposal on its own "+ "when it is grounded in company data and corroborated, and files "+ "anything less certain as a SUGGESTION the principal approves on the "+ "watch list. Being honest about certainty is what keeps the watch "+ "list trusted.\n\n"+ "## WHAT BELONGS ON THE WATCHLIST\n\n"+ "An ongoing, externally-observable source tied to a NAMED company "+ "entity — a competitor, vendor, ticker or initiative from the company "+ "context — that we'd want flagged when it next changes: a public "+ "competitor's ticker or filings, a vendor's status page, a competitor's "+ "own blog / changelog feed. A one-off event already fully known is NOT "+ "watchlist material; the *ongoing source* behind it might be. "+ "Industry news feeds and generic searches are almost never worth it.\n\n"+ "## RULES\n\n"+ " - Propose at most a handful of sources; most runs warrant zero or "+ f"one. Policy adds at most {max_direct} on its own and files at most "+ f"{max_suggest} suggestions per run — extra proposals are dropped.\n"+ " - `grounding_entity` MUST name the competitor / vendor / ticker / "+ "initiative from the company context this source is about.\n"+ " - `target` MUST be concrete and real: a ticker symbol, or a URL "+ "taken from a finding's `urls` list — do NOT invent feed URLs. If you "+ "cannot give a real target, do not propose.\n"+ " - `certainty` = 'confident' ONLY when the entity is in the company "+ "context AND the target is the entity's own source (its ticker, its "+ "site, its status page). Otherwise 'unsure'.\n"+ " - `rationale` is the one line the principal reads: why this source, "+ "for this company, now.\n"+ " - SKIP anything already on the current watchlist and NEVER propose "+ "a target listed under DECLINED.\n"+ " - `slug` must be unique kebab-case (e.g. `stock-tsla`, "+ "`rss-acme-blog`). Set `route_to_specialist` when obvious.\n\n"+ "After your tool calls, emit ONE short line: what you proposed and "+ "what you deliberately skipped. Be terse."+ )class ExecutiveResearchInput(BaseModel):@@ -571,6 +591,7 @@ class ExecutiveResearchWorkflow(Workflow):try:watchlist_calls = await _watchlist_analysis_loop(deduped, existing_watchlist,+ profile=profile, initiatives=initiatives,)except Exception:logger.exception("research: watchlist-analysis pass failed")@@ -583,7 +604,8 @@ class ExecutiveResearchWorkflow(Workflow):summary=(f"tool_calls={len(tool_calls)} "f"ok={sum(1 for t in tool_calls if t['ok'])} "- f"watchlist_adds={sum(1 for t in watchlist_calls if t['ok'])}"+ f"watchlist_adds={sum(1 for t in watchlist_calls if t.get('outcome') == 'added')} "+ f"watchlist_suggested={sum(1 for t in watchlist_calls if t.get('outcome') == 'suggested')}"),)@@ -873,46 +895,77 @@ async def _executive_synthesis_loop(async def _watchlist_analysis_loop(findings: list[ResearchFinding],existing_watchlist: list[Any],+ *,+ profile: Any = None,+ initiatives: list[Any] | None = None,) -> list[dict[str, Any]]:- """Dedicated forward-looking pass: decide what to MONITOR going forward- and call ``add_watchlist_entry`` for each.+ """Dedicated forward-looking pass: the model PROPOSES sources to monitor+ via ``propose_watch``; ``watch_policy.apply_proposals`` then decides,+ deterministically, which are added on their own (grounded in company+ data + corroborated) and which become suggestions for the principal.Separate from ``_executive_synthesis_loop`` (which routes urgent items- to people) and from its budget, so adding monitors is the explicit goal- here rather than a deprioritized afterthought. Returns the tool-call- summaries (same shape as the synthesis loop) so they merge into the- run's ``tool_calls``. Only ``add_watchlist_entry`` is offered — no- channel tools, so no synthetic Session is needed.+ to people) and from its budget. Returns tool-call summaries (same shape+ as the synthesis loop, plus ``outcome`` = added | suggested | rejected)+ so they merge into the run's ``tool_calls``. Only ``propose_watch`` is+ offered — no channel tools, so no synthetic Session is needed."""if not findings:return []from openexecutive.config import get_settings+ from openexecutive.monitoring import store as monitoring_store+ from openexecutive.monitoring.research import watch_policyfrom openexecutive.orchestrator.watchlist_tools import (- ADD_WATCHLIST_ENTRY_TOOL,- handle_add_watchlist_entry,+ PROPOSE_WATCH_TOOL,+ handle_propose_watch,)from openexecutive.providers import get_providerfrom openexecutive.workflows._synthesis import execute_tool_calls- handlers = {"add_watchlist_entry": handle_add_watchlist_entry}- tools = [ADD_WATCHLIST_ENTRY_TOOL]+ policy_settings = watch_policy.PolicySettings.load()+ proposals: list[watch_policy.WatchProposal] = []++ async def _propose(tool_input: dict[str, Any]) -> str:+ return await handle_propose_watch(tool_input, proposals)++ handlers = {"propose_watch": _propose}+ tools = [PROPOSE_WATCH_TOOL]settings = get_settings()model = settings.routing_model+ try:+ declines = monitoring_store.list_declines()+ except Exception:+ logger.exception("research.watchlist: list_declines failed")+ declines = []+ try:+ outcome_counts = monitoring_store.policy_outcome_counts()+ specialist_counts = monitoring_store.specialist_outcome_counts()+ except Exception:+ logger.exception("research.watchlist: outcome counts failed")+ outcome_counts, specialist_counts = {}, {}+messages: list[dict[str, Any]] = [{"role": "user",- "content": _render_watchlist_turn(findings, existing_watchlist),+ "content": _render_watchlist_turn(+ findings, existing_watchlist,+ declines=declines, outcome_counts=outcome_counts,+ specialist_counts=specialist_counts,+ ),},]- tool_calls: list[dict[str, Any]] = []+ system = _build_watchlist_system(+ policy_settings.max_direct_adds, policy_settings.max_suggestions,+ )+ call_summaries: list[dict[str, Any]] = []for _iteration in range(1, _MAX_WATCHLIST_ITERATIONS + 1):try:response = await get_provider(model).messages_create(model=model,max_tokens=_MAX_SYNTHESIS_TOKENS,- system=_WATCHLIST_SYSTEM,+ system=system,tools=tools, # type: ignore[arg-type]messages=messages, # type: ignore[arg-type])@@ -920,22 +973,19 @@ async def _watchlist_analysis_loop(logger.exception("research.watchlist: provider call failed")break- ok_so_far = sum(1 for t in tool_calls if t.get("ok"))- budget_remaining = max(0, _MAX_WATCHLIST_ADDS_PER_RUN - ok_so_far)+ budget_remaining = max(0, _MAX_WATCHLIST_PROPOSALS_PER_RUN - len(proposals))iter_calls = await execute_tool_calls(response, handlers, budget_remaining=budget_remaining,)- tool_calls.extend(iter_calls)+ call_summaries.extend(iter_calls)stop_reason = getattr(response, "stop_reason", "")if stop_reason != "tool_use" or not iter_calls:break-- new_ok = sum(1 for t in iter_calls if t.get("ok"))- if (ok_so_far + new_ok) >= _MAX_WATCHLIST_ADDS_PER_RUN:+ if len(proposals) >= _MAX_WATCHLIST_PROPOSALS_PER_RUN:logger.info(- "research.watchlist: budget exhausted (%d/%d); stopping",- ok_so_far + new_ok, _MAX_WATCHLIST_ADDS_PER_RUN,+ "research.watchlist: proposal cap reached (%d); stopping",+ len(proposals),)break@@ -975,7 +1025,26 @@ async def _watchlist_analysis_loop(})messages.append({"role": "user", "content": tool_results})- return tool_calls+ # Proposals the handler refused (bad target, declined, duplicate slug)+ # are already in call_summaries with ok=False; keep them so the artifact+ # shows what the model tried. Policy decides the rest.+ refused = [c for c in call_summaries if not c.get("ok")]+ for c in refused:+ c["outcome"] = "rejected"+ if not proposals:+ return refused++ ctx = watch_policy.PolicyContext(+ vocabulary=watch_policy.grounding_vocabulary(+ profile, list(initiatives or []), list(existing_watchlist),+ ),+ priority_terms=watch_policy.priority_terms(profile),+ existing=list(existing_watchlist),+ outcome_counts=outcome_counts,+ settings=policy_settings,+ )+ decided = watch_policy.apply_proposals(proposals, findings, ctx)+ return refused + decided# Tools the Executive synthesis pass MUST NOT call. Two reasons:@@ -1156,13 +1225,19 @@ def _render_synthesis_turn(findings: list[ResearchFinding], people: list[Any]) -def _render_watchlist_turn(findings: list[ResearchFinding],existing_watchlist: list[Any],+ *,+ declines: list[Any] | None = None,+ outcome_counts: dict[tuple[str, str], dict[str, int]] | None = None,+ specialist_counts: dict[str, dict[str, int]] | None = None,) -> str:- """User-turn for the dedicated watchlist-analysis pass: the findings- (with their URLs) plus the current watchlist for dedup."""+ """User-turn for the watchlist-analysis pass: the findings (with URLs),+ the current watchlist with its trust record, targets the principal+ declined, and how the policy's past guesses turned out."""parts: list[str] = ["FINDINGS FROM THIS RESEARCH RUN:\n"]for i, f in enumerate(findings, start=1):block = (- f"#{i} [{f.severity_hint.value} | {f.confidence}] "+ f"#{i} [{f.severity_hint.value} | {f.confidence}"+ f"{' | verified' if f.verification == 'confirmed' else ''}] "f"({f.source_specialist}) {f.title}\n"f" {f.summary}\n")@@ -1176,15 +1251,63 @@ def _render_watchlist_turn(slug = getattr(item, "slug", "")signal_type = getattr(item, "signal_type", "")target = getattr(item, "target", "")- if slug:- parts.append(f"- {slug} [{signal_type}] target={target}")+ if not slug:+ continue+ line = f"- {slug} [{signal_type}] target={target}"+ origin = getattr(item, "origin", "")+ if origin:+ line += f" origin={origin}"+ fired = getattr(item, "fired_count", 0) or 0+ dismissed = getattr(item, "dismiss_count", 0) or 0+ trust = getattr(item, "trust_score", None)+ if fired or dismissed:+ line += f" fired={fired} dismissed={dismissed}"+ if isinstance(trust, (int, float)) and trust < 1.0:+ line += f" trust={trust:.2f}"+ if not getattr(item, "enabled", True):+ line += " (disabled)"+ parts.append(line)else:parts.append("- (nothing yet)")+ if declines:+ parts.append("\nDECLINED BY THE PRINCIPAL (never propose these again):")+ for d in declines[:40]:+ target = getattr(d, "normalized_target", "")+ reason = getattr(d, "reason", "")+ entity = getattr(d, "entity", "")+ if target:+ line = f"- {target}"+ if entity:+ line += f" (about {entity})"+ if reason:+ line += f" — {reason}"+ parts.append(line)++ history_lines: list[str] = []+ for (signal_type, kind), tally in sorted((outcome_counts or {}).items()):+ approved = tally.get("approved", 0)+ declined = tally.get("declined", 0) + tally.get("auto_disabled", 0) + tally.get("expired", 0)+ if approved + declined:+ history_lines.append(+ f"- {signal_type} watches grounded in a {kind or 'unknown'}: "+ f"{approved} approved / {declined} declined or dropped"+ )+ for specialist, tally in sorted((specialist_counts or {}).items()):+ approved = tally.get("approved", 0)+ declined = tally.get("declined", 0) + tally.get("auto_disabled", 0) + tally.get("expired", 0)+ if approved + declined:+ history_lines.append(+ f"- proposals from {specialist}: {approved} approved / {declined} declined or dropped"+ )+ if history_lines:+ parts.append("\nHOW PAST PROPOSALS TURNED OUT:")+ parts.extend(history_lines[:12])+parts.append("\nDecide which ongoing sources are worth monitoring and call "- "add_watchlist_entry for each — real ticker/feed targets only, "- "preferring URLs from the findings above."+ "propose_watch for each — real ticker/feed targets only, preferring "+ "URLs from the findings above, each tied to a named company entity.")return "\n".join(parts)@@ -1223,7 +1346,10 @@ def _render_artifact(f"{_inline(f.summary)}")- routed = [t for t in tool_calls if t.get("tool") != "add_watchlist_entry"]+ routed = [+ t for t in tool_calls+ if t.get("tool") not in ("add_watchlist_entry", "propose_watch")+ ]if routed:lines.append("\n## Actions routed")for t in routed[:25]:@@ -1233,15 +1359,29 @@ def _render_artifact()watchlist_calls = [- t for t in tool_calls if t.get("tool") == "add_watchlist_entry"+ t for t in tool_calls+ if t.get("tool") in ("add_watchlist_entry", "propose_watch")+ ]+ added = [+ t for t in watchlist_calls+ if t.get("outcome") == "added" or (t.get("tool") == "add_watchlist_entry" and t.get("ok"))]- if watchlist_calls:+ suggested = [t for t in watchlist_calls if t.get("outcome") == "suggested"]+ rejected = [t for t in watchlist_calls if t not in added and t not in suggested]+ if added:lines.append("\n## Now watching")- for t in watchlist_calls[:25]:- # Show failures too (e.g. slug-dedup rejections) so an add that- # didn't take isn't silently dropped from the artifact.- mark = "✓" if t.get("ok") else "✗"- lines.append(f"- {mark} {_inline(t.get('result_preview', ''))}")+ for t in added[:25]:+ lines.append(f"- ✓ {_inline(t.get('result_preview', ''))}")+ if suggested:+ lines.append("\n## Suggested for your approval (see /watchlist)")+ for t in suggested[:25]:+ lines.append(f"- ? {_inline(t.get('result_preview', ''))}")+ if rejected:+ # Show refusals too (declined target, bad feed, policy) so a proposal+ # that didn't take isn't silently dropped from the artifact.+ lines.append("\n## Watch proposals not taken")+ for t in rejected[:25]:+ lines.append(f"- ✗ {_inline(t.get('result_preview', ''))}")lines.append("\n## Per-specialist activity")for s in per_specialist:diff --git a/packages/core/openexecutive/workflows/morning_brief.py b/packages/core/openexecutive/workflows/morning_brief.pyindex 35c790d7..3f30016b 100644--- a/packages/core/openexecutive/workflows/morning_brief.py+++ b/packages/core/openexecutive/workflows/morning_brief.py@@ -140,8 +140,10 @@ class MorningBriefWorkflow(Workflow):activity = []handled = brief_state.handled_since(since)+ pending_suggestions = brief_state.pending_watch_suggestions()fingerprint = brief_state.build_brief_fingerprint(today_data=today_data, activity=activity, handled=handled, since=since,+ pending_watch_suggestions=pending_suggestions,)previous = brief_state.last_delivered(BRIEF_KIND)suppressed = (@@ -200,6 +202,7 @@ class MorningBriefWorkflow(Workflow):artifact_text = await synthesize_briefing_narrative(today_data=today_data, activity=activity, period_label=period,standalone=True, since=since, handled=handled,+ pending_watch_suggestions=pending_suggestions,)except Exception as exc:logger.exception("morning_brief: synthesis failed")diff --git a/packages/core/tests/unit/test_alert_sweep_runner.py b/packages/core/tests/unit/test_alert_sweep_runner.pyindex a86b32be..24b3e22f 100644--- a/packages/core/tests/unit/test_alert_sweep_runner.py+++ b/packages/core/tests/unit/test_alert_sweep_runner.py@@ -6,12 +6,14 @@ from datetime import UTC, datetime, timedeltaimport pytestfrom openexecutive.alerts import lifecycle+from openexecutive.monitoring.research import watch_policyfrom openexecutive.scheduler import runner@pytest.fixture(autouse=True)def _reset_throttle(monkeypatch: pytest.MonkeyPatch) -> None:monkeypatch.setattr(runner, "_last_alert_sweep_at", None)+ monkeypatch.setattr(watch_policy, "sweep", lambda now, db_path=None: {"expired": 0, "disabled": 0, "nudged": 0})def test_maybe_sweep_throttles_to_interval(monkeypatch: pytest.MonkeyPatch) -> None:@@ -38,3 +40,30 @@ def test_maybe_sweep_swallows_errors(monkeypatch: pytest.MonkeyPatch) -> None:assert runner._maybe_sweep_alerts(datetime.now(UTC)) == 0# The failed attempt still consumed the interval slot (no hot retry loop).assert runner._last_alert_sweep_at is not None+++def test_maybe_sweep_runs_the_watchlist_sweep_on_the_same_throttle(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ seen: list[datetime] = []+ monkeypatch.setattr(lifecycle, "expire_stale_alerts", lambda now, db_path=None: 0)+ monkeypatch.setattr(+ watch_policy, "sweep",+ lambda now, db_path=None: (seen.append(now), {"expired": 1, "disabled": 0, "nudged": 0})[1],+ )+ t0 = datetime.now(UTC)+ runner._maybe_sweep_alerts(t0)+ runner._maybe_sweep_alerts(t0 + timedelta(minutes=5))+ assert seen == [t0]+++def test_watchlist_sweep_failure_never_breaks_the_alert_sweep(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setattr(lifecycle, "expire_stale_alerts", lambda now, db_path=None: 3)++ def boom(now: datetime, db_path=None) -> dict[str, int]: # noqa: ARG001+ raise RuntimeError("watchlist db locked")++ monkeypatch.setattr(watch_policy, "sweep", boom)+ assert runner._maybe_sweep_alerts(datetime.now(UTC)) == 3diff --git a/packages/core/tests/unit/test_brief_state.py b/packages/core/tests/unit/test_brief_state.pyindex ffc1f867..c51080f9 100644--- a/packages/core/tests/unit/test_brief_state.py+++ b/packages/core/tests/unit/test_brief_state.py@@ -125,10 +125,36 @@ def test_handled_since_reads_review_audit_events(tmp_path: Path, monkeypatch: pymonkeypatch.setattr(audit_logger, "get_audit_logger", lambda: al)al.log("alert_review_routed", "Routed 'Acme renewal' to Dana", actor="executive")al.log("alert_review_closed", "Resolved 'Stripe incident' — vendor marked resolved", actor="executive")+ al.log("watchlist_research_added", "Started watching stock-acme — competitor ticker", actor="executive")+ al.log("watchlist_auto_disabled", "Stopped watching rss-noise — dismissed 3 of 6", actor="scheduler")al.log("tool_invocation", "unrelated", actor="executive")handled = brief_state.handled_since(datetime.now(UTC) - timedelta(hours=1))kinds = sorted(h["kind"] for h in handled)- assert kinds == ["closed", "routed"]+ assert kinds == ["closed", "routed", "stopped_watching", "watching"]assert all(h["summary"] and h["at"] for h in handled)assert brief_state.handled_since(datetime.now(UTC) + timedelta(hours=1)) == []+++def test_fingerprint_moves_with_pending_watch_suggestions() -> None:+ since = datetime.now(UTC) - timedelta(hours=12)+ base = dict(today_data={"proposals": [], "departments": [], "people": []}, activity=[], handled=[], since=since)+ assert brief_state.build_brief_fingerprint(**base) == brief_state.build_brief_fingerprint(**base, pending_watch_suggestions=0)+ assert brief_state.build_brief_fingerprint(**base) != brief_state.build_brief_fingerprint(**base, pending_watch_suggestions=2)+++def test_pending_watch_suggestions_counts_dry_run_research_rows(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ from openexecutive.alerts.store import initialize_db as init_alerts+ from openexecutive.memory.episodic import initialize_db as init_episodic+ from openexecutive.monitoring import store as ms++ db = tmp_path / "w.db"+ monkeypatch.setattr("openexecutive.memory.episodic.DB_PATH", db)+ init_episodic(db)+ init_alerts(db)+ ms.initialize_db(db)+ assert brief_state.pending_watch_suggestions() == 0+ ms.insert_watchlist_item(slug="rss-a", signal_type="rss", target="https://a.com/f",+ mode="dry_run", origin="research_proposed", db_path=db)+ ms.insert_watchlist_item(slug="rss-b", signal_type="rss", target="https://b.com/f", db_path=db)+ assert brief_state.pending_watch_suggestions() == 1diff --git a/packages/core/tests/unit/test_briefing_context_render.py b/packages/core/tests/unit/test_briefing_context_render.pyindex 61fbcf7c..a238cb50 100644--- a/packages/core/tests/unit/test_briefing_context_render.py+++ b/packages/core/tests/unit/test_briefing_context_render.py@@ -80,3 +80,13 @@ def test_eod_context_splits_and_lists_handled() -> None:assert "CARRIED OVER: 2 older item(s)" in textlegacy = _render_eod_context(period_label="p", today_data=_today(), activity=[])assert "STILL AWAITING DECISION:" in legacy and "CARRIED OVER" not in legacy+++def test_render_context_mentions_pending_watch_suggestions_once() -> None:+ since = datetime.now(UTC) - timedelta(hours=24)+ text = render_briefing_context(+ period_label="p", today_data=_today(), activity=[], since=since, pending_watch_suggestions=2,+ )+ assert "WATCH SUGGESTIONS WAITING: 2 sources" in text and "/watchlist" in text+ quiet = render_briefing_context(period_label="p", today_data=_today(), activity=[], since=since)+ assert "WATCH SUGGESTIONS" not in quietdiff --git a/packages/core/tests/unit/test_company_profile.py b/packages/core/tests/unit/test_company_profile.pyindex f859a128..4a8313bd 100644--- a/packages/core/tests/unit/test_company_profile.py+++ b/packages/core/tests/unit/test_company_profile.py@@ -226,3 +226,15 @@ def test_concurrent_saves_do_not_break_each_other(tmp_path: Path):assert errors == []assert CompanyProfile.load_from_yaml(path).name.startswith("w")assert [p.name for p in tmp_path.iterdir()] == ["profile.yaml"]+++def test_profile_vendors_and_tickers_render_and_roundtrip(tmp_path: Path):+ profile = CompanyProfile(name="Acme", vendors=["Stripe", "AWS"], tickers=["ACME"])+ block = profile.to_prompt_block()+ assert "Vendors: Stripe, AWS" in block and "Tracked tickers: ACME" in block+ path = tmp_path / "p.yaml"+ profile.save_to_yaml(path)+ loaded = CompanyProfile.load_from_yaml(path)+ assert loaded.vendors == ["Stripe", "AWS"] and loaded.tickers == ["ACME"]+ # Older profile files without the fields still load.+ assert CompanyProfile.model_validate({"name": "Old"}).vendors == []diff --git a/packages/core/tests/unit/test_executive_research_scheduler.py b/packages/core/tests/unit/test_executive_research_scheduler.pyindex 63c8dcae..e71e044e 100644--- a/packages/core/tests/unit/test_executive_research_scheduler.py+++ b/packages/core/tests/unit/test_executive_research_scheduler.py@@ -48,6 +48,25 @@ def test_state_hash_changes_when_watchlist_grows(db: Path) -> None:assert before != after+def test_state_hash_ignores_suggestions_and_disabled_rows(db: Path) -> None:+ """Approving / declining a research suggestion must not read as a state+ change that triggers a fresh 7-specialist run."""+ before = research_scheduler.compute_research_state_hash(db_path=db)+ monitoring_store.insert_watchlist_item(+ slug="rss-sugg", signal_type="rss", target="https://s.com/feed",+ mode="dry_run", origin="research_proposed", db_path=db,+ )+ assert research_scheduler.compute_research_state_hash(db_path=db) == before+ item = monitoring_store.get_watchlist_item_by_slug("rss-sugg", db_path=db)+ assert item is not None and item.id is not None+ monitoring_store.delete_watchlist_item(item.id, db_path=db)+ assert research_scheduler.compute_research_state_hash(db_path=db) == before+ monitoring_store.insert_watchlist_item(+ slug="stock-off", signal_type="stock", target="OFF", enabled=False, db_path=db,+ )+ assert research_scheduler.compute_research_state_hash(db_path=db) == before++def test_state_hash_changes_when_initiative_added(db: Path) -> None:from openexecutive.memory.episodic import store_initiativediff --git a/packages/core/tests/unit/test_executive_research_watchlist.py b/packages/core/tests/unit/test_executive_research_watchlist.pyindex e647d79e..f89b8a76 100644--- a/packages/core/tests/unit/test_executive_research_watchlist.py+++ b/packages/core/tests/unit/test_executive_research_watchlist.py@@ -21,6 +21,19 @@ from openexecutive.monitoring.research.models import ResearchFindingfrom openexecutive.workflows import executive_research as er[email protected](autouse=True)+def _passthrough_target_validation(monkeypatch: pytest.MonkeyPatch) -> None:+ """The pass validates rss targets at insert time with a real fetch; stub+ it so a feed URL never hits the network here (covered by+ test_target_validation.py)."""+ from openexecutive.orchestrator import watchlist_tools as wt++ async def _passthrough(signal_type: str, target: str, config: dict) -> tuple[str, str, dict]:+ return signal_type, target, config++ monkeypatch.setattr(wt, "validate_and_normalize_target", _passthrough)++@pytest.fixturedef db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:db_path = tmp_path / "test_research.db"@@ -40,9 +53,29 @@ def _finding(title: str = "Tesla cut prices") -> ResearchFinding:suggested_audience="principal",confidence="high",relevant_urls=["https://example.com/feed.xml"],+ source_specialist="cfo",)+def _profile():+ from openexecutive.memory.company_profile import CompanyProfile++ return CompanyProfile.model_validate({+ "name": "Sente Labs",+ "competitive_landscape": {"primary_competitors": ["Tesla"]},+ "tickers": ["TSLA"],+ })+++def _propose(slug: str, signal_type: str, target: str, entity: str = "Tesla",+ certainty: str = "confident", **extra: Any) -> tuple[str, dict[str, Any]]:+ return ("propose_watch", {+ "slug": slug, "signal_type": signal_type, "target": target,+ "grounding_entity": entity, "rationale": f"watch {slug}",+ "certainty": certainty, "finding_index": 1, **extra,+ })++def _resp(tool_uses: list[tuple[str, dict[str, Any]]], stop_reason: str = "end_turn"):msg = MagicMock()msg.stop_reason = stop_reason@@ -95,32 +128,55 @@ class FakeStore:@pytest.mark.asyncio-async def test_watchlist_pass_adds_entry(db: Path, monkeypatch: pytest.MonkeyPatch) -> None:+async def test_watchlist_pass_adds_grounded_proposal_directly(+ db: Path, monkeypatch: pytest.MonkeyPatch,+) -> None:+ _stub_provider(monkeypatch, [_resp([_propose("stock-tsla", "stock", "TSLA")])])+ calls = await er._watchlist_analysis_loop(+ [_finding()], existing_watchlist=[], profile=_profile(), initiatives=[],+ )+ assert [c["outcome"] for c in calls] == ["added"]+ row = monitoring_store.get_watchlist_item_by_slug("stock-tsla", db_path=db)+ assert row is not None+ assert row.origin == "research" and row.mode == "active"+ assert row.notes == "watch stock-tsla"+ # Quiet defaults, not the handler's 15min/low.+ assert row.cadence == "daily" and row.severity_floor.value == "medium"+ assert row.trigger_json == {"abs_change_pct_gte": 5}+++async def test_watchlist_pass_files_uncertain_proposal_as_suggestion(+ db: Path, monkeypatch: pytest.MonkeyPatch,+) -> None:_stub_provider(monkeypatch, [- _resp([("add_watchlist_entry", {- "slug": "stock-tsla", "signal_type": "stock", "target": "TSLA",- })]),+ _resp([_propose("rss-initech", "rss", "https://initech.com/feed.xml", entity="Initech",+ certainty="unsure")]),])- calls = await er._watchlist_analysis_loop([_finding()], existing_watchlist=[])- assert any(c["tool"] == "add_watchlist_entry" and c["ok"] for c in calls)- slugs = [w.slug for w in monitoring_store.list_watchlist(db_path=db)]- assert "stock-tsla" in slugs+ calls = await er._watchlist_analysis_loop(+ [_finding()], existing_watchlist=[], profile=_profile(), initiatives=[],+ )+ assert [c["outcome"] for c in calls] == ["suggested"]+ row = monitoring_store.get_watchlist_item_by_slug("rss-initech", db_path=db)+ assert row is not None+ assert row.origin == "research_proposed" and row.mode == "dry_run"+ assert monitoring_store.list_pending_suggestions(db_path=db)[0].slug == "rss-initech"@pytest.mark.asyncio-async def test_watchlist_pass_respects_budget(db: Path, monkeypatch: pytest.MonkeyPatch) -> None:- # One response asking for more adds than the budget allows.+async def test_watchlist_pass_respects_proposal_cap(db: Path, monkeypatch: pytest.MonkeyPatch) -> None:over = [- ("add_watchlist_entry", {- "slug": f"stock-x{i}", "signal_type": "stock", "target": f"X{i}",- })- for i in range(er._MAX_WATCHLIST_ADDS_PER_RUN + 3)+ _propose(f"stock-x{i}", "stock", f"X{i}", entity="Nobody", certainty="unsure")+ for i in range(er._MAX_WATCHLIST_PROPOSALS_PER_RUN + 3)]_stub_provider(monkeypatch, [_resp(over, stop_reason="tool_use")])- calls = await er._watchlist_analysis_loop([_finding()], existing_watchlist=[])- ok = [c for c in calls if c["ok"]]- assert len(ok) == er._MAX_WATCHLIST_ADDS_PER_RUN- assert len(monitoring_store.list_watchlist(db_path=db)) == er._MAX_WATCHLIST_ADDS_PER_RUN+ calls = await er._watchlist_analysis_loop(+ [_finding()], existing_watchlist=[], profile=_profile(), initiatives=[],+ )+ queued = [c for c in calls if c.get("tool") == "propose_watch" and c["result_preview"] != "over budget — skipped"]+ assert len(queued) == er._MAX_WATCHLIST_PROPOSALS_PER_RUN+ # Policy then files at most its own suggestion budget (2 by default).+ assert len(monitoring_store.list_pending_suggestions(db_path=db)) == 2@pytest.mark.asyncio@@ -132,16 +188,53 @@ async def test_watchlist_pass_skips_already_watched(monitoring_store.insert_watchlist_item(slug="stock-tsla", signal_type="stock", target="TSLA", db_path=db,)- _stub_provider(monkeypatch, [- _resp([("add_watchlist_entry", {- "slug": "stock-tsla", "signal_type": "stock", "target": "TSLA",- })]),- ])- calls = await er._watchlist_analysis_loop([_finding()], existing_watchlist=[])+ _stub_provider(monkeypatch, [_resp([_propose("stock-tsla", "stock", "TSLA")])])+ calls = await er._watchlist_analysis_loop(+ [_finding()], existing_watchlist=monitoring_store.list_watchlist(db_path=db),+ profile=_profile(), initiatives=[],+ )assert all(not c["ok"] for c in calls) # rejected: slug already existsassert len(monitoring_store.list_watchlist(db_path=db)) == 1+async def test_watchlist_pass_never_calls_add_tool(db: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ # A model that tries the old tool gets "unknown tool" — nothing lands.+ _stub_provider(monkeypatch, [+ _resp([("add_watchlist_entry", {"slug": "stock-tsla", "signal_type": "stock", "target": "TSLA"})]),+ ])+ calls = await er._watchlist_analysis_loop(+ [_finding()], existing_watchlist=[], profile=_profile(), initiatives=[],+ )+ assert calls and all(not c["ok"] for c in calls)+ assert monitoring_store.list_watchlist(db_path=db) == []+++def test_watchlist_turn_renders_trust_declines_and_history(db: Path) -> None:+ monitoring_store.insert_watchlist_item(+ slug="rss-acme", signal_type="rss", target="https://acme.com/feed", origin="research", db_path=db,+ )+ import sqlite3++ with sqlite3.connect(db) as conn:+ conn.execute("UPDATE watchlist SET fired_count = 4, dismiss_count = 2, trust_score = 0.64")+ monitoring_store.insert_decline(+ normalized_target="https://initech.com/feed", kind="declined_explicit",+ reason="not_relevant", entity="Initech", db_path=db,+ )+ text = er._render_watchlist_turn(+ [_finding()], monitoring_store.list_watchlist(db_path=db),+ declines=monitoring_store.list_declines(db_path=db),+ outcome_counts={("stock", "competitor"): {"approved": 4, "declined": 1}},+ specialist_counts={"cso": {"approved": 2, "auto_disabled": 1}},+ )+ assert "origin=research fired=4 dismissed=2 trust=0.64" in text+ assert "DECLINED BY THE PRINCIPAL" in text and "https://initech.com/feed (about Initech) — not_relevant" in text+ assert "stock watches grounded in a competitor: 4 approved / 1 declined or dropped" in text+ assert "proposals from cso: 2 approved / 1 declined or dropped" in text+ assert "propose_watch" in text++@pytest.mark.asyncioasync def test_watchlist_pass_empty_findings_noop(monkeypatch: pytest.MonkeyPatch) -> None:# No provider call should happen for empty findings.@@ -162,7 +255,7 @@ async def test_run_persists_artifact_as_recent_research(async def fake_synth(deduped):return ("ran", [])- async def fake_watchlist(findings, existing_watchlist):+ async def fake_watchlist(findings, existing_watchlist, **_kw):return []monkeypatch.setattr(er, "research_one_specialist", fake_research_one)@@ -206,15 +299,12 @@ async def test_watchlist_pass_multi_iteration() -> None:"""Exercise the message-threading path: iter 1 adds with stop_reason'tool_use' (budget remaining) so the loop continues; iter 2 ends."""- r1 = _resp(- [("add_watchlist_entry", {- "slug": "stock-tsla", "signal_type": "stock", "target": "TSLA",- })],- stop_reason="tool_use",- )+ r1 = _resp([_propose("stock-tsla", "stock", "TSLA")], stop_reason="tool_use")r2 = _resp([], stop_reason="end_turn")_stub_provider(monkeypatch, [r1, r2])- calls = await er._watchlist_analysis_loop([_finding()], existing_watchlist=[])+ calls = await er._watchlist_analysis_loop(+ [_finding()], existing_watchlist=[], profile=_profile(), initiatives=[],+ )ok = [c for c in calls if c["ok"]]assert len(ok) == 1assert "stock-tsla" in [w.slug for w in monitoring_store.list_watchlist(db_path=db)]diff --git a/packages/core/tests/unit/test_executive_research_workflow.py b/packages/core/tests/unit/test_executive_research_workflow.pyindex fbd86ec7..3bb467c8 100644--- a/packages/core/tests/unit/test_executive_research_workflow.py+++ b/packages/core/tests/unit/test_executive_research_workflow.py@@ -211,7 +211,7 @@ async def test_workflow_runs_end_to_end_with_stubbed_specialists("openexecutive.workflows.executive_research.research_one_specialist",fake_research_one,)- async def fake_watchlist(findings, existing_watchlist):+ async def fake_watchlist(findings, existing_watchlist, **_kw):return []monkeypatch.setattr(@@ -330,7 +330,7 @@ async def test_workflow_drops_low_confidence_pre_synthesis("openexecutive.workflows.executive_research.research_one_specialist",fake_research_one,)- async def fake_watchlist(findings, existing_watchlist):+ async def fake_watchlist(findings, existing_watchlist, **_kw):return []monkeypatch.setattr(diff --git a/packages/core/tests/unit/test_watch_policy.py b/packages/core/tests/unit/test_watch_policy.pynew file mode 100644index 00000000..b9c207b5--- /dev/null+++ b/packages/core/tests/unit/test_watch_policy.py@@ -0,0 +1,414 @@+"""The research watchlist policy: grounded proposals go straight in, uncertain+ones become suggestions, declines are remembered, research watches retire."""+from __future__ import annotations++from datetime import UTC, datetime, timedelta+from pathlib import Path+from types import SimpleNamespace+from typing import Any++import pytest++from openexecutive.alerts.store import initialize_db as initialize_alerts_db+from openexecutive.audit import AuditLogger, set_audit_logger+from openexecutive.memory.company_profile import CompanyProfile+from openexecutive.memory.episodic import initialize_db as initialize_episodic_db+from openexecutive.monitoring import store as ms+from openexecutive.monitoring.models import (+ DECLINE_KIND_EXPIRED,+ DECLINE_KIND_EXPLICIT,+ MODE_ACTIVE,+ MODE_DRY_RUN,+ ORIGIN_RESEARCH,+ ORIGIN_RESEARCH_PROPOSED,+)+from openexecutive.monitoring.research import watch_policy as wp+from openexecutive.monitoring.research.models import ResearchFinding+from openexecutive.monitoring.validation import normalize_target, registrable_domain+++def db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ db_path = tmp_path / "policy.db"+ monkeypatch.setattr("openexecutive.memory.episodic.DB_PATH", db_path)+ monkeypatch.setattr("openexecutive.alerts.store.DB_PATH", db_path)+ initialize_episodic_db(db_path)+ initialize_alerts_db(db_path)+ ms.initialize_db(db_path)+ audit = AuditLogger(db_path=db_path)+ audit.initialize_db()+ set_audit_logger(audit)+ return db_path+++def _profile() -> CompanyProfile:+ return CompanyProfile.model_validate({+ "name": "Sente Labs",+ "competitive_landscape": {"primary_competitors": ["Acme Corp", "Globex"]},+ "strategic_priorities": {"current_year": ["Expand into EU enterprise accounts"]},+ "vendors": ["Stripe"],+ "tickers": ["ACME"],+ })+++def _finding(**kw: Any) -> ResearchFinding:+ base: dict[str, Any] = {+ "title": "Acme cut prices",+ "summary": "Acme Corp cut list prices 20% on 2026-09-01.",+ "confidence": "high",+ "relevant_urls": ["https://www.acme.com/blog/pricing"],+ "source_specialist": "cso",+ }+ base.update(kw)+ return ResearchFinding(**base)+++def _proposal(**kw: Any) -> wp.WatchProposal:+ base: dict[str, Any] = {+ "slug": "rss-acme-blog", "signal_type": "rss",+ "target": "https://www.acme.com/blog/feed.xml",+ "grounding_entity": "Acme Corp", "rationale": "Competitor pricing moves",+ "finding_index": 0, "certainty": "confident",+ }+ base.update(kw)+ base["normalized_target"] = normalize_target(base["signal_type"], base["target"])+ return wp.WatchProposal(**base)+++def _ctx(existing: list[Any] | None = None, **kw: Any) -> wp.PolicyContext:+ profile = _profile()+ initiatives = [SimpleNamespace(title="Launch Helios API", status="active")]+ existing = existing or []+ return wp.PolicyContext(+ vocabulary=wp.grounding_vocabulary(profile, initiatives, existing),+ priority_terms=wp.priority_terms(profile),+ existing=existing,+ **kw,+ )+++# --------------------------------------------------------------------- #+# Vocabulary + matching+# --------------------------------------------------------------------- #+++def test_vocabulary_covers_profile_initiatives_and_watch_labels(db: Path) -> None:+ ms.insert_watchlist_item(+ slug="stock-hubs", signal_type="stock", target="HUBS",+ config={"display_name": "HubSpot"}, db_path=db,+ )+ vocab = wp.grounding_vocabulary(+ _profile(), [SimpleNamespace(title="Launch Helios API")], ms.list_watchlist(db_path=db),+ )+ assert vocab["sente labs"] == wp.KIND_COMPANY+ assert vocab["acme corp"] == wp.KIND_COMPETITOR+ assert vocab["stripe"] == wp.KIND_VENDOR+ assert vocab["acme"] == wp.KIND_TICKER+ assert vocab["launch helios api"] == wp.KIND_INITIATIVE+ assert vocab["hubspot"] == wp.KIND_WATCH and vocab["hubs"] == wp.KIND_WATCH+++def test_match_entity_is_token_based_and_prefers_company_data() -> None:+ vocab = {"acme corp": wp.KIND_COMPETITOR, "acme": wp.KIND_WATCH, "stripe": wp.KIND_VENDOR}+ assert wp.match_entity("Acme", vocab) == ("acme corp", wp.KIND_COMPETITOR)+ assert wp.match_entity("ACME CORP.", vocab) == ("acme corp", wp.KIND_COMPETITOR)+ assert wp.match_entity("Stripe Inc", vocab) == ("stripe", wp.KIND_VENDOR)+ assert wp.match_entity("Initech", vocab) is None+ assert wp.match_entity("", vocab) is None+++def test_priority_terms_drop_stopwords() -> None:+ assert wp.priority_terms(_profile()) == ["enterprise", "accounts"]+++def test_normalize_target_and_domain() -> None:+ assert normalize_target("stock", " acme ") == "ACME"+ assert normalize_target("rss", "HTTPS://www.Acme.com/feed/#top") == "https://www.acme.com/feed"+ assert normalize_target("rss", "https://acme.com/") == "https://acme.com"+ assert registrable_domain("https://www.acme.com/blog") == "acme.com"+ assert registrable_domain("ACME") == ""+++# --------------------------------------------------------------------- #+# Classification ledger+# --------------------------------------------------------------------- #+++def test_grounded_own_source_high_confidence_is_direct() -> None:+ d = wp.classify(_proposal(), _finding(), _ctx())+ # +2 competitor, +1 own domain, +1 high confidence = 4+ assert d.tier == wp.TIER_DIRECT and d.score == 4+ assert d.grounding_kind == wp.KIND_COMPETITOR+++def test_ticker_in_profile_is_own_source_for_stock() -> None:+ p = _proposal(slug="stock-acme", signal_type="stock", target="ACME", grounding_entity="Acme Corp")+ d = wp.classify(p, _finding(), _ctx())+ assert d.tier == wp.TIER_DIRECT+++def test_vendor_status_page_is_direct() -> None:+ p = _proposal(+ slug="vendor-stripe", signal_type="vendor_status",+ target="https://status.stripe.com/feed.atom", grounding_entity="Stripe",+ )+ d = wp.classify(p, _finding(), _ctx())+ assert d.tier == wp.TIER_DIRECT and "own source" in " ".join(d.reasons)+++def test_entity_not_in_company_data_is_never_direct() -> None:+ p = _proposal(grounding_entity="Initech", target="https://initech.com/feed.xml")+ d = wp.classify(p, _finding(verification="confirmed", source_specialist="cso,cfo"), _ctx())+ assert d.tier == wp.TIER_SUGGEST+ assert d.score == 3 # own-source +1 needs an entity; high +1, verified +1, consensus +1+++def test_medium_confidence_grounded_needs_more_corroboration() -> None:+ d = wp.classify(_proposal(), _finding(confidence="medium"), _ctx())+ assert d.tier == wp.TIER_SUGGEST and d.score == 3+ d2 = wp.classify(_proposal(), _finding(confidence="medium", verification="confirmed"), _ctx())+ assert d2.tier == wp.TIER_DIRECT and d2.score == 4+++def test_unsure_only_downgrades() -> None:+ d = wp.classify(_proposal(certainty="unsure"), _finding(), _ctx())+ assert d.tier == wp.TIER_SUGGEST and "unsure" in d.reasons[-1]+ # 'confident' cannot lift an ungrounded proposal.+ d2 = wp.classify(_proposal(grounding_entity="Initech", certainty="confident"), _finding(), _ctx())+ assert d2.tier == wp.TIER_SUGGEST+++def test_query_is_always_a_suggestion() -> None:+ p = _proposal(slug="q-acme", signal_type="query", target="Acme Corp pricing", grounding_entity="Acme Corp")+ d = wp.classify(p, _finding(verification="confirmed"), _ctx())+ assert d.tier == wp.TIER_SUGGEST and "standing web queries" in d.reasons[-1]+++def test_same_site_already_watched_is_rejected(db: Path) -> None:+ ms.insert_watchlist_item(+ slug="rss-acme-news", signal_type="rss", target="https://acme.com/news/feed", db_path=db,+ )+ existing = ms.list_watchlist(db_path=db)+ d = wp.classify(_proposal(), _finding(), _ctx(existing))+ assert d.tier == wp.TIER_REJECT and "already watched" in d.reasons[-1]+++def test_ceiling_turns_direct_into_suggestion(db: Path) -> None:+ for i in range(3):+ ms.insert_watchlist_item(slug=f"stock-x{i}", signal_type="stock", target=f"X{i}", db_path=db)+ ctx = _ctx(ms.list_watchlist(db_path=db), settings=wp.PolicySettings(max_enabled=3))+ d = wp.classify(_proposal(), _finding(), ctx)+ assert d.tier == wp.TIER_SUGGEST and "ceiling" in d.reasons[-1]+++def test_history_adjusts_only_with_enough_samples() -> None:+ counts = {("rss", wp.KIND_COMPETITOR): {"approved": 1, "declined": 4}}+ d = wp.classify(_proposal(), _finding(), _ctx(outcome_counts=counts))+ assert d.score == 3 and d.tier == wp.TIER_SUGGEST # −1 from history+ few = {("rss", wp.KIND_COMPETITOR): {"approved": 0, "declined": 3}}+ assert wp.classify(_proposal(), _finding(), _ctx(outcome_counts=few)).score == 4+++# --------------------------------------------------------------------- #+# Quiet defaults+# --------------------------------------------------------------------- #+++def test_quiet_defaults_add_keywords_and_medium_floor() -> None:+ cadence, floor, trigger = wp.quiet_defaults(_proposal(), "acme corp", ["enterprise"])+ assert cadence == "daily" and floor.value == "medium"+ kws = trigger["keywords"]+ assert kws[:2] == ["acme", "corp"] and "pricing" in kws and "enterprise" in kws+ _, _, stock_trigger = wp.quiet_defaults(+ _proposal(signal_type="stock", target="ACME"), "acme", [],+ )+ assert stock_trigger == {"abs_change_pct_gte": 5}+ cadence_pw, _, _ = wp.quiet_defaults(+ _proposal(signal_type="page_watch", target="https://acme.com/pricing"), "acme", [],+ )+ assert cadence_pw == "weekly"+++# --------------------------------------------------------------------- #+# apply_proposals+# --------------------------------------------------------------------- #+++def test_apply_adds_direct_and_files_suggestion(db: Path) -> None:+ findings = [_finding(), _finding(title="Initech raised", summary="Initech raised.", confidence="medium")]+ proposals = [+ _proposal(),+ _proposal(slug="rss-initech", target="https://initech.com/feed.xml",+ grounding_entity="Initech", finding_index=1, certainty="unsure"),+ ]+ out = wp.apply_proposals(proposals, findings, _ctx(), db_path=db)+ assert [o["outcome"] for o in out] == ["added", "suggested"]+ rows = {w.slug: w for w in ms.list_watchlist(db_path=db)}+ acme, initech = rows["rss-acme-blog"], rows["rss-initech"]+ assert acme.origin == ORIGIN_RESEARCH and acme.mode == MODE_ACTIVE+ assert acme.notes == "Competitor pricing moves" and acme.severity_floor.value == "medium"+ assert acme.config_json["_policy"]["grounding_kind"] == wp.KIND_COMPETITOR+ assert initech.origin == ORIGIN_RESEARCH_PROPOSED and initech.mode == MODE_DRY_RUN+ assert ms.list_pending_suggestions(db_path=db)[0].slug == "rss-initech"+++def test_apply_honours_budgets_and_duplicate_targets(db: Path) -> None:+ findings = [_finding()]+ proposals = [+ _proposal(slug="stock-acme", signal_type="stock", target="ACME"),+ _proposal(slug="stock-acme-2", signal_type="stock", target="acme"), # same target+ _proposal(slug="vendor-stripe", signal_type="vendor_status",+ target="https://status.stripe.com/feed.atom", grounding_entity="Stripe"),+ _proposal(slug="rss-acme-blog"), # third direct → budget → suggestion+ _proposal(slug="rss-initech", target="https://initech.com/feed.xml", grounding_entity="Initech"),+ _proposal(slug="rss-globex", target="https://globex.com/feed.xml", grounding_entity="Globex",+ certainty="unsure"), # suggestion budget spent → rejected+ ]+ ctx = _ctx(settings=wp.PolicySettings(max_direct_adds=2, max_suggestions=2))+ out = wp.apply_proposals(proposals, findings, ctx, db_path=db)+ assert [o["outcome"] for o in out] == [+ "added", "rejected", "added", "suggested", "suggested", "rejected",+ ]+ assert "duplicate" in out[1]["result_preview"]+ assert "budget" in out[5]["result_preview"]+++# --------------------------------------------------------------------- #+# Declines memory+# --------------------------------------------------------------------- #+++def test_explicit_decline_is_permanent_and_expiry_retries_after_90_days(db: Path) -> None:+ ms.insert_decline(normalized_target="https://initech.com/feed.xml",+ kind=DECLINE_KIND_EXPLICIT, reason="not_relevant", db_path=db)+ ms.insert_decline(normalized_target="https://globex.com/feed.xml",+ kind=DECLINE_KIND_EXPIRED, reason="expired", db_path=db)+ assert ms.is_declined("https://initech.com/feed.xml", db_path=db)+ assert ms.is_declined("https://globex.com/feed.xml", db_path=db)+ later = datetime.now(UTC) + timedelta(days=91)+ assert ms.is_declined("https://initech.com/feed.xml", now=later, db_path=db)+ assert not ms.is_declined("https://globex.com/feed.xml", now=later, db_path=db)+ # An expiry never downgrades an explicit decline.+ ms.insert_decline(normalized_target="https://initech.com/feed.xml",+ kind=DECLINE_KIND_EXPIRED, reason="expired", db_path=db)+ assert ms.list_declines(db_path=db)[-1].kind == DECLINE_KIND_EXPLICIT or any(+ d.normalized_target == "https://initech.com/feed.xml" and d.kind == DECLINE_KIND_EXPLICIT+ for d in ms.list_declines(db_path=db)+ )+++async def test_propose_handler_refuses_declined_target_under_new_slug(+ db: Path, monkeypatch: pytest.MonkeyPatch,+) -> None:+ from openexecutive.orchestrator import watchlist_tools as wt++ async def _passthrough(signal_type: str, target: str, config: dict) -> tuple[str, str, dict]:+ return signal_type, target, config++ monkeypatch.setattr(wt, "validate_and_normalize_target", _passthrough)+ ms.insert_decline(normalized_target="https://initech.com/feed.xml",+ kind=DECLINE_KIND_EXPLICIT, reason="not_relevant", db_path=db)+ collector: list[Any] = []+ out = await wt.handle_propose_watch({+ "slug": "rss-initech-again", "signal_type": "rss",+ "target": "HTTPS://initech.com/feed.xml/", "grounding_entity": "Initech",+ "rationale": "x", "certainty": "confident",+ }, collector)+ assert "declined" in out and collector == []+ ok = await wt.handle_propose_watch({+ "slug": "stock-acme", "signal_type": "stock", "target": "ACME",+ "grounding_entity": "Acme Corp", "rationale": "y", "certainty": "confident",+ "finding_index": 1,+ }, collector)+ assert '"queued": "stock-acme"' in ok and collector[0].finding_index == 0+++# --------------------------------------------------------------------- #+# Sweep+# --------------------------------------------------------------------- #+++def _backdate(db: Path, slug: str, days: int) -> None:+ import sqlite3++ with sqlite3.connect(db) as conn:+ conn.execute(+ "UPDATE watchlist SET created_at = ? WHERE slug = ?",+ ((datetime.now(UTC) - timedelta(days=days)).isoformat(), slug),+ )+++def test_sweep_expires_old_suggestions_as_unreviewed(db: Path) -> None:+ ms.insert_watchlist_item(+ slug="rss-old", signal_type="rss", target="https://old.com/feed", mode=MODE_DRY_RUN,+ origin=ORIGIN_RESEARCH_PROPOSED, db_path=db,+ )+ ms.insert_watchlist_item(+ slug="rss-new", signal_type="rss", target="https://new.com/feed", mode=MODE_DRY_RUN,+ origin=ORIGIN_RESEARCH_PROPOSED, db_path=db,+ )+ _backdate(db, "rss-old", 15)+ counts = wp.sweep(datetime.now(UTC), db_path=db)+ assert counts["expired"] == 1+ assert [w.slug for w in ms.list_pending_suggestions(db_path=db)] == ["rss-new"]+ decl = ms.list_declines(db_path=db)+ assert decl[0].normalized_target == "https://old.com/feed" and decl[0].kind == DECLINE_KIND_EXPIRED+++def test_sweep_expires_a_suggestion_that_already_recorded_signals(db: Path) -> None:+ """Dry-run suggestions poll and record signals; the FK on external_signals+ must not make them un-expirable."""+ from openexecutive.monitoring.models import Signal++ wid = ms.insert_watchlist_item(+ slug="rss-polled", signal_type="rss", target="https://polled.com/feed", mode=MODE_DRY_RUN,+ origin=ORIGIN_RESEARCH_PROPOSED, db_path=db,+ )+ ms.insert_signal(Signal(+ watchlist_id=wid, source_kind="rss", source_external_id="e1",+ captured_at=datetime.now(UTC).isoformat(), normalized_summary="s",+ provenance_url="https://polled.com/1", dedup_key="k1",+ ), db_path=db)+ _backdate(db, "rss-polled", 15)+ assert wp.sweep(datetime.now(UTC), db_path=db)["expired"] == 1+ assert ms.get_watchlist_item(wid, db_path=db) is None+ assert ms.list_signals_for_watchlist(wid, db_path=db) == []+++def test_sweep_auto_disables_noisy_and_dead_research_watches(db: Path) -> None:+ import sqlite3++ ms.insert_watchlist_item(slug="rss-noisy", signal_type="rss", target="https://noisy.com/feed",+ origin=ORIGIN_RESEARCH, db_path=db)+ ms.insert_watchlist_item(slug="rss-dead", signal_type="rss", target="https://dead.com/feed",+ origin=ORIGIN_RESEARCH, db_path=db)+ ms.insert_watchlist_item(slug="rss-mine", signal_type="rss", target="https://mine.com/feed",+ db_path=db) # manual: never auto-disabled+ with sqlite3.connect(db) as conn:+ conn.execute(+ "UPDATE watchlist SET fired_count = 6, dismiss_count = 3, trust_score = 0.4 "+ "WHERE slug IN ('rss-noisy', 'rss-mine')"+ )+ _backdate(db, "rss-dead", 31)+ _backdate(db, "rss-mine", 31)+ counts = wp.sweep(datetime.now(UTC), db_path=db)+ assert counts["disabled"] == 2+ enabled = {w.slug: w.enabled for w in ms.list_watchlist(db_path=db)}+ assert enabled == {"rss-noisy": False, "rss-dead": False, "rss-mine": True}+++def test_sweep_nudges_once_suggestions_pile_up(db: Path) -> None:+ from openexecutive.alerts.store import list_alerts++ for i in range(3):+ ms.insert_watchlist_item(+ slug=f"rss-s{i}", signal_type="rss", target=f"https://s{i}.com/feed",+ mode=MODE_DRY_RUN, origin=ORIGIN_RESEARCH_PROPOSED, db_path=db,+ )+ assert wp.sweep(datetime.now(UTC), db_path=db)["nudged"] == 0 # too fresh+ _backdate(db, "rss-s0", 8)+ assert wp.sweep(datetime.now(UTC), db_path=db)["nudged"] == 1+ assert wp.sweep(datetime.now(UTC), db_path=db)["nudged"] == 0 # coalesced+ alerts = [a for a in list_alerts(limit=10, db_path=db) if a.source == wp.NUDGE_ALERT_SOURCE]+ assert len(alerts) == 1 and "3 watch suggestions" in alerts[0].headlinediff --git a/packages/core/tests/unit/test_watchlist_routes.py b/packages/core/tests/unit/test_watchlist_routes.pynew file mode 100644index 00000000..308afb0d--- /dev/null+++ b/packages/core/tests/unit/test_watchlist_routes.py@@ -0,0 +1,148 @@+"""Watchlist HTTP routes: research suggestions (approve / decline), decline+memory on delete, and the origin field on responses."""+from __future__ import annotations++from pathlib import Path++import pytest+from fastapi import FastAPI+from fastapi.testclient import TestClient++from openexecutive.alerts import store as alert_store+from openexecutive.api.routes import watchlist as watchlist_route+from openexecutive.audit import AuditLogger, set_audit_logger+from openexecutive.memory import episodic+from openexecutive.monitoring import store as ms+++def db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ db_path = tmp_path / "watchlist.db"+ monkeypatch.setattr(alert_store, "DB_PATH", db_path)+ monkeypatch.setattr(episodic, "DB_PATH", db_path)+ alert_store.initialize_db(db_path)+ episodic.initialize_db(db_path)+ ms.initialize_db(db_path)+ audit = AuditLogger(db_path=db_path)+ audit.initialize_db()+ set_audit_logger(audit)+ return db_path+++def client(db: Path) -> TestClient:+ app = FastAPI()+ app.include_router(watchlist_route.router)+ return TestClient(app)+++def _suggest(db: Path, slug: str = "rss-initech", target: str = "https://initech.com/feed") -> int:+ return ms.insert_watchlist_item(+ slug=slug, signal_type="rss", target=target, mode="dry_run",+ origin="research_proposed", notes="Adjacent competitor blog",+ config={"_policy": {"entity": "Initech", "grounding_kind": "", "specialist": "cso"}},+ db_path=db,+ )+++def test_list_carries_origin(client: TestClient, db: Path) -> None:+ ms.insert_watchlist_item(slug="stock-aapl", signal_type="stock", target="AAPL", db_path=db)+ _suggest(db)+ rows = {r["slug"]: r for r in client.get("/watchlist").json()}+ assert rows["stock-aapl"]["origin"] == "manual"+ assert rows["rss-initech"]["origin"] == "research_proposed" and rows["rss-initech"]["mode"] == "dry_run"+++def test_approve_turns_suggestion_live_and_records_outcome(client: TestClient, db: Path) -> None:+ _suggest(db)+ res = client.post("/watchlist/rss-initech/approve")+ assert res.status_code == 200, res.text+ body = res.json()+ assert body["origin"] == "research" and body["mode"] == "active" and body["enabled"] is True+ assert ms.list_pending_suggestions(db_path=db) == []+ assert ms.policy_outcome_counts(db_path=db) == {("rss", ""): {"approved": 1}}+ assert ms.specialist_outcome_counts(db_path=db) == {"cso": {"approved": 1}}+ # Not a pending suggestion any more → 409; unknown → 404.+ assert client.post("/watchlist/rss-initech/approve").status_code == 409+ assert client.post("/watchlist/nope/approve").status_code == 404+++def test_approve_rejects_manual_rows(client: TestClient, db: Path) -> None:+ ms.insert_watchlist_item(slug="stock-aapl", signal_type="stock", target="AAPL", db_path=db)+ assert client.post("/watchlist/stock-aapl/approve").status_code == 409+++def test_decline_not_relevant_removes_and_remembers(client: TestClient, db: Path) -> None:+ _suggest(db)+ res = client.post("/watchlist/rss-initech/decline", json={"reason": "not_relevant"})+ assert res.status_code == 200, res.text+ assert res.json() == {"slug": "rss-initech", "reason": "not_relevant", "result": "removed"}+ assert ms.get_watchlist_item_by_slug("rss-initech", db_path=db) is None+ declines = ms.list_declines(db_path=db)+ assert declines[0].normalized_target == "https://initech.com/feed"+ assert declines[0].kind == "declined_explicit" and declines[0].entity == "Initech"+ assert ms.is_declined("https://initech.com/feed", db_path=db)+ assert ms.policy_outcome_counts(db_path=db) == {("rss", ""): {"declined": 1}}+++def test_decline_defaults_to_not_relevant_without_a_body(client: TestClient, db: Path) -> None:+ _suggest(db)+ res = client.post("/watchlist/rss-initech/decline")+ assert res.status_code == 200 and res.json()["reason"] == "not_relevant"+++def test_decline_too_noisy_keeps_it_live_at_a_high_floor(client: TestClient, db: Path) -> None:+ _suggest(db)+ res = client.post("/watchlist/rss-initech/decline", json={"reason": "too_noisy"})+ assert res.status_code == 200 and res.json()["result"] == "kept_quiet"+ row = ms.get_watchlist_item_by_slug("rss-initech", db_path=db)+ assert row is not None+ assert row.mode == "active" and row.origin == "research" and row.severity_floor.value == "high"+ assert ms.list_declines(db_path=db) == []+ assert ms.policy_outcome_counts(db_path=db) == {("rss", ""): {"approved": 1}}+++def test_decline_validates_reason_and_state(client: TestClient, db: Path) -> None:+ _suggest(db)+ assert client.post("/watchlist/rss-initech/decline", json={"reason": "meh"}).status_code == 400+ ms.insert_watchlist_item(slug="stock-aapl", signal_type="stock", target="AAPL", db_path=db)+ assert client.post("/watchlist/stock-aapl/decline", json={"reason": "not_relevant"}).status_code == 409+ assert client.post("/watchlist/nope/decline").status_code == 404+++def test_delete_research_row_records_decline_with_reason(client: TestClient, db: Path) -> None:+ ms.insert_watchlist_item(+ slug="stock-acme", signal_type="stock", target="acme", origin="research", db_path=db,+ )+ ms.insert_watchlist_item(slug="stock-mine", signal_type="stock", target="MINE", db_path=db)+ assert client.delete("/watchlist/stock-acme?reason=wrong_source").status_code == 204+ declines = ms.list_declines(db_path=db)+ assert [(d.normalized_target, d.reason) for d in declines] == [("ACME", "wrong_source")]+ assert client.delete("/watchlist/stock-mine").status_code == 204+ assert len(ms.list_declines(db_path=db)) == 1 # manual rows are not declines+ assert client.delete("/watchlist/stock-mine?reason=bogus").status_code == 404+++def test_delete_rejects_unknown_reason(client: TestClient, db: Path) -> None:+ ms.insert_watchlist_item(slug="stock-acme", signal_type="stock", target="ACME", origin="research", db_path=db)+ assert client.delete("/watchlist/stock-acme?reason=bogus").status_code == 400+ assert ms.get_watchlist_item_by_slug("stock-acme", db_path=db) is not None+++def test_delete_and_decline_work_after_the_watch_recorded_signals(client: TestClient, db: Path) -> None:+ from openexecutive.monitoring.models import Signal++ wid = ms.insert_watchlist_item(+ slug="stock-acme", signal_type="stock", target="ACME", origin="research", db_path=db,+ )+ sid = _suggest(db)+ for w, key in ((wid, "k1"), (sid, "k2")):+ ms.insert_signal(Signal(+ watchlist_id=w, source_kind="stock", source_external_id=key,+ captured_at="2026-09-12T00:00:00+00:00", normalized_summary="s",+ provenance_url="https://x/1", dedup_key=key,+ ), db_path=db)+ assert client.delete("/watchlist/stock-acme?reason=not_relevant").status_code == 204+ assert client.post("/watchlist/rss-initech/decline", json={"reason": "wrong_source"}).status_code == 200+ assert ms.list_watchlist(db_path=db) == []+ assert ms.list_signals_for_watchlist(wid, db_path=db) == []diff --git a/packages/core/tests/unit/test_watchlist_tools.py b/packages/core/tests/unit/test_watchlist_tools.pyindex d065c9c2..c7efaea5 100644--- a/packages/core/tests/unit/test_watchlist_tools.py+++ b/packages/core/tests/unit/test_watchlist_tools.py@@ -237,3 +237,34 @@ async def test_add_invokes_target_validation_and_surfaces_rejection(}))assert "error" in result and "not a feed" in result["error"]assert ms.get_watchlist_item_by_slug("rss-bad") is None+++# --------------------------------------------------------------------- #+# origin + declines memory+# --------------------------------------------------------------------- #+++async def test_add_stamps_executive_origin(db: Path) -> None:+ await wt.handle_add_watchlist_entry({+ "slug": "stock-aapl", "signal_type": "stock", "target": "AAPL",+ })+ row = ms.get_watchlist_item_by_slug("stock-aapl", db_path=db)+ assert row is not None and row.origin == "executive"+++async def test_remove_research_watch_records_decline(db: Path) -> None:+ ms.insert_watchlist_item(+ slug="rss-acme", signal_type="rss", target="https://Acme.com/feed/",+ origin="research", db_path=db,+ )+ ms.insert_watchlist_item(slug="stock-mine", signal_type="stock", target="MINE", db_path=db)+ out = json.loads(await wt.handle_remove_watchlist_entry({"slug": "rss-acme", "reason": "too_noisy"}))+ assert out["ok"] is True+ declines = ms.list_declines(db_path=db)+ assert [d.normalized_target for d in declines] == ["https://acme.com/feed"]+ assert declines[0].kind == "declined_explicit" and declines[0].reason == "too_noisy"+ # A manual row removed is not a decline.+ await wt.handle_remove_watchlist_entry({"slug": "stock-mine"})+ assert len(ms.list_declines(db_path=db)) == 1diff --git a/packages/ui/src/app/company-profile/page.tsx b/packages/ui/src/app/company-profile/page.tsxindex fd805315..ba4d2aa8 100644--- a/packages/ui/src/app/company-profile/page.tsx+++ b/packages/ui/src/app/company-profile/page.tsx@@ -52,7 +52,7 @@ const NUM_FIELDS = new Set([const LIST_FIELDS = new Set(["pain_points", "primary_competitors", "competitive_advantages","priorities", "culture_values", "operating_principles",- "departments", "leadership_team",+ "departments", "leadership_team", "vendors", "tickers",]);/** Flat snapshot of the SAVED profile — feeds both the Ask OE form@@ -71,6 +71,8 @@ function snapshotProfile(profile: CompanyProfile): Record<string, unknown> {pain_points: profile.target_customer.pain_points,primary_competitors: profile.competitive_landscape.primary_competitors,competitive_advantages: profile.competitive_landscape.competitive_advantages,+ vendors: profile.vendors ?? [],+ tickers: profile.tickers ?? [],priorities: profile.strategic_priorities.current_year,north_star_metric: profile.strategic_priorities.north_star_metric,culture_values: profile.culture.values,@@ -398,6 +400,9 @@ export default function CompanyProfilePage() {{/* Competitive Landscape */}<CompetitiveSection profile={profile} saving={saving} onSave={save} pending={pending} />+ {/* External Dependencies (vendors + tickers the research policy may watch on its own) */}+ <ExternalDependenciesSection profile={profile} saving={saving} onSave={save} pending={pending} />+{/* Strategic Priorities */}<PrioritiesSection profile={profile} saving={saving} onSave={save} pending={pending} />@@ -586,6 +591,47 @@ function CompetitiveSection({ profile, saving, onSave, pending }: SectionCompone);}+function ExternalDependenciesSection({ profile, saving, onSave, pending }: SectionComponentProps) {+ const [vendors, setVendors] = useState(listToText(profile.vendors ?? []));+ const [tickers, setTickers] = useState(listToText(profile.tickers ?? []));+ useEffect(() => {+ setVendors(listToText(profile.vendors ?? []));+ setTickers(listToText(profile.tickers ?? []));+ }, [profile]);++ const [editing, setEditing] = usePendingSection(pending, {+ vendors: (v) => setVendors(listToText(v as string[])),+ tickers: (v) => setTickers(listToText(v as string[])),+ });++ return (+ <Section+ title="External Dependencies"+ editing={editing}+ onEditingChange={setEditing}+ saving={saving}+ onSave={() => onSave({ vendors: textToList(vendors), tickers: textToList(tickers) })}+ viewContent={+ <div className="space-y-4">+ <p className="text-xs text-fg-subtle">+ Named here, a vendor or ticker counts as company data: the Executive+ will start watching its status page or filings on its own instead of+ asking you first.+ </p>+ <div><FieldLabel>Vendors & dependencies</FieldLabel><Pills items={profile.vendors ?? []} /></div>+ <div><FieldLabel>Tracked tickers</FieldLabel><Pills items={profile.tickers ?? []} /></div>+ </div>+ }+ editContent={+ <div className="space-y-3">+ <div><FieldLabel>Vendors (one per line)</FieldLabel><Textarea value={vendors} onChange={setVendors} rows={3} placeholder={"Stripe\nAWS"} /></div>+ <div><FieldLabel>Tickers (one per line — yours and competitors')</FieldLabel><Textarea value={tickers} onChange={setTickers} rows={3} placeholder={"CRM\nHUBS"} /></div>+ </div>+ }+ />+ );+}+function PrioritiesSection({ profile, saving, onSave, pending }: SectionComponentProps) {const [priorities, setPriorities] = useState(listToText(profile.strategic_priorities.current_year));const [northStar, setNorthStar] = useState(profile.strategic_priorities.north_star_metric);diff --git a/packages/ui/src/app/watchlist/page.tsx b/packages/ui/src/app/watchlist/page.tsxindex 7a781a57..e4e36adc 100644--- a/packages/ui/src/app/watchlist/page.tsx+++ b/packages/ui/src/app/watchlist/page.tsx@@ -4,15 +4,38 @@ import Link from "next/link";import { useEffect, useMemo, useRef, useState } from "react";import {+ approveWatchSuggestion,createWatchlistItem,+ declineWatchSuggestion,+ deleteWatchlistItem,listWatchlist,patchWatchlistItem,+ type WatchDeclineReason,type WatchlistCadence,type WatchlistItem,type WatchlistSeverity,type WatchlistSignalType,} from "@/lib/api";+// A research suggestion: the Executive wanted to watch this but was not sure+// enough to add it on its own. Sits in dry_run (polls, never alerts) until+// approved or declined here.+function isSuggestion(item: WatchlistItem): boolean {+ return item.origin === "research_proposed" && item.mode === "dry_run";+}++const DECLINE_REASONS: { value: WatchDeclineReason; label: string; hint: string }[] = [+ { value: "not_relevant", label: "Not relevant", hint: "Never suggest this company/topic again" },+ { value: "too_noisy", label: "Too noisy", hint: "Keep it, but only high-severity signals" },+ { value: "wrong_source", label: "Wrong source", hint: "Right topic, drop only this feed/page" },+];++// Rationale + provenance stamp the research policy left on the row.+function policyStamp(item: WatchlistItem): { entity?: string; score?: number; source_url?: string } {+ const raw = (item.config_json as Record<string, unknown> | undefined)?._policy;+ return raw && typeof raw === "object" ? (raw as { entity?: string; score?: number; source_url?: string }) : {};+}+const CADENCES: WatchlistCadence[] = ["real_time", "15min", "hourly", "daily", "weekly"];const SEVERITIES: WatchlistSeverity[] = ["low", "medium", "high", "urgent"];const SIGNAL_TYPES: { value: WatchlistSignalType; label: string; hint: string }[] = [@@ -79,15 +102,116 @@ function ModePill({ mode }: { mode: string }) {);}+function DeclineMenu({+ slug,+ busy,+ onPick,+ label,+}: {+ slug: string;+ busy: boolean;+ onPick: (slug: string, reason: WatchDeclineReason) => void;+ label: string;+}) {+ const [open, setOpen] = useState(false);+ return (+ <div className="relative">+ <button+ type="button"+ disabled={busy}+ onClick={() => setOpen((o) => !o)}+ className="px-3 py-1.5 text-xs rounded-lg border border-line hover:bg-surface-overlay disabled:opacity-50"+ >+ {label}+ </button>+ {open && (+ <div className="absolute right-0 z-20 mt-1 w-56 rounded-lg border border-line bg-surface-elevated shadow-lg p-1">+ {DECLINE_REASONS.map((r) => (+ <button+ key={r.value}+ type="button"+ onClick={() => {+ setOpen(false);+ onPick(slug, r.value);+ }}+ className="w-full text-left px-2 py-1.5 rounded hover:bg-surface-overlay"+ >+ <div className="text-xs text-fg">{r.label}</div>+ <div className="text-[10px] text-fg-subtle">{r.hint}</div>+ </button>+ ))}+ </div>+ )}+ </div>+ );+}++function SuggestionCard({+ item,+ busy,+ onApprove,+ onDecline,+}: {+ item: WatchlistItem;+ busy: boolean;+ onApprove: (slug: string) => void;+ onDecline: (slug: string, reason: WatchDeclineReason) => void;+}) {+ const stamp = policyStamp(item);+ return (+ <div className="rounded-xl border border-amber-500/30 bg-amber-500/5 p-4">+ <div className="flex items-start justify-between gap-2 mb-1">+ <div className="min-w-0">+ <div className="text-sm font-semibold text-fg truncate" title={item.slug}>+ {humanizeSlug(item.slug)}+ </div>+ <div className="text-xs text-fg-muted truncate" title={item.target}>+ {item.signal_type} · {item.target}+ </div>+ </div>+ <span className="flex-shrink-0 inline-block px-1.5 py-0.5 rounded border text-[10px] font-medium bg-amber-500/20 text-amber-200 border-amber-500/30">+ suggested+ </span>+ </div>+ {item.notes && <p className="text-xs text-fg mt-2">{item.notes}</p>}+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-[11px] text-fg-muted mt-2">+ {stamp.entity && <span>about: {stamp.entity}</span>}+ <span>suggested {formatRelTime(item.created_at)} ago</span>+ <span>seen in shadow: {item.fired_count} signal{item.fired_count === 1 ? "" : "s"}</span>+ {stamp.source_url && (+ <a href={stamp.source_url} target="_blank" rel="noreferrer" className="text-indigo-300 hover:text-indigo-200">+ source ↗+ </a>+ )}+ </div>+ <div className="flex items-center justify-end gap-2 mt-3 pt-2 border-t border-line">+ <DeclineMenu slug={item.slug} busy={busy} onPick={onDecline} label="Decline…" />+ <button+ type="button"+ disabled={busy}+ onClick={() => onApprove(item.slug)}+ className="px-3 py-1.5 text-xs rounded-lg bg-indigo-600 hover:bg-indigo-500 text-white font-medium disabled:opacity-50"+ >+ {busy ? "…" : "Approve"}+ </button>+ </div>+ </div>+ );+}+function WatchCard({item,onToggle,toggleBusy,+ onStopWatching,}: {item: WatchlistItem;onToggle: (slug: string, enabled: boolean) => void;toggleBusy: boolean;+ onStopWatching?: (slug: string, reason: WatchDeclineReason) => void;}) {+ const isResearch = item.origin === "research";+ const stamp = policyStamp(item);return (<div className="rounded-xl border border-line bg-surface-elevated hover:bg-surface-overlay transition-colors p-4 group"><div className="flex items-start justify-between gap-2 mb-2">@@ -106,10 +230,18 @@ function WatchCard({<ModePill mode={item.mode} /></div></div>+ {isResearch && (+ <p className="text-[11px] text-fg-muted mb-2">+ <span className="text-indigo-300">Added by the Executive</span>+ {stamp.entity ? ` · about ${stamp.entity}` : ""}+ {item.notes ? ` · ${item.notes}` : ""}+ </p>+ )}<div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-[11px] text-fg-muted mb-2"><span>cadence: {item.cadence}</span><span>severity: {item.severity_floor}→{item.severity_ceiling}</span><span>fired: {item.fired_count}</span>+ {item.dismiss_count > 0 && <span>dismissed: {item.dismiss_count}</span>}<span>last: {formatRelTime(item.last_fired_at)}</span></div><div className="flex items-center justify-between gap-2 pt-2 border-t border-line">@@ -123,12 +255,17 @@ function WatchCard({/>enabled</label>- <Link- href={`/watchlist/${encodeURIComponent(item.slug)}`}- className="text-xs text-indigo-300 hover:text-indigo-200"- >- inspect →- </Link>+ <div className="flex items-center gap-2">+ {isResearch && onStopWatching && (+ <DeclineMenu slug={item.slug} busy={toggleBusy} onPick={onStopWatching} label="Stop watching…" />+ )}+ <Link+ href={`/watchlist/${encodeURIComponent(item.slug)}`}+ className="text-xs text-indigo-300 hover:text-indigo-200"+ >+ inspect →+ </Link>+ </div></div></div>);@@ -372,9 +509,12 @@ export default function WatchlistPage() {// Group monitors by signal type, mirroring the artifacts/runs collapsible// groups. Known types render in SIGNAL_TYPES order; any unknown type sorts// last (alphabetically) so a new backend adapter never silently vanishes.+ const suggestions = useMemo(() => items.filter(isSuggestion), [items]);+const groups = useMemo(() => {const map = new Map<string, WatchlistItem[]>();for (const it of items) {+ if (isSuggestion(it)) continue;const bucket = map.get(it.signal_type);if (bucket) bucket.push(it);else map.set(it.signal_type, [it]);@@ -406,6 +546,55 @@ export default function WatchlistPage() {refresh();}, []);+ function markBusy(slug: string, busy: boolean) {+ setBusySlugs((prev) => {+ const next = new Set(prev);+ if (busy) next.add(slug);+ else next.delete(slug);+ return next;+ });+ }++ async function approve(slug: string) {+ markBusy(slug, true);+ try {+ const updated = await approveWatchSuggestion(slug);+ setItems((prev) => prev.map((it) => (it.slug === slug ? updated : it)));+ } catch (e) {+ setError(e instanceof Error ? e.message : "Approve failed");+ } finally {+ markBusy(slug, false);+ }+ }++ async function decline(slug: string, reason: WatchDeclineReason) {+ markBusy(slug, true);+ try {+ const res = await declineWatchSuggestion(slug, reason);+ if (res.result === "kept_quiet") {+ refresh();+ } else {+ setItems((prev) => prev.filter((it) => it.slug !== slug));+ }+ } catch (e) {+ setError(e instanceof Error ? e.message : "Decline failed");+ } finally {+ markBusy(slug, false);+ }+ }++ async function stopWatching(slug: string, reason: WatchDeclineReason) {+ markBusy(slug, true);+ try {+ await deleteWatchlistItem(slug, reason);+ setItems((prev) => prev.filter((it) => it.slug !== slug));+ } catch (e) {+ setError(e instanceof Error ? e.message : "Remove failed");+ } finally {+ markBusy(slug, false);+ }+ }+async function toggle(slug: string, enabled: boolean) {// Optimistic. The disabled prop on the input prevents a second// click landing while the PATCH is in flight, so the revert path@@ -484,6 +673,33 @@ export default function WatchlistPage() {</div>)}+ {suggestions.length > 0 && (+ <div className="mb-8">+ <div className="flex items-baseline gap-2 mb-1">+ <span className="text-sm font-semibold text-fg">Suggested by the Executive</span>+ <span className="text-xs text-fg-muted">+ {suggestions.length} waiting for you+ </span>+ </div>+ <p className="text-xs text-fg-subtle mb-3">+ Sources the research council thought worth monitoring but couldn't tie+ firmly enough to your company data to add on its own. They poll in+ shadow mode and never alert until you approve. Declines are remembered.+ </p>+ <div className="grid grid-cols-1 md:grid-cols-2 gap-4">+ {suggestions.map((item) => (+ <SuggestionCard+ key={item.id}+ item={item}+ busy={busySlugs.has(item.slug)}+ onApprove={approve}+ onDecline={decline}+ />+ ))}+ </div>+ </div>+ )}+<div className="space-y-6">{groups.map((group) => {const isCollapsed = !!collapsed[group.key];@@ -517,6 +733,7 @@ export default function WatchlistPage() {item={item}onToggle={toggle}toggleBusy={busySlugs.has(item.slug)}+ onStopWatching={stopWatching}/>))}</div>diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.tsindex 5fdc423f..672da5a2 100644--- a/packages/ui/src/lib/api.ts+++ b/packages/ui/src/lib/api.ts@@ -224,6 +224,9 @@ export interface CompanyProfile {strategic_priorities: { current_year: string[]; north_star_metric: string };culture: { values: string[]; operating_principles: string[] };financials: { burn_rate_monthly: number | null; runway_months: number | null; key_metrics: Record<string, unknown> };+ /** External dependencies the research watch policy treats as company data. */+ vendors: string[];+ tickers: string[];}export async function getCompanyProfile(): Promise<CompanyProfile> {@@ -2741,6 +2744,10 @@ export type WatchlistSignalType =export type WatchlistCadence = "real_time" | "15min" | "hourly" | "daily" | "weekly";export type WatchlistMode = "active" | "dry_run";export type WatchlistSeverity = "low" | "medium" | "high" | "urgent";+/** Who put the row on the watchlist. `research_proposed` = a pending suggestion. */+export type WatchlistOrigin = "manual" | "executive" | "research" | "research_proposed";+/** Why a research suggestion / watch was declined — each picks a different remedy. */+export type WatchDeclineReason = "not_relevant" | "too_noisy" | "wrong_source";export interface WatchlistItem {id: number;@@ -2764,6 +2771,7 @@ export interface WatchlistItem {dismiss_count: number;trust_score: number;notes: string;+ origin: WatchlistOrigin | string;}export interface WatchlistSignal {@@ -2868,13 +2876,53 @@ export async function patchWatchlistItem(return res.json();}-export async function deleteWatchlistItem(slug: string): Promise<void> {- const res = await fetch(`${API_BASE}/watchlist/${encodeURIComponent(slug)}`, {+export async function deleteWatchlistItem(+ slug: string,+ reason?: WatchDeclineReason,+): Promise<void> {+ const qs = reason ? `?reason=${encodeURIComponent(reason)}` : "";+ const res = await fetch(`${API_BASE}/watchlist/${encodeURIComponent(slug)}${qs}`, {method: "DELETE",});if (!res.ok) throw new Error(`Failed to delete watchlist entry: ${res.statusText}`);}+/** Turn a research suggestion (origin=research_proposed, dry_run) into a live watch. */+export async function approveWatchSuggestion(slug: string): Promise<WatchlistItem> {+ const res = await fetch(`${API_BASE}/watchlist/${encodeURIComponent(slug)}/approve`, {+ method: "POST",+ });+ if (!res.ok) {+ const text = await res.text().catch(() => "");+ throw new Error(`Failed to approve suggestion: ${res.statusText}${text ? ` — ${text}` : ""}`);+ }+ return res.json();+}++export interface WatchDeclineResponse {+ slug: string;+ reason: string;+ /** "removed" (declined + deleted) or "kept_quiet" (too_noisy → live with a high floor). */+ result: "removed" | "kept_quiet" | string;+}++/** Decline a research suggestion. The reason picks the remedy server-side. */+export async function declineWatchSuggestion(+ slug: string,+ reason: WatchDeclineReason,+): Promise<WatchDeclineResponse> {+ const res = await fetch(`${API_BASE}/watchlist/${encodeURIComponent(slug)}/decline`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({ reason }),+ });+ if (!res.ok) {+ const text = await res.text().catch(() => "");+ throw new Error(`Failed to decline suggestion: ${res.statusText}${text ? ` — ${text}` : ""}`);+ }+ return res.json();+}+// ---------------------------------------------------------------------------// Decisions / Trust Ledger (first-climb autonomy)// ---------------------------------------------------------------------------