AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
feat(attunement): learn which proactive outreach lands per person
Rufusd09a31265f43
diff --git a/.env.example b/.env.exampleindex 1d7f83e8..c97843c1 100644--- a/.env.example+++ b/.env.example@@ -327,6 +327,12 @@ NUDGE_MAX_PER_SCOPE=3# ATTUNEMENT_LOOP_TTL_DAYS=21# ATTUNEMENT_MAX_OPEN_LOOPS_PER_PERSON=15# ATTUNEMENT_MAX_CALLS_PER_DAY=200+# Outcome ledger: proactive DMs are resolved replied / acted, or ignored after+# ATTUNEMENT_IGNORE_AFTER_HOURS. A person whose last MUTE_MIN_SENDS resolved+# sends from a nudge source all went unanswered is chased less for it.+# ATTUNEMENT_IGNORE_AFTER_HOURS=72+# ATTUNEMENT_MUTE_MIN_SENDS=5+# ATTUNEMENT_MUTE_COOLDOWN_MULTIPLIER=3# Research council cadence: the periodic run is considered every# WATCHLIST_RESEARCH_INTERVAL_MINUTES and skipped when nothing changed.WATCHLIST_RESEARCH_INTERVAL_MINUTES=360diff --git a/packages/core/openexecutive/alerts/lifecycle.py b/packages/core/openexecutive/alerts/lifecycle.pyindex d3c1924a..2015e3cd 100644--- a/packages/core/openexecutive/alerts/lifecycle.py+++ b/packages/core/openexecutive/alerts/lifecycle.py@@ -243,6 +243,33 @@ def mute_pattern_for(alert: Alert) -> str | None:return tags[0] if tags else None+def resolve_alert_outreach(alert: Alert, status: str) -> None:+ """Resolve the Attunement outcome rows for review DMs about ``alert``.++ Acknowledged or resolved: the DMs to the person it is routed to (and to+ the principal, who is escalated to) landed. Dismissed or stale: the alert+ didn't matter, so those DMs are voided — counted neither way. Never+ attributes an outcome to anyone else the alert was once DM'd to, and a+ dismissal can never lower anyone's rate. Never raises."""+ if alert.id is None:+ return+ try:+ from openexecutive.attunement.outcomes import OUTCOME_ACTED, OUTCOME_VOID, resolve_by_ref+ from openexecutive.people.store import find_principal_person++ ref = f"alert:{alert.id}"+ if status in ("ack", "resolved"):+ owners = {pid for pid in (getattr(alert, "routed_to_person_id", None),) if pid}+ principal = find_principal_person()+ if principal is not None and principal.id is not None:+ owners.add(principal.id)+ resolve_by_ref(ref, OUTCOME_ACTED, person_ids=owners)+ elif status in ("dismissed", "stale", "expired"):+ resolve_by_ref(ref, OUTCOME_VOID)+ except Exception:+ logger.debug("resolve_alert_outreach failed", exc_info=True)++def record_ack_feedback(alert: Alert, status: str) -> None:"""Teach the source of an alert from the principal's verdict.@@ -252,6 +279,8 @@ def record_ack_feedback(alert: Alert, status: str) -> None:"""from openexecutive.briefing.ranking import watch_slug_from_tags+ resolve_alert_outreach(alert, status)+slug = watch_slug_from_tags(list(alert.topic_tags or []))if slug is None:returndiff --git a/packages/core/openexecutive/alerts/review.py b/packages/core/openexecutive/alerts/review.pyindex 6c394b0c..3dc25cd4 100644--- a/packages/core/openexecutive/alerts/review.py+++ b/packages/core/openexecutive/alerts/review.py@@ -510,17 +510,24 @@ def _dm_text(headline: str, text: str) -> str:return f"[Alert review] Re: {_untrusted(headline, 120)}\n\n{body}"-async def _dm(person_id: int, text: str, *, headline: str = "") -> tuple[bool, str]:+async def _dm(+ person_id: int, text: str, *, headline: str = "", alert_id: int | None = None+) -> tuple[bool, str]:"""DM a rostered person through the real handler (server-side channel- resolution + the outbound anti-spam guard). Returns (ok, detail)."""+ resolution + the outbound anti-spam guard). Returns (ok, detail).++ Tagged as alert-review outreach about ``alert_id``, so acknowledging or+ dismissing that alert later resolves whether the DM landed."""import json+ from openexecutive.attunement.outcomes import SOURCE_ALERT_REVIEW, tag_proactivefrom openexecutive.orchestrator.schedule_tools import handle_message_persontry:- raw = await handle_message_person({- "person_id": person_id, "text": _dm_text(headline, text),- })+ with tag_proactive(SOURCE_ALERT_REVIEW, f"alert:{alert_id}" if alert_id else ""):+ raw = await handle_message_person({+ "person_id": person_id, "text": _dm_text(headline, text),+ })parsed = json.loads(raw)except Exception as exc:return False, f"dm failed: {exc}"@@ -600,6 +607,11 @@ def _close_or_annotate(ctx: _MoveContext) -> str:if strong:new_status = lifecycle.RESOLVED_STATUS if v.verdict == "resolved" else "dismissed"alert_store.set_status(ctx.alert_id, new_status, db_path=ctx.db_path)+ # The review's own earlier DMs about this alert: resolved means they+ # landed; stale means they didn't matter (voided, never "ignored").+ lifecycle.resolve_alert_outreach(+ alert, "resolved" if new_status == lifecycle.RESOLVED_STATUS else "stale"+ )alert_store.set_review(ctx.alert_id, verdict=v.verdict, note=ctx.note, recommended_move="close",why_now="", due_at=None, reviewed_at=ctx.now.isoformat(), db_path=ctx.db_path,@@ -727,6 +739,7 @@ async def _apply_route(ctx: _MoveContext) -> None:alert_store.update_alert_routing(ctx.alert_id, target, db_path=ctx.db_path)ok, detail = await _dm(target, v.message or f"Can you own this? {alert.headline}", headline=alert.headline,+ alert_id=ctx.alert_id,)ctx.summary.moves_used += 1if ok:@@ -754,6 +767,7 @@ async def _apply_nudge(ctx: _MoveContext) -> None:returnok, detail = await _dm(target, v.message or f"Checking in on: {alert.headline}", headline=alert.headline,+ alert_id=ctx.alert_id,)ctx.summary.moves_used += 1if ok:@@ -781,6 +795,7 @@ async def _apply_escalate(ctx: _MoveContext) -> None:ctx.principal_id,v.message or f"Needs you today: {alert.headline}\n{v.why_now or ''}".strip(),headline=alert.headline,+ alert_id=ctx.alert_id,)ctx.summary.moves_used += 1if not ok:diff --git a/packages/core/openexecutive/api/routes/people.py b/packages/core/openexecutive/api/routes/people.pyindex e736af9d..aa73cc7a 100644--- a/packages/core/openexecutive/api/routes/people.py+++ b/packages/core/openexecutive/api/routes/people.py@@ -230,3 +230,37 @@ def close_open_loop_route(loop_id: int, body: OpenLoopClose, request: Request) -caller = _require_principal_or(loop.owner_person_id, request)close_open_loop(loop_id, reason=body.reason, closed_by_person_id=caller)return Response(status_code=status.HTTP_204_NO_CONTENT)+++class OutreachStat(BaseModel):+ source: str+ label: str+ sent: int+ replied: int+ acted: int+ ignored: int+ pending: int++[email protected]("/people/{person_id}/outreach", response_model=list[OutreachStat])+def get_person_outreach(person_id: int, request: Request) -> list[OutreachStat]:+ """How this person responded to proactive outreach over the last 30 days,+ per kind of outreach. The principal or that person only."""+ from openexecutive.attunement import outcomes++ # Authorize first, so a non-principal can't probe which ids exist.+ _require_principal_or(person_id, request)+ if people_store.get_person(person_id) is None:+ raise HTTPException(status_code=404, detail="Person not found")+ rows: list[OutreachStat] = []+ for (_, source), s in sorted(outcomes.acceptance(person_id=person_id).items()):+ rows.append(OutreachStat(+ source=source,+ label=outcomes.SOURCE_LABELS.get(source, source),+ sent=s.sent,+ replied=s.counts.get(outcomes.OUTCOME_REPLIED, 0),+ acted=s.counts.get(outcomes.OUTCOME_ACTED, 0),+ ignored=s.counts.get(outcomes.OUTCOME_IGNORED, 0),+ pending=s.pending,+ ))+ return rowsdiff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex f63c5f0a..f123e4ec 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -1562,6 +1562,48 @@ attunement:tests/conftest.py no-ops `schedule_open_loop_pass` for every test soExecutive turns don't call a provider or write default-DB rows; testsof the pass call `run_open_loop_pass` directly.+ outcomes:+ module: openexecutive.attunement.outcomes+ why: |+ Nothing measured whether proactive outreach landed, so an always-ignored+ nudge kept going and an always-answered one ranked no higher.+ recording: |+ `tag_proactive(source, ref)` ContextVar (wrap non-yielding code only —+ never across an async-generator yield). `_record_outbound_context`+ (schedule_tools) calls `record_send` after inserting the linkage: a row+ only when tagged AND the recipient resolves to a Person. Tagged: runner+ generic dispatch via `_outreach_source` (proactive_nudge → nudge_stalled /+ nudge_commitment / nudge_initiative / open_loop [commitment target is an+ open_loop], ref = scope_key; else followup, ref action:<id>); reflection+ and research around their tool execution; alert review `_dm(alert_id=)`+ → alert_review, ref alert:<id>. Untracked: briefs and dynamic-workflow+ deliveries (no session → no linkage), broadcasts (no single recipient),+ web-chat sends (no linkage by design).+ resolution: |+ replied — `mark_outbound_context_consumed`. acted — close_open_loop with+ reason reported_done, or done closed by the owner themselves (principal+ tidy-up credits nobody); `resumer.apply_resolution` resolves+ nudge:stalled:<run_id>; store_initiative/update_initiative on an existing+ initiative resolves nudge:initiative:<id>; alert ack or resolved+ (`alerts.lifecycle.resolve_alert_outreach`, also called by alert review+ when it closes an alert) — scoped to routed_to_person_id + principal.+ void — alert dismissed / stale: excluded from every rate, so a dismissal+ (POST /alerts/{id}/ack has no per-caller authz, pre-existing) can never+ push someone toward demotion. ignored — `sweep_ignored` at the start of+ each nudge scan AND lazily in acceptance()/muted_pairs() (rates stay+ honest with NUDGE_SCAN_ENABLED=false). Only rows still open are touched.+ Recording skips email cc's (only the first `to` address) and principal+ self follow-ups.+ use: |+ `acceptance()` per (person, source), 30 days, voids excluded.+ nudge_engine `_apply_outcome_feedback` uses `muted_pairs(min_sends)`:+ demoted when the person's LAST ATTUNEMENT_MUTE_MIN_SENDS (5) resolved+ sends of that source were all unanswered → cooldown x+ MUTE_COOLDOWN_MULTIPLIER (3), ranked last in `_apply_caps`; never+ dropped; one answer lifts it (a 30-day share would not — review+ finding). Reflection WHAT LANDS block (sources with >=3 resolved).+ GET /people/{id}/outreach (auth before 404) → "How they respond" card.+ table: proactive_outcomes (episodic DB); wiped by slots + reset_all_state.departments:module: openexecutive.departmentsdiff --git a/packages/core/openexecutive/architecture/prebuilt/agents.json b/packages/core/openexecutive/architecture/prebuilt/agents.jsonindex 63b1d630..06aa11bf 100644--- a/packages/core/openexecutive/architecture/prebuilt/agents.json+++ b/packages/core/openexecutive/architecture/prebuilt/agents.json@@ -1,7 +1,7 @@{"section_id": "agents","title": "Agent Council",- "markdown": "The Executive (`openexecutive.orchestrator.executive.Executive`) is a single coherent persona that fans out to specialist sub-agents via Anthropic tool use. Each specialist subclasses `openexecutive.agents.base.BaseAgent`, carrying a `name`, `domain`, and `model`, and exposes `analyze(...)`, which wraps the question in user-turn context and calls Claude through the per-call provider.\n\nRouting uses one `consult_specialist` tool. Beside it the Executive carries its skill tools; Attunement adds `list_open_loops` (what a person owes — everyone's for the principal only in a private conversation, otherwise the caller's own) and `close_open_loop`, which only closes a loop when the turn's resolved speaker is the principal or the loop's owner — an unrostered sender, a signed-in web user not on the roster, and unattended sessions are refused. Multiple parallel `tool_use` blocks in a single assistant turn fan out concurrently through `router.route_parallel`, each running its own domain-filtered ChromaDB query before the specialist sees the question. The Executive then synthesizes the returned analyses into one reply.\n\nThe nine entries in `SPECIALIST_REGISTRY` (`openexecutive.orchestrator.router`):\n\n| Key | Agent | Domain |\n| --- | --- | --- |\n| `cso` | `StrategyAgent` | strategy |\n| `cfo` | `FinanceAgent` | finance |\n| `chro` | `HRAgent` | hr |\n| `gc` | `LegalAgent` | legal |\n| `coo` | `OperationsAgent` | operations |\n| `cmo` | `MarketingAgent` | marketing |\n| `cpo` | `ProductAgent` | product |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5`; a deep-reasoning tier uses `claude-opus-5` (adaptive thinking); routing/fast classification uses `claude-haiku-4-5`. The Council's **Deep reasoning** toggle is honoured on Claude Opus/Sonnet (direct or via OpenRouter) and on any OpenRouter model whose live catalog entry supports `reasoning` (today all OpenAI, Gemini, DeepSeek and Grok entries; not Llama) — the request translator turns Anthropic adaptive thinking + effort into OpenRouter's `reasoning` parameter. It is a silent no-op on models that can't reason, and disabled for Haiku, which rejects adaptive thinking. With `OPENROUTER_ENABLED`, the Council dropdown's non-Anthropic entries come from OpenRouter's live `/models` catalog (fetched at startup, refreshed in the background, filtered to tool-capable paid text models from an allowlisted vendor set), falling back to a built-in snapshot if the fetch fails. Six Council-only agents are model/prompt-overridable in the UI but NOT callable via `consult_specialist`, because they are deliberately kept out of `SPECIALIST_REGISTRY`: `quality_judge` (committee review), `utility_fast` (gates, titles, decision parsing), `research` (the `executive_research` fan-out), `fixture_generator` (invents demo companies), `engagement_intake` (models a real client from intake material), and `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments). The last three share one shape — a forced tool call producing a whole company, validated for referential integrity, with a single repair retry — but opposite epistemics: the fixture author invents, the other two extract and leave unstated facts empty rather than guessing.\n\nOne more structured-output utility agent sits beside `triage`: `openexecutive.agents.alert_review.AlertReviewAgent` (routing model, one forced `emit_alert_reviews` tool call, never raises). The alert review job hands it a batch of open alerts with evidence and gets back, per alert, a verdict (relevant / changed / resolved / stale), a confidence, the evidence it relied on, a one-line note, why-now, an optional deadline, and a recommended move (none / route / nudge / escalate / draft / suggest_workflow / merge / close) with its parameters. Like `triage`, it never mutates state — `alerts.review.apply_verdict` executes the verdicts deterministically within authority, so the model's job is judgment, not action.\n\nEvery specialist *advises* — each returns domain analysis the Executive synthesizes into one voice. None of them act on the company's behalf; the side-effecting tools in the main loop (schedule, people, departments, broadcast, watchlist, workflows) belong to the Executive, not to a specialist.\n\nThe Executive can also launch *any* workflow conversationally: `orchestrator.workflow_run_tools` adds `list_workflows` (the launchable catalog with each workflow's inputs) and `run_workflow` (runs a built-in or custom workflow to completion and returns its artifact, checkpointing approval gates as `awaiting_human`). This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nThe Executive also backs the **Ask OE** panel's form-fill tier via `orchestrator.form_tools.propose_form_values`: when a chat turn arrives with a `<page_context>` block describing a form on the user's screen, the Executive can propose values for it. The proposal is delivered to the UI as a `form_patch` SSE event and placed into the form as highlighted suggestions — the tool never saves or submits anything; the user reviews and saves manually. The tool is **always** in the tool list (tool definitions sit at the top of the cached prompt prefix, so a conditionally-present tool would invalidate the prompt cache whenever panel and non-panel turns alternate); its description restricts usage to turns that carry a form descriptor.",+ "markdown": "The Executive (`openexecutive.orchestrator.executive.Executive`) is a single coherent persona that fans out to specialist sub-agents via Anthropic tool use. Each specialist subclasses `openexecutive.agents.base.BaseAgent`, carrying a `name`, `domain`, and `model`, and exposes `analyze(...)`, which wraps the question in user-turn context and calls Claude through the per-call provider.\n\nRouting uses one `consult_specialist` tool. Beside it the Executive carries its skill tools; Tool calls made while proactive work is tagged (scheduler dispatch, reflection, research, alert review) feed the Attunement outcome ledger. Attunement adds `list_open_loops` (what a person owes — everyone's for the principal only in a private conversation, otherwise the caller's own) and `close_open_loop`, which only closes a loop when the turn's resolved speaker is the principal or the loop's owner — an unrostered sender, a signed-in web user not on the roster, and unattended sessions are refused. Multiple parallel `tool_use` blocks in a single assistant turn fan out concurrently through `router.route_parallel`, each running its own domain-filtered ChromaDB query before the specialist sees the question. The Executive then synthesizes the returned analyses into one reply.\n\nThe nine entries in `SPECIALIST_REGISTRY` (`openexecutive.orchestrator.router`):\n\n| Key | Agent | Domain |\n| --- | --- | --- |\n| `cso` | `StrategyAgent` | strategy |\n| `cfo` | `FinanceAgent` | finance |\n| `chro` | `HRAgent` | hr |\n| `gc` | `LegalAgent` | legal |\n| `coo` | `OperationsAgent` | operations |\n| `cmo` | `MarketingAgent` | marketing |\n| `cpo` | `ProductAgent` | product |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5`; a deep-reasoning tier uses `claude-opus-5` (adaptive thinking); routing/fast classification uses `claude-haiku-4-5`. The Council's **Deep reasoning** toggle is honoured on Claude Opus/Sonnet (direct or via OpenRouter) and on any OpenRouter model whose live catalog entry supports `reasoning` (today all OpenAI, Gemini, DeepSeek and Grok entries; not Llama) — the request translator turns Anthropic adaptive thinking + effort into OpenRouter's `reasoning` parameter. It is a silent no-op on models that can't reason, and disabled for Haiku, which rejects adaptive thinking. With `OPENROUTER_ENABLED`, the Council dropdown's non-Anthropic entries come from OpenRouter's live `/models` catalog (fetched at startup, refreshed in the background, filtered to tool-capable paid text models from an allowlisted vendor set), falling back to a built-in snapshot if the fetch fails. Six Council-only agents are model/prompt-overridable in the UI but NOT callable via `consult_specialist`, because they are deliberately kept out of `SPECIALIST_REGISTRY`: `quality_judge` (committee review), `utility_fast` (gates, titles, decision parsing), `research` (the `executive_research` fan-out), `fixture_generator` (invents demo companies), `engagement_intake` (models a real client from intake material), and `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments). The last three share one shape — a forced tool call producing a whole company, validated for referential integrity, with a single repair retry — but opposite epistemics: the fixture author invents, the other two extract and leave unstated facts empty rather than guessing.\n\nOne more structured-output utility agent sits beside `triage`: `openexecutive.agents.alert_review.AlertReviewAgent` (routing model, one forced `emit_alert_reviews` tool call, never raises). The alert review job hands it a batch of open alerts with evidence and gets back, per alert, a verdict (relevant / changed / resolved / stale), a confidence, the evidence it relied on, a one-line note, why-now, an optional deadline, and a recommended move (none / route / nudge / escalate / draft / suggest_workflow / merge / close) with its parameters. Like `triage`, it never mutates state — `alerts.review.apply_verdict` executes the verdicts deterministically within authority, so the model's job is judgment, not action.\n\nEvery specialist *advises* — each returns domain analysis the Executive synthesizes into one voice. None of them act on the company's behalf; the side-effecting tools in the main loop (schedule, people, departments, broadcast, watchlist, workflows) belong to the Executive, not to a specialist.\n\nThe Executive can also launch *any* workflow conversationally: `orchestrator.workflow_run_tools` adds `list_workflows` (the launchable catalog with each workflow's inputs) and `run_workflow` (runs a built-in or custom workflow to completion and returns its artifact, checkpointing approval gates as `awaiting_human`). This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nThe Executive also backs the **Ask OE** panel's form-fill tier via `orchestrator.form_tools.propose_form_values`: when a chat turn arrives with a `<page_context>` block describing a form on the user's screen, the Executive can propose values for it. The proposal is delivered to the UI as a `form_patch` SSE event and placed into the form as highlighted suggestions — the tool never saves or submits anything; the user reviews and saves manually. The tool is **always** in the tool list (tool definitions sit at the top of the cached prompt prefix, so a conditionally-present tool would invalidate the prompt cache whenever panel and non-panel turns alternate); its description restricts usage to turns that carry a form descriptor.","mermaid": "flowchart TD\n User([User message]) --> Exec[\"Executive<br/>orchestrator\"]\n Exec -->|consult_specialist| Cso[\"cso: StrategyAgent\"]\n Exec -->|consult_specialist| Cfo[\"cfo: FinanceAgent\"]\n Exec -->|consult_specialist| Gc[\"gc: LegalAgent\"]\n Exec -->|consult_specialist| More[\"chro / coo / cmo / cpo<br/>board_comms / triage\"]\n Cso --> Claude[\"Claude (Anthropic)\"]\n Cfo --> Claude\n Gc --> Claude\n More --> Claude\n Claude --> Exec\n class User entry\n class Exec compute\n class Cso compute\n class Cfo compute\n class Gc compute\n class More compute\n class Claude external",- "generated_at": "2026-09-22T22:44:51.279191+00:00"+ "generated_at": "2026-09-22T23:07:13.054261+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.jsonindex 70e87d0f..c2727418 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`, `POST /chat/stop` | 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. Each round of tool calls also emits an `activity` event (`{type, label, tool, iteration}`) naming what is running — progress only, forwarded verbatim and never persisted with the message, unlike an `action_taken` chip. The client mints a `client_turn_id` and sends it with the turn; `POST /chat/stop` takes that id and halts the turn mid-flight, so the button is live from the moment Send is pressed rather than only once the first SSE byte arrives. A stopped turn emits a `stopped` event and then the usual `done` over the same still-open stream — never an `error` — and whatever streamed so far is persisted and flagged. The endpoint returns 404 both for an unknown id and for another caller's turn, so it cannot be used to probe which turns are live. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages`, `POST /sessions/{id}/messages/{message_id}/feedback` | List and read saved chat sessions (assistant messages carry their row `id` and any `feedback`). The feedback route records 👍/👎 (`{\"feedback\": \"up\"|\"down\"|null}`) on one assistant reply; only the session's own caller or the principal may rate it (403 otherwise). The chat stream's `done` event carries `message_id` for the persisted reply. |\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`, `GET /people/{id}/open-loops`, `POST /open-loops/{loop_id}/close` | Roster CRUD and scope lookups. Archiving a person closes their open loops. The open-loop routes list what a person owes (soonest due first) and close one (`reason`: done / not_needed / cancelled) — both the principal's or the owner's only (403 otherwise, via `people.store.is_principal_or_self`). |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\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, and by source — the part of the system that made the calls — including server-side web-search counts). |\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. Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the eight specialist domains or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. |\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. The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`, so that `awaiting_human` frame carries `terminal: true` to say so explicitly, plus `resumable` — whether the run continues by itself once answered or stops at the gate. `GET /workflows/runs/{run_id}` returns the run row with the resume payload replaced by a small `resume_progress` summary (`gate_step_id`, `completed_step_ids`, or `null`): the payload holds every completed step's full text, and the run-detail page polls this endpoint while a run is unfinished. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\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}`, `GET /memories/people` | Episodic-memory record management, plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5). |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived people with an email, offered to the UI's sign-in gate. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. |\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`, `POST /chat/stop` | 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. Each round of tool calls also emits an `activity` event (`{type, label, tool, iteration}`) naming what is running — progress only, forwarded verbatim and never persisted with the message, unlike an `action_taken` chip. The client mints a `client_turn_id` and sends it with the turn; `POST /chat/stop` takes that id and halts the turn mid-flight, so the button is live from the moment Send is pressed rather than only once the first SSE byte arrives. A stopped turn emits a `stopped` event and then the usual `done` over the same still-open stream — never an `error` — and whatever streamed so far is persisted and flagged. The endpoint returns 404 both for an unknown id and for another caller's turn, so it cannot be used to probe which turns are live. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages`, `POST /sessions/{id}/messages/{message_id}/feedback` | List and read saved chat sessions (assistant messages carry their row `id` and any `feedback`). The feedback route records 👍/👎 (`{\"feedback\": \"up\"|\"down\"|null}`) on one assistant reply; only the session's own caller or the principal may rate it (403 otherwise). The chat stream's `done` event carries `message_id` for the persisted reply. |\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`, `GET /people/{id}/open-loops`, `POST /open-loops/{loop_id}/close`, `GET /people/{id}/outreach` | Roster CRUD and scope lookups. Archiving a person closes their open loops. The open-loop routes list what a person owes (soonest due first) and close one (`reason`: done / not_needed / cancelled) — both the principal's or the owner's only (403 otherwise, via `people.store.is_principal_or_self`). `/outreach` returns, per kind of proactive outreach over 30 days, `sent` / `replied` / `acted` / `ignored` / `pending` (voided DMs are excluded) — same access rule, checked before the person lookup so it can't probe which ids exist. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\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, and by source — the part of the system that made the calls — including server-side web-search counts). |\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. Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the eight specialist domains or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. |\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. The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`, so that `awaiting_human` frame carries `terminal: true` to say so explicitly, plus `resumable` — whether the run continues by itself once answered or stops at the gate. `GET /workflows/runs/{run_id}` returns the run row with the resume payload replaced by a small `resume_progress` summary (`gate_step_id`, `completed_step_ids`, or `null`): the payload holds every completed step's full text, and the run-detail page polls this endpoint while a run is unfinished. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\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}`, `GET /memories/people` | Episodic-memory record management, plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5). |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived people with an email, offered to the UI's sign-in gate. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. |\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-22T22:44:51.279191+00:00"+ "generated_at": "2026-09-22T23:17:20.508677+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/attunement.json b/packages/core/openexecutive/architecture/prebuilt/attunement.jsonindex 6e177013..ec46b139 100644--- a/packages/core/openexecutive/architecture/prebuilt/attunement.json+++ b/packages/core/openexecutive/architecture/prebuilt/attunement.json@@ -1,7 +1,7 @@{"section_id": "attunement","title": "Attunement (Open Loops)",- "markdown": "Attunement is the Executive adapting to each person it works with. Its first piece is **open loops**: the concrete things someone on the roster committed to, or was asked for, in conversation — tracked until they're done, and chased when they slip. It lives in `openexecutive.attunement`.\n\n### Why it exists\n\nBefore this, commitments were captured only from the principal's own words (`memory.episodic.should_extract` requires `is_principal`), because stored messages did not record who said them. A teammate's \"I'll send the vendor quote by Thursday\" vanished. And nothing in production ever set `scheduled_actions.awaiting_response_since`, so the nudge engine's commitment-chasing source had nothing to chase.\n\n### Sender attribution and feedback\n\nEvery persisted user message records `chat_messages.sender_person_id`: the **resolved** rostered sender, never the session owner. Discord and Telegram sessions from unrostered senders are owned by the principal so they still show in the sidebar; attribution keeps those outsiders' words from ever being read as the principal's. The web route passes its header-resolved caller (a header-less caller is the principal's own CLI / API surface; a signed-in email not on the roster resolves to nobody). Slack, Discord and Telegram pass the sender they resolved. For the turn itself, the Executive records the resolved speaker on `Session.caller_person_id`, which tool handlers read.\n\nAssistant replies can carry explicit feedback: `chat_messages.feedback` (`up` / `down`) via `POST /sessions/{id}/messages/{message_id}/feedback`, restricted to the session's own caller or the principal. The chat stream's `done` event includes `message_id` so the web panel renders 👍/👎 on the reply. Each rating writes an `attunement` audit row.\n\n### Opening and closing loops\n\nAfter every chat turn whose speaker resolved to a rostered, non-archived person — on any channel, email included, because the hook sits in the Executive rather than an adapter — `schedule_open_loop_pass` runs fire-and-forget, beside the episodic extraction:\n\n1. **Prefilter** — a keyword check (\"I'll\", \"by Friday\", \"can you\", … or, when loops are open, \"sent\", \"done\", …) skips most turns with no model call. A turn carrying an attached document (`[Attached: …]` inlined by `integrations.attachments`) is skipped outright: the document's words sit in the same message — after the text on the web, before it on Telegram and Discord — so a quote found there would be the document's, not the speaker's.\n2. **Budget** — `ATTUNEMENT_MAX_CALLS_PER_DAY` (default 200) is taken atomically from the `attunement_usage` row for the UTC day.\n3. **One forced-tool call** (`record_open_loops`, routing model) sees today's date, the speaker, the roster, the loops the speaker may close, the message and the reply. It may:\n - open a **commitment** the speaker made (owner = the speaker);\n - open an **ask** the speaker made of a named rostered person (owner = that person);\n - when the principal speaks, open a commitment the principal attributes to a named teammate (\"Sara will send the numbers Monday\");\n - close loops the speaker reports done, sent, no longer needed or cancelled — their own loops, or any loop when the principal speaks.\n4. **Gates in code**, not just the prompt: every item must quote the speaker's own message verbatim (commitments through the episodic extractor's `_is_valid_user_commitment`, so the Executive's own suggestions are never logged as someone's promise), and the stored `text` must itself appear verbatim in that message — it is re-injected into the nudge intent a tool-using turn executes, so it is never a model paraphrase (the intent also tells that turn to treat the quoted text as data); owners must resolve to exactly one rostered person (a full name not on the roster never falls back to a rostered first name — \"Ben Jones from Acme\" is not Ben Ortiz); a teammate cannot attribute a commitment to someone else; the principal's own commitments are left to the episodic extractor; a loop id outside the closable set is ignored; each owner holds at most `ATTUNEMENT_MAX_OPEN_LOOPS_PER_PERSON` (15). Due dates are clamped to 60 days and default to `ATTUNEMENT_LOOP_DEFAULT_DUE_DAYS` (2).\n5. **Audit** — one `attunement` row per pass (`op=extract`, opened / closed / dropped with reasons) plus `loop_opened` / `loop_closed` rows.\n\n### Storage and chasing\n\nA loop is a `scheduled_actions` row: `kind='open_loop'`, `channel='__internal__'`, inserted already `done` so the runner never dispatches it, `assigned_to_person_id` = owner, `awaiting_response_since` = due time, `scope_key` = `loop:{owner}:{hash}`. A partial unique index over open loops dedupes concurrent passes. That shape is exactly what existing readers expect:\n\n- the nudge engine's commitment source chases an open loop **as soon as it is overdue**, with a check-in addressed to its owner, through `prefer_channel_for`, availability windows, `NUDGE_MAX_PER_SCOPE` and the outbound guard;\n- `list_awaiting_replies_by_person` counts it **once it is due** (the same cut-off the nudge engine uses), so `/today`'s roster and reflection's \"people waiting\" include an overdue loop but not one still in the future — while `last_contact_at_by_person`, the client engagement \"follow-ups completed\" count and the `/today` activity feed (which now filters `__internal__` rows in SQL so loops cannot crowd real sends out of its window) all exclude it, since a loop is not a message sent;\n- `executive_reflection` renders an **OPEN LOOPS** block (up to 10, overdue flagged).\n\nA loop closes (its `awaiting_response_since` cleared, audited) when the owner reports it done, when the principal or owner calls `close_open_loop` or uses **Mark done** on the person's page, when its owner is archived, or when it passes `ATTUNEMENT_LOOP_TTL_DAYS` (21) — expired at the start of each nudge scan.\n\n### Who can see and close a loop\n\nWhat someone owes is not roster-public. `list_open_loops` shows the principal everyone's loops only on a **private surface** — web chat, a Slack or Discord DM, or a 1:1 Telegram chat; in a shared channel or thread, a Telegram group, a Google Chat space or an email thread (which can carry cc's), and for anyone else, it shows only the caller's own loops, and an unresolved caller gets nothing. `GET /people/{id}/open-loops` is the principal's or that person's only.\n\n`close_open_loop` (chat tool) and `POST /open-loops/{id}/close` only close when the resolved caller is the principal or the loop's owner. Every one of these checks, and the feedback route's, goes through one helper, `people.store.is_principal_or_self`. Loop ids appear in prompts and replies and inbound email reaches the Executive, so a quoted \"close loop 12\" from an unrostered sender, a signed-in web user not on the roster, or an unattended session (a scheduled nudge's prompt quotes the loop text) is refused. The reflection pass is not given the tool at all.\n\n### Settings\n\n`ATTUNEMENT_ENABLED`, `ATTUNEMENT_OPEN_LOOPS_ENABLED`, `ATTUNEMENT_LOOP_DEFAULT_DUE_DAYS`, `ATTUNEMENT_LOOP_TTL_DAYS`, `ATTUNEMENT_MAX_OPEN_LOOPS_PER_PERSON`, `ATTUNEMENT_MAX_CALLS_PER_DAY`. The open loops themselves live in `scheduled_actions` and the attribution columns in `chat_messages`, both wiped by company switches and resets; `attunement_usage` is wiped with them.\n\n### Known gaps\n\nEmail and Google Chat turns open and close loops (the hook is in the Executive) but do not persist `chat_messages`, so they carry no stored attribution or feedback.",+ "markdown": "Attunement is the Executive adapting to each person it works with. Its first piece is **open loops**: the concrete things someone on the roster committed to, or was asked for, in conversation — tracked until they're done, and chased when they slip. It lives in `openexecutive.attunement`.\n\n### Why it exists\n\nBefore this, commitments were captured only from the principal's own words (`memory.episodic.should_extract` requires `is_principal`), because stored messages did not record who said them. A teammate's \"I'll send the vendor quote by Thursday\" vanished. And nothing in production ever set `scheduled_actions.awaiting_response_since`, so the nudge engine's commitment-chasing source had nothing to chase.\n\n### Sender attribution and feedback\n\nEvery persisted user message records `chat_messages.sender_person_id`: the **resolved** rostered sender, never the session owner. Discord and Telegram sessions from unrostered senders are owned by the principal so they still show in the sidebar; attribution keeps those outsiders' words from ever being read as the principal's. The web route passes its header-resolved caller (a header-less caller is the principal's own CLI / API surface; a signed-in email not on the roster resolves to nobody). Slack, Discord and Telegram pass the sender they resolved. For the turn itself, the Executive records the resolved speaker on `Session.caller_person_id`, which tool handlers read.\n\nAssistant replies can carry explicit feedback: `chat_messages.feedback` (`up` / `down`) via `POST /sessions/{id}/messages/{message_id}/feedback`, restricted to the session's own caller or the principal. The chat stream's `done` event includes `message_id` so the web panel renders 👍/👎 on the reply. Each rating writes an `attunement` audit row.\n\n### Opening and closing loops\n\nAfter every chat turn whose speaker resolved to a rostered, non-archived person — on any channel, email included, because the hook sits in the Executive rather than an adapter — `schedule_open_loop_pass` runs fire-and-forget, beside the episodic extraction:\n\n1. **Prefilter** — a keyword check (\"I'll\", \"by Friday\", \"can you\", … or, when loops are open, \"sent\", \"done\", …) skips most turns with no model call. A turn carrying an attached document (`[Attached: …]` inlined by `integrations.attachments`) is skipped outright: the document's words sit in the same message — after the text on the web, before it on Telegram and Discord — so a quote found there would be the document's, not the speaker's.\n2. **Budget** — `ATTUNEMENT_MAX_CALLS_PER_DAY` (default 200) is taken atomically from the `attunement_usage` row for the UTC day.\n3. **One forced-tool call** (`record_open_loops`, routing model) sees today's date, the speaker, the roster, the loops the speaker may close, the message and the reply. It may:\n - open a **commitment** the speaker made (owner = the speaker);\n - open an **ask** the speaker made of a named rostered person (owner = that person);\n - when the principal speaks, open a commitment the principal attributes to a named teammate (\"Sara will send the numbers Monday\");\n - close loops the speaker reports done, sent, no longer needed or cancelled — their own loops, or any loop when the principal speaks.\n4. **Gates in code**, not just the prompt: every item must quote the speaker's own message verbatim (commitments through the episodic extractor's `_is_valid_user_commitment`, so the Executive's own suggestions are never logged as someone's promise), and the stored `text` must itself appear verbatim in that message — it is re-injected into the nudge intent a tool-using turn executes, so it is never a model paraphrase (the intent also tells that turn to treat the quoted text as data); owners must resolve to exactly one rostered person (a full name not on the roster never falls back to a rostered first name — \"Ben Jones from Acme\" is not Ben Ortiz); a teammate cannot attribute a commitment to someone else; the principal's own commitments are left to the episodic extractor; a loop id outside the closable set is ignored; each owner holds at most `ATTUNEMENT_MAX_OPEN_LOOPS_PER_PERSON` (15). Due dates are clamped to 60 days and default to `ATTUNEMENT_LOOP_DEFAULT_DUE_DAYS` (2).\n5. **Audit** — one `attunement` row per pass (`op=extract`, opened / closed / dropped with reasons) plus `loop_opened` / `loop_closed` rows.\n\n### Storage and chasing\n\nA loop is a `scheduled_actions` row: `kind='open_loop'`, `channel='__internal__'`, inserted already `done` so the runner never dispatches it, `assigned_to_person_id` = owner, `awaiting_response_since` = due time, `scope_key` = `loop:{owner}:{hash}`. A partial unique index over open loops dedupes concurrent passes. That shape is exactly what existing readers expect:\n\n- the nudge engine's commitment source chases an open loop **as soon as it is overdue**, with a check-in addressed to its owner, through `prefer_channel_for`, availability windows, `NUDGE_MAX_PER_SCOPE` and the outbound guard;\n- `list_awaiting_replies_by_person` counts it **once it is due** (the same cut-off the nudge engine uses), so `/today`'s roster and reflection's \"people waiting\" include an overdue loop but not one still in the future — while `last_contact_at_by_person`, the client engagement \"follow-ups completed\" count and the `/today` activity feed (which now filters `__internal__` rows in SQL so loops cannot crowd real sends out of its window) all exclude it, since a loop is not a message sent;\n- `executive_reflection` renders an **OPEN LOOPS** block (up to 10, overdue flagged).\n\nA loop closes (its `awaiting_response_since` cleared, audited) when the owner reports it done, when the principal or owner calls `close_open_loop` or uses **Mark done** on the person's page, when its owner is archived, or when it passes `ATTUNEMENT_LOOP_TTL_DAYS` (21) — expired at the start of each nudge scan.\n\n### Who can see and close a loop\n\nWhat someone owes is not roster-public. `list_open_loops` shows the principal everyone's loops only on a **private surface** — web chat, a Slack or Discord DM, or a 1:1 Telegram chat; in a shared channel or thread, a Telegram group, a Google Chat space or an email thread (which can carry cc's), and for anyone else, it shows only the caller's own loops, and an unresolved caller gets nothing. `GET /people/{id}/open-loops` is the principal's or that person's only.\n\n`close_open_loop` (chat tool) and `POST /open-loops/{id}/close` only close when the resolved caller is the principal or the loop's owner. Every one of these checks, and the feedback route's, goes through one helper, `people.store.is_principal_or_self`. Loop ids appear in prompts and replies and inbound email reaches the Executive, so a quoted \"close loop 12\" from an unrostered sender, a signed-in web user not on the roster, or an unattended session (a scheduled nudge's prompt quotes the loop text) is refused. The reflection pass is not given the tool at all.\n\n### Outcome ledger — what lands, per person\n\n`attunement.outcomes` records every **proactive** DM to a rostered person and resolves it with no model call, so the Executive can do more of what gets answered and less of what doesn't.\n\n- **Recording.** Proactive work tags itself with `tag_proactive(source, ref)` — a ContextVar, wrapped only around non-yielding code — and the single point every DM passes through, `schedule_tools._record_outbound_context`, writes a `proactive_outcomes` row next to the `outbound_context` linkage when a tag is set and the recipient resolves to a Person. Tagged callers: the scheduler's generic dispatch (a nudge is `nudge_stalled` / `nudge_commitment` / `nudge_initiative`, or `open_loop` when its commitment target is an open loop, keyed by its scope key; anything else is `followup`), `executive_reflection` (`reflection`), `executive_research` (`research`) and alert review (`alert_review`, keyed `alert:<id>`). A user's own chat turn is never tagged, and web-chat sends write no linkage. Only the addressed recipient counts: an email's first `to` address gets a row, its cc's only get reply linkage; and a follow-up the principal scheduled for themselves is not outreach.\n- **Resolution.** `replied` when the recipient's reply consumes the linkage (`mark_outbound_context_consumed`). `acted` when the thing it was about got done, however it was done: the open loop a chase was about is reported done **by its owner** (the principal tidying a loop away credits nobody); the approval a stalled-run nudge chased is resolved (`resumer.apply_resolution`); the initiative a check-in was about is updated; or the alert a review DM was about is acknowledged or resolved — credited only to the person it is routed to and the principal, never to someone DM'd about it on an earlier pass. `void` when that alert is dismissed or found stale: the DM didn't matter, so it counts neither way — a dismissal, which anyone with API access can make, can never lower someone's rate. `ignored` when still open after `ATTUNEMENT_IGNORE_AFTER_HOURS` (72) — swept at the start of each nudge scan and whenever rates are read, so the rates stay honest with the scan disabled. Expired, cancelled or archived loops resolve nothing.\n- **Use.** `acceptance()` gives per-(person, source) counts over 30 days. The nudge engine demotes a candidate whose person left their **last** `ATTUNEMENT_MUTE_MIN_SENDS` (5) resolved sends of that source all unanswered (`muted_pairs`): it ranks after every other candidate and its cooldown is multiplied by `ATTUNEMENT_MUTE_COOLDOWN_MULTIPLIER` (3). It is never dropped, and a single answer lifts it — judged on the most recent sends rather than a 30-day share, which would keep a demoted source (with fewer chances to be answered) demoted long after the person came back. Reflection gets a **WHAT LANDS** block (per person, per source with ≥3 resolved), and the prompt steers DMs toward the kinds that land. `GET /people/{id}/outreach` (principal or that person) backs a \"How they respond\" card on the person page.\n\n### Settings\n\n`ATTUNEMENT_ENABLED`, `ATTUNEMENT_OPEN_LOOPS_ENABLED`, `ATTUNEMENT_LOOP_DEFAULT_DUE_DAYS`, `ATTUNEMENT_LOOP_TTL_DAYS`, `ATTUNEMENT_MAX_OPEN_LOOPS_PER_PERSON`, `ATTUNEMENT_MAX_CALLS_PER_DAY`, `ATTUNEMENT_IGNORE_AFTER_HOURS`, `ATTUNEMENT_MUTE_MIN_SENDS`, `ATTUNEMENT_MUTE_COOLDOWN_MULTIPLIER`. The open loops themselves live in `scheduled_actions` and the attribution columns in `chat_messages`, both wiped by company switches and resets; `attunement_usage` and `proactive_outcomes` are wiped with them.\n\n### Known gaps\n\nEmail and Google Chat turns open and close loops (the hook is in the Executive) but do not persist `chat_messages`, so they carry no stored attribution or feedback. `POST /alerts/{id}/ack` has no per-caller authorization (pre-existing), which is why a dismissal voids rather than counts against anyone. Principal briefs and dynamic-workflow deliveries run without a chat session, so they write no outreach linkage and are not in the outcome ledger; broadcasts to a channel have no single recipient and are not counted either.","mermaid": "flowchart TD\n Turn[\"Chat turn<br/>(any channel)\"]\n Resolve[\"Resolved speaker<br/>(rostered, not archived)\"]\n Persist[(\"chat_messages<br/>sender_person_id · feedback\")]\n Pre[\"Prefilter + daily budget\"]\n LLM[\"record_open_loops<br/>(forced tool)\"]\n Gate[\"Code gates<br/>verbatim quote · owner · closable set\"]\n Loops[(\"scheduled_actions<br/>kind=open_loop\")]\n Nudge[\"nudge_engine<br/>commitment source\"]\n Guard[\"prefer_channel_for<br/>+ outbound guard\"]\n Owner[\"Owner's channel\"]\n Reflect[\"executive_reflection<br/>OPEN LOOPS block\"]\n Today[\"/today awaiting counts\"]\n Close[\"close_open_loop · Mark done<br/>archive · TTL expiry\"]\n Turn --> Resolve\n Resolve --> Persist\n Resolve --> Pre\n Pre --> LLM\n LLM --> Gate\n Gate -- \"open / close\" --> Loops\n Loops -- \"overdue\" --> Nudge\n Nudge --> Guard\n Guard --> Owner\n Loops --> Reflect\n Loops --> Today\n Close --> Loops\n class Turn entry\n class Resolve compute\n class Persist storage\n class Pre compute\n class LLM hot\n class Gate compute\n class Loops storage\n class Nudge compute\n class Guard compute\n class Owner external\n class Reflect compute\n class Today compute\n class Close compute",- "generated_at": "2026-09-22T22:46:36.368281+00:00"+ "generated_at": "2026-09-22T23:17:20.508677+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/clients.json b/packages/core/openexecutive/architecture/prebuilt/clients.jsonindex 29098185..b3f04d4d 100644--- a/packages/core/openexecutive/architecture/prebuilt/clients.json+++ b/packages/core/openexecutive/architecture/prebuilt/clients.json@@ -1,7 +1,7 @@{"section_id": "clients","title": "Client Companies (Slots)",- "markdown": "The **clients** module (`openexecutive.clients`) adds **multi-client mode** for fractional executives: one Open Executive instance serving several client companies, exactly **one active at a time**. It generalizes the fixture switcher's swap machinery into named, durable *slots* — save files of the full company context. Single-company installs are untouched: nothing changes until a slot is explicitly created, and the `/clients` page shows only an intro until then.\n\n## What a slot contains\n\nEach slot lives at `company/_client_slots/<slug>/` (gitignored — client data is never committable):\n\n| Artifact | What it carries |\n| --- | --- |\n| `state.db` | A transactionally-consistent copy of the shared SQLite DB — chat history, scheduled actions, departments, people, watchlist, audit/run history |\n| `profile.yaml` | The company profile |\n| `docs/`, `skills/` | Company documents (all file types) and company-authored skills |\n| `mcp_servers.json` | Per-client external MCP tools (e.g. one client's Crayon or Google Workspace credentials) |\n| `meta.json` | Display name + created/saved timestamps |\n\n## Switching\n\n`POST /clients/{slug}/activate` saves the current client back to its slot (`VACUUM INTO` for the DB copy), then restores the target: the DB through sqlite3's online **backup API** (the live file's inode never changes, so handles held elsewhere stay valid), the company artifacts by replacement, and the ChromaDB `company_docs` collection + company skills re-indexed from the restored directories. The isolated per-company collections are wiped in the same pass — `recent_research`, `notion_wiki`, and `inbound_attachments` (attachments are dropped and recreated rather than re-indexed: they have no source directory to rebuild from, and a row surviving a slot switch would be one client's attachment visible to the next). Idempotent schema initializers re-run after every restore, so a slot saved before a schema-adding deploy gains the new tables. Activating a **blank** slot (created with `source: \"blank\"`, no `state.db` yet) factory-wipes the per-client tables and re-seeds defaults — departments, principal briefs, cadences — so the new client's Today page works without a restart. That wipe covers the **derived caches** — `briefing_narrative` and `person_insights` — as well as authored state. They are regenerable, but `/today` serves them from cache and only regenerates in a background task, so a surviving row renders the *outgoing* client's briefing text under the incoming one, and `person_insights` reaches Discord, the MCP server, and the morning/end-of-day digests as well as the UI. Switching into a slot that already has `state.db` was never exposed: the sqlite backup API truncates the destination to an exact copy of the source.\n\nThe first activation from single-company mode auto-snapshots the original company to `_user_backup` (the same restore point the fixture switcher uses); `POST /fixtures/unload` brings it back and exits client mode.\n\n## Invariants\n\n- At most one slot is active — recorded in an allowlist-validated `.active_client` sentinel.\n- **Only the active client is live**: its scheduled actions fire, its docs are indexed; parked clients sleep. The single-instance scheduler constraint is unchanged.\n- Slot operations share the fixture switcher's destructive-op lock, so fixture loads, snapshots, resets, and slot switches serialize against each other. The Notion sync tick coordinates with the same lock without queueing on it: it skips its tick while the lock is held, fetches from Notion unlocked, and takes the lock only for its short local write phase — aborting without writing if the active client changed mid-fetch (in-process only; a CLI run is a separate process the lock cannot see). A fixture and a client are never active simultaneously (slot ops refuse with 409 while a fixture is loaded); loading a fixture saves an active client back to its slot first, so demos can never destroy client work. Factory reset clears the active-client sentinel but preserves slot directories.\n- `generated_fixtures` is operator-level (the demo library) and is preserved verbatim across switches.\n- **Every path that swaps the live company wipes the derived caches**, from one shared list (`cli.fixture_loader.PER_CLIENT_CACHE_TABLES`): blank/seed slot activation, factory reset, and fixture load *and* unload. Three hand-maintained copies of that list is what let the leak survive in two paths after being fixed in one — a new per-company cache table goes in the constant, once. On the fixture path the wipe runs in `_apply_state_from_source`, unconditionally: a fixture needs only `profile.yaml`, so gating it on `memory.json` would skip exactly the loads that still swap the company.\n- Do **not** treat `person_insights`' `input_hash` as a guard against this. It covers per-person signals (role, principal flag, status, counters, availability, authority and department scope, bucketed timestamps, the UTC day) but carries no person, name or company identity, and the cache key is `person_id` — a reused autoincrement PK. An outgoing principal and a freshly seeded incoming one hash identically whenever those signals coincide, which is ordinary steady state for a seeded slot.\n- Each client gets a stable Honcho workspace (`openexec-client-<slug>`) so peer memory survives parking; fixture teardown paths recognise the prefix and never delete these.\n\n## Caveats\n\n`mcp_servers.json` is read by the MCP gateway at process startup — a switch that changes it takes effect on the next API restart (the activate response carries `mcp_config_changed`). Scheduled actions whose `run_at` passed while a client was parked are claimed on the first tick after activation; authority gates still apply, but expect the returning client's overdue follow-ups to fire shortly after a switch.\n\nTwo residuals. `/today`'s background regeneration tasks capture the outgoing company's data and can write it back into the live DB for up to roughly 25 seconds after the wipe — on **every** swapping path, fixture load/unload and slot activation alike, since those writers neither take the destructive-op lock nor check company identity. For `person_insights` it does not self-heal: the late write stores the outgoing `input_hash`, which the incoming person's signals often match, so the stale note survives until the UTC-day bucket rolls. Closing this needs company identity in the cache hash or those writers taking the lock. Second, and blank-slot only, `dynamic_workflows` / `eval_scenarios` are client-scoped but **not** wiped: they are authored rather than derived, and the first-activation snapshot captures only profile, docs, `memory.json`, people and departments — so wiping them before extending that snapshot would destroy the operator's own work. Until then the outgoing client's workflow definitions stay registered and active on the blank path, runnable against the incoming client's data and readable via `/workflows`.\n\n## Setting up a new engagement with AI\n\n`POST /clients/generate` turns **real intake material** into a reviewable draft of the client: profile, org, roster, starter docs, and known history. Intake material is pasted text (kickoff-call notes, a brief, website copy) and/or **file attachments** (PDF, Word, Excel, CSV, Markdown/text; the request is multipart). Each attachment's extracted text both feeds the draft and is appended to the bundle as a `source_<name>.md` company doc, so it lands in the seed slot and is indexed into the `company_docs` collection on activation alongside the AI-written docs (extracted text, not the original binary; legacy `.xls` is unsupported). It runs the Council-configurable `engagement_intake` agent — the grounded sibling of the demo fixture generator (same bundle schema, validation, and repair-retry; the Company Simulator's fictional path is unchanged). Grounding rules: extract, don't invent — unstated numbers stay null, only people named in the material appear, docs are engagement working documents (intake brief, current-state summary, stakeholder map, open questions), and **no contact handles are ever imported**, even if present in the notes.\n\nSaving the reviewed draft (`POST /clients` with `source: \"generated\"`) writes a **seed slot**: profile and docs as normal slot artifacts, plus `people.yaml` / `departments.yaml` / `memory.json` in the same shapes curated fixtures use. Nothing touches live state until activation, when the blank-restore path applies the seed files with the fixture loader's seeders and skips the default-department reseed (the draft supplied the org). After the first save-back writes `state.db`, the seed files remain as the engagement's birth record but are no longer consulted; `meta.json` records `origin: \"generated\"` and the intake notes.\n\n## The practice layer: engagement metadata + cockpit\n\nEach slot's `meta.json` carries optional **engagement metadata** — your role for the client, engagement status (active/paused/winding down/completed), start and renewal dates, retainer (display only), and primary contact — editable via `PATCH /clients/{slug}` for active *and* parked slots, because meta.json lives outside the swapped client state. Renewal awareness deliberately lives here and never as scheduled actions (those swap with the client and would vanish when parked).\n\nThe **practice cockpit** (`GET /clients/cockpit`) gives cross-client awareness without touching the one-active-client ceiling: the active client is counted from the live DB, and each parked client's `state.db` is opened **read-only, in place** — no activation, no lock. Cards roll up pending/overdue follow-ups, awaiting replies, unread alerts, and renewal countdowns. Parked data is as fresh as the slot's last save point and every card says so; one broken slot degrades to a single error-flagged card, never a failed board. Cockpit cards link to the **engagement value report** — a workflow that turns the client's own record (decisions, deliverables, follow-through) into a renewal-ready artifact, reading parked clients without activating them. With two or more clients, `/today` gains an \"Across your clients\" section for the parked ones — single-company installs see none of this, anywhere.\n\n## Overnight rotation (cockpit v2)\n\nWith `CLIENT_ROTATION_ENABLED=true` (off by default), a nightly scheduled job (`CLIENT_ROTATION_TIME`, default 03:30 UTC) activates each parked client in turn, generates its morning brief as an artifact in that client's own record, runs its monitor scan, saves it back, and **always restores the original active client** — then delivers one cross-client digest via the original client's principal channel. Two safety rails matter: the scheduler **pauses claiming** while the rotation's `.rotation_in_progress` marker exists (so a just-activated client's overdue outbound backlog can never fire at 3am — rotation does brief + monitors only, never outbound), and the rotation row is re-seeded after every slot activation because scheduled rows swap with the client. Completed engagements and never-activated slots sleep through rotation; per-client failures are skipped and reported in the digest.\n\n## API + UI\n\n`GET /clients` (list + active + fixture status), `POST /clients` (`source: \"current\"` captures the live company and activates; `\"blank\"` creates an empty client to onboard fresh; `\"generated\"` saves a reviewed intake draft as a seed slot), `POST /clients/generate` (grounded AI draft from intake notes and/or file attachments; multipart), `PATCH /clients/{slug}` (engagement metadata), `GET /clients/cockpit` (practice board), `POST /clients/save` (checkpoint without switching), `POST /clients/{slug}/activate`, `DELETE /clients/{slug}` (refuses the active slot). The `/clients` page lives under Settings → advanced tools.\n\n**Knowledge review state per slot.** `_ensure_schemas` re-runs the idempotent schema inits after a restore, including `ReviewStore.initialize_db` followed by `sync_builtin_registrations`. Without that second call a freshly activated slot carried an empty `review_items` table until the next process restart; now it gets the shipped docs as trusted defaults straight away, matching a normal boot.\n\nAttunement adds no per-client table of its own beyond the `attunement_usage` daily call counter, which is in `_BLANK_WIPE_TABLES` and `reset_all_state`: open loops live in `scheduled_actions` and message attribution / feedback in `chat_messages`, both already swapped with the slot. The engagement report's \"follow-ups completed\" count excludes open loops (`kind != 'open_loop'`): they are recorded `done` but are promises someone made, not follow-ups the Executive completed.",+ "markdown": "The **clients** module (`openexecutive.clients`) adds **multi-client mode** for fractional executives: one Open Executive instance serving several client companies, exactly **one active at a time**. It generalizes the fixture switcher's swap machinery into named, durable *slots* — save files of the full company context. Single-company installs are untouched: nothing changes until a slot is explicitly created, and the `/clients` page shows only an intro until then.\n\n## What a slot contains\n\nEach slot lives at `company/_client_slots/<slug>/` (gitignored — client data is never committable):\n\n| Artifact | What it carries |\n| --- | --- |\n| `state.db` | A transactionally-consistent copy of the shared SQLite DB — chat history, scheduled actions, departments, people, watchlist, audit/run history |\n| `profile.yaml` | The company profile |\n| `docs/`, `skills/` | Company documents (all file types) and company-authored skills |\n| `mcp_servers.json` | Per-client external MCP tools (e.g. one client's Crayon or Google Workspace credentials) |\n| `meta.json` | Display name + created/saved timestamps |\n\n## Switching\n\n`POST /clients/{slug}/activate` saves the current client back to its slot (`VACUUM INTO` for the DB copy), then restores the target: the DB through sqlite3's online **backup API** (the live file's inode never changes, so handles held elsewhere stay valid), the company artifacts by replacement, and the ChromaDB `company_docs` collection + company skills re-indexed from the restored directories. The isolated per-company collections are wiped in the same pass — `recent_research`, `notion_wiki`, and `inbound_attachments` (attachments are dropped and recreated rather than re-indexed: they have no source directory to rebuild from, and a row surviving a slot switch would be one client's attachment visible to the next). Idempotent schema initializers re-run after every restore, so a slot saved before a schema-adding deploy gains the new tables. Activating a **blank** slot (created with `source: \"blank\"`, no `state.db` yet) factory-wipes the per-client tables and re-seeds defaults — departments, principal briefs, cadences — so the new client's Today page works without a restart. That wipe covers the **derived caches** — `briefing_narrative` and `person_insights` — as well as authored state. They are regenerable, but `/today` serves them from cache and only regenerates in a background task, so a surviving row renders the *outgoing* client's briefing text under the incoming one, and `person_insights` reaches Discord, the MCP server, and the morning/end-of-day digests as well as the UI. Switching into a slot that already has `state.db` was never exposed: the sqlite backup API truncates the destination to an exact copy of the source.\n\nThe first activation from single-company mode auto-snapshots the original company to `_user_backup` (the same restore point the fixture switcher uses); `POST /fixtures/unload` brings it back and exits client mode.\n\n## Invariants\n\n- At most one slot is active — recorded in an allowlist-validated `.active_client` sentinel.\n- **Only the active client is live**: its scheduled actions fire, its docs are indexed; parked clients sleep. The single-instance scheduler constraint is unchanged.\n- Slot operations share the fixture switcher's destructive-op lock, so fixture loads, snapshots, resets, and slot switches serialize against each other. The Notion sync tick coordinates with the same lock without queueing on it: it skips its tick while the lock is held, fetches from Notion unlocked, and takes the lock only for its short local write phase — aborting without writing if the active client changed mid-fetch (in-process only; a CLI run is a separate process the lock cannot see). A fixture and a client are never active simultaneously (slot ops refuse with 409 while a fixture is loaded); loading a fixture saves an active client back to its slot first, so demos can never destroy client work. Factory reset clears the active-client sentinel but preserves slot directories.\n- `generated_fixtures` is operator-level (the demo library) and is preserved verbatim across switches.\n- **Every path that swaps the live company wipes the derived caches**, from one shared list (`cli.fixture_loader.PER_CLIENT_CACHE_TABLES`): blank/seed slot activation, factory reset, and fixture load *and* unload. Three hand-maintained copies of that list is what let the leak survive in two paths after being fixed in one — a new per-company cache table goes in the constant, once. On the fixture path the wipe runs in `_apply_state_from_source`, unconditionally: a fixture needs only `profile.yaml`, so gating it on `memory.json` would skip exactly the loads that still swap the company.\n- Do **not** treat `person_insights`' `input_hash` as a guard against this. It covers per-person signals (role, principal flag, status, counters, availability, authority and department scope, bucketed timestamps, the UTC day) but carries no person, name or company identity, and the cache key is `person_id` — a reused autoincrement PK. An outgoing principal and a freshly seeded incoming one hash identically whenever those signals coincide, which is ordinary steady state for a seeded slot.\n- Each client gets a stable Honcho workspace (`openexec-client-<slug>`) so peer memory survives parking; fixture teardown paths recognise the prefix and never delete these.\n\n## Caveats\n\n`mcp_servers.json` is read by the MCP gateway at process startup — a switch that changes it takes effect on the next API restart (the activate response carries `mcp_config_changed`). Scheduled actions whose `run_at` passed while a client was parked are claimed on the first tick after activation; authority gates still apply, but expect the returning client's overdue follow-ups to fire shortly after a switch.\n\nTwo residuals. `/today`'s background regeneration tasks capture the outgoing company's data and can write it back into the live DB for up to roughly 25 seconds after the wipe — on **every** swapping path, fixture load/unload and slot activation alike, since those writers neither take the destructive-op lock nor check company identity. For `person_insights` it does not self-heal: the late write stores the outgoing `input_hash`, which the incoming person's signals often match, so the stale note survives until the UTC-day bucket rolls. Closing this needs company identity in the cache hash or those writers taking the lock. Second, and blank-slot only, `dynamic_workflows` / `eval_scenarios` are client-scoped but **not** wiped: they are authored rather than derived, and the first-activation snapshot captures only profile, docs, `memory.json`, people and departments — so wiping them before extending that snapshot would destroy the operator's own work. Until then the outgoing client's workflow definitions stay registered and active on the blank path, runnable against the incoming client's data and readable via `/workflows`.\n\n## Setting up a new engagement with AI\n\n`POST /clients/generate` turns **real intake material** into a reviewable draft of the client: profile, org, roster, starter docs, and known history. Intake material is pasted text (kickoff-call notes, a brief, website copy) and/or **file attachments** (PDF, Word, Excel, CSV, Markdown/text; the request is multipart). Each attachment's extracted text both feeds the draft and is appended to the bundle as a `source_<name>.md` company doc, so it lands in the seed slot and is indexed into the `company_docs` collection on activation alongside the AI-written docs (extracted text, not the original binary; legacy `.xls` is unsupported). It runs the Council-configurable `engagement_intake` agent — the grounded sibling of the demo fixture generator (same bundle schema, validation, and repair-retry; the Company Simulator's fictional path is unchanged). Grounding rules: extract, don't invent — unstated numbers stay null, only people named in the material appear, docs are engagement working documents (intake brief, current-state summary, stakeholder map, open questions), and **no contact handles are ever imported**, even if present in the notes.\n\nSaving the reviewed draft (`POST /clients` with `source: \"generated\"`) writes a **seed slot**: profile and docs as normal slot artifacts, plus `people.yaml` / `departments.yaml` / `memory.json` in the same shapes curated fixtures use. Nothing touches live state until activation, when the blank-restore path applies the seed files with the fixture loader's seeders and skips the default-department reseed (the draft supplied the org). After the first save-back writes `state.db`, the seed files remain as the engagement's birth record but are no longer consulted; `meta.json` records `origin: \"generated\"` and the intake notes.\n\n## The practice layer: engagement metadata + cockpit\n\nEach slot's `meta.json` carries optional **engagement metadata** — your role for the client, engagement status (active/paused/winding down/completed), start and renewal dates, retainer (display only), and primary contact — editable via `PATCH /clients/{slug}` for active *and* parked slots, because meta.json lives outside the swapped client state. Renewal awareness deliberately lives here and never as scheduled actions (those swap with the client and would vanish when parked).\n\nThe **practice cockpit** (`GET /clients/cockpit`) gives cross-client awareness without touching the one-active-client ceiling: the active client is counted from the live DB, and each parked client's `state.db` is opened **read-only, in place** — no activation, no lock. Cards roll up pending/overdue follow-ups, awaiting replies, unread alerts, and renewal countdowns. Parked data is as fresh as the slot's last save point and every card says so; one broken slot degrades to a single error-flagged card, never a failed board. Cockpit cards link to the **engagement value report** — a workflow that turns the client's own record (decisions, deliverables, follow-through) into a renewal-ready artifact, reading parked clients without activating them. With two or more clients, `/today` gains an \"Across your clients\" section for the parked ones — single-company installs see none of this, anywhere.\n\n## Overnight rotation (cockpit v2)\n\nWith `CLIENT_ROTATION_ENABLED=true` (off by default), a nightly scheduled job (`CLIENT_ROTATION_TIME`, default 03:30 UTC) activates each parked client in turn, generates its morning brief as an artifact in that client's own record, runs its monitor scan, saves it back, and **always restores the original active client** — then delivers one cross-client digest via the original client's principal channel. Two safety rails matter: the scheduler **pauses claiming** while the rotation's `.rotation_in_progress` marker exists (so a just-activated client's overdue outbound backlog can never fire at 3am — rotation does brief + monitors only, never outbound), and the rotation row is re-seeded after every slot activation because scheduled rows swap with the client. Completed engagements and never-activated slots sleep through rotation; per-client failures are skipped and reported in the digest.\n\n## API + UI\n\n`GET /clients` (list + active + fixture status), `POST /clients` (`source: \"current\"` captures the live company and activates; `\"blank\"` creates an empty client to onboard fresh; `\"generated\"` saves a reviewed intake draft as a seed slot), `POST /clients/generate` (grounded AI draft from intake notes and/or file attachments; multipart), `PATCH /clients/{slug}` (engagement metadata), `GET /clients/cockpit` (practice board), `POST /clients/save` (checkpoint without switching), `POST /clients/{slug}/activate`, `DELETE /clients/{slug}` (refuses the active slot). The `/clients` page lives under Settings → advanced tools.\n\n**Knowledge review state per slot.** `_ensure_schemas` re-runs the idempotent schema inits after a restore, including `ReviewStore.initialize_db` followed by `sync_builtin_registrations`. Without that second call a freshly activated slot carried an empty `review_items` table until the next process restart; now it gets the shipped docs as trusted defaults straight away, matching a normal boot.\n\nAttunement adds no per-client table of its own beyond the `attunement_usage` daily call counter and the `proactive_outcomes` ledger, both in `_BLANK_WIPE_TABLES` and `reset_all_state`: open loops live in `scheduled_actions` and message attribution / feedback in `chat_messages`, both already swapped with the slot. The engagement report's \"follow-ups completed\" count excludes open loops (`kind != 'open_loop'`): they are recorded `done` but are promises someone made, not follow-ups the Executive completed.","mermaid": "flowchart TD\n UI[\"/clients page (Settings)\"] -->|\"activate slug\"| Lock[\"destructive-op lock (shared with fixtures)\"]\n Lock --> SaveBack[\"save-back: VACUUM INTO state.db + copy profile / docs / skills / mcp\"]\n SaveBack --> SlotA[(\"slot A dir\")]\n SlotB[(\"slot B dir\")] --> Restore[\"restore: sqlite backup API + artifact replacement\"]\n Lock --> Restore\n Restore --> Live[(\"live company context\")]\n Restore --> Chroma[\"reindex company_docs + skills\"]\n Restore -.stable workspace.-> Honcho[\"Honcho peer memory\"]\n Live --> Scheduler[\"scheduler: only the ACTIVE client's actions fire\"]",- "generated_at": "2026-09-22T22:50:33.153068+00:00"+ "generated_at": "2026-09-22T23:07:13.054261+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/lifecycle.json b/packages/core/openexecutive/architecture/prebuilt/lifecycle.jsonindex 43003dff..7aa96623 100644--- a/packages/core/openexecutive/architecture/prebuilt/lifecycle.json+++ b/packages/core/openexecutive/architecture/prebuilt/lifecycle.json@@ -1,7 +1,7 @@{"section_id": "lifecycle","title": "Request Lifecycle",- "markdown": "A single chat message makes a full round-trip through the API, the orchestrator's tool-use loop, a parallel specialist fan-out, and synthesis — all streamed back as server-sent events.\n\n### Steps\n\n1. **Arrival** — the client mints a `client_turn_id` and posts to `POST /chat` (`openexecutive.api.routes.chat`). The turn carries a `<current_speaker>` hint resolved from the caller's `person_id`, plus a `<briefing>` digest of current open alerts (built in parallel with RAG/episodic/peer-memory fetches) so the Executive can discuss any item shown on the `/today` briefing page. A turn arriving from a chat adapter instead of the web app also carries a `<channel>` block naming the surface and stating which approvals can be completed there; on Slack the `<briefing>` digest is gated to the principal's DMs. All three ride in the **user turn**, never a cached system block. The server registers a stop switch under that id *before* the context fetch, so a Stop pressed during those first seconds halts the turn before any model call is made.\n2. **Tool-use loop** — the `Executive` calls Claude. For a cross-domain question the assistant turn emits multiple `consult_specialist` tool-use blocks at once.\n3. **Parallel fan-out** — `openexecutive.orchestrator.router.route_parallel` dispatches those calls concurrently, bounded by `MAX_PARALLEL_SPECIALISTS`; calls past the cap get a skip tool_result.\n4. **Per-specialist RAG** — each specialist runs its own domain-filtered ChromaDB query, then reasons over the retrieved chunks and returns analysis as a tool_result.\n5. **Synthesis** — the Executive feeds the tool_results back to Claude and streams one coherent reply. Every tool round — not just a specialist one — emits an `activity` event naming what is running, immediately followed by a `thinking` keepalive. The label names the *activity*, never the internal agent: \"Putting time on the calendar…\", \"Looking up people…\", or, for an MCP call, the underlying tool by name. A round that really does fan out collapses to the generic \"Consulting specialists…\" — the one voice holds even in the progress line. The keepalive carries no tool information of its own; it used to drive a hardcoded \"Consulting specialists…\" string, so an MCP or calendar round misreported itself as a fan-out.\n6. **Optional committee review** — when enabled, `Executive.stream_chat_with_committee()` runs a silent draft, parallel reviewer critiques, then a streamed revision pass.\n7. **Side effects** — after the reply, every rostered speaker's turn (not only the principal's) schedules a fire-and-forget **open-loop pass** (Attunement) beside the episodic extraction: a keyword prefilter, then one forced-tool call that may open or close loops, every item quote-gated against the speaker's own words. The user message is persisted with `sender_person_id` — the resolved speaker, never the principal fallback a Discord / Telegram session uses for ownership — and the session records the speaker for the turn (`Session.caller_person_id`), which `close_open_loop` reads. Any side-effecting tool call surfaces an `action_taken` chip, which unlike the ephemeral `activity` label is persisted with the assistant message; the stream closes with a `done` event — preceded by a `stopped` event when the user halted the turn, in which case the partial reply is still persisted and flagged so it reads as cut short rather than complete, and is mirrored into the live in-memory session so the next turn's prompt matches what was saved. The stream still ends with `done` event. One side-effecting tool is gated server-side rather than by its description: `ack_alert` will only accept an `alert_id` from the live alert board the server itself derived this turn — the whole live set, not only the rows the `<briefing>` digest printed, since `/today` renders more cards than the digest lists and every one of them is Discuss-able — and it fails closed, so an id it cannot even parse is refused rather than waved through to the handler's own parse. That check runs on **every** session. It used to run only on turns that arrived from a chat channel, keyed on `origin_channel`, which the browser never sets — so the web, the surface the principal actually uses, was unchecked and the model could ack any id, including one quoted out of an alert body by the briefing page's Discuss handoff. What that buys is bounded and worth stating plainly: an id that is invented, closed, snoozed or expired is refused, including one quoted out of an attacker-written alert body; the model being argued into acking the wrong *live* card is not prevented. The board is recorded on the turn's `Session`, and the route binds that session for the **whole** SSE body (`schedule_tools.set_session`, alongside `set_turn`) rather than letting `stream_chat` bind it from inside its own generator. `_sse_body` drives the executive with `asyncio.wait_for(stream.__anext__())`, which runs each step in a fresh Task holding a *copy* of the context, so a binding made inside the generator is discarded with the step that made it: step one sees the session and every later step sees `None`. The tool-call loop runs on those later steps, so the whole guard read an empty set and refused every ack on the web — on live, open cards — until the binding moved out to the route. Anything reading `current_session` mid-turn has the same requirement, and two of them needed more than the binding to behave. `schedule_followup`'s seen-`channel_ref` anti-spam gate refuses a send to an address the session has not seen; with no session it skipped itself, so a web turn could schedule to **any** address, and with an empty one it refused even the principal's own. The route now seeds the caller's own addresses onto the session, so on web the gate means what it means on every other surface. Reply linkage (`_record_outbound_context`, read back by `inbound_hydration` to quote the originating conversation into the turn handling a recipient's reply) is the other: it was never reachable on web, and rather than switch that on for the principal's broadest surface as a side effect it is held back, keyed on an explicit `Session.from_web_chat` flag. Not on an empty `origin_channel` — that names an inbound chat adapter, and the email poller, alert review, the CLI and the unattended workflows all leave it empty while legitimately recording linkage. `scheduled_actions` rows also take their `session_id` from the session. A session that was shown no board has an empty trusted set and can ack nothing, so the unattended passes (the nightly reflection, the research synthesis) are refused by default — they also still withhold the tool outright, which is belt-and-braces rather than the only thing stopping them. After the stream closes, the turn is also handed to the episodic memory extractor (`memory.episodic.schedule_extraction`, fire-and-forget) — on every turn where the principal said anything at all, and only the principal: a turn naming an `origin_channel` must resolve to a person marked `is_principal`, because the quote validator downstream cannot tell whose words it is checking. Both this path and the committee path call the same `should_extract` predicate, and it applies no length floor: the gate used to sum in the assistant's reply, which let a verbose answer drag a trivial turn in and discarded the short, decisive instructions that are the whole point of extracting. A user-side floor would fare no better — \"Do B.\" and \"Done\" are one character apart. See **Memory** for what that cost on a live tenant.\n8. **Tool failures** — a handler that raises instead of returning its JSON error is isolated: both tool gathers run with `return_exceptions=True`, the model gets an error `tool_result` naming only the exception's TYPE — a message can carry a filesystem path, a validation error echoing the input, or a third-party HTTP body, and anything in model context can be quoted back to the user, so the full repr stays in the log and the audit row — and the failure is audited with `ok=false`. Only `CancelledError` is re-raised, so turn-timeout and client-disconnect handling still work. Before this one crashing tool aborted the whole turn, which reached the user as an unexplained apology with no audit row (#136).\n\nWeb search, when invoked on the Anthropic path, executes inside the Anthropic API itself (`web_search_20250305`) and returns within the same generation; for any model routed via OpenRouter the same tool becomes OpenRouter's `openrouter:web_search` server tool, which also runs inside the generation with the same search cap and domain lists.",+ "markdown": "A single chat message makes a full round-trip through the API, the orchestrator's tool-use loop, a parallel specialist fan-out, and synthesis — all streamed back as server-sent events.\n\n### Steps\n\n1. **Arrival** — the client mints a `client_turn_id` and posts to `POST /chat` (`openexecutive.api.routes.chat`). The turn carries a `<current_speaker>` hint resolved from the caller's `person_id`, plus a `<briefing>` digest of current open alerts (built in parallel with RAG/episodic/peer-memory fetches) so the Executive can discuss any item shown on the `/today` briefing page. A turn arriving from a chat adapter instead of the web app also carries a `<channel>` block naming the surface and stating which approvals can be completed there; on Slack the `<briefing>` digest is gated to the principal's DMs. All three ride in the **user turn**, never a cached system block. The server registers a stop switch under that id *before* the context fetch, so a Stop pressed during those first seconds halts the turn before any model call is made.\n2. **Tool-use loop** — the `Executive` calls Claude. For a cross-domain question the assistant turn emits multiple `consult_specialist` tool-use blocks at once.\n3. **Parallel fan-out** — `openexecutive.orchestrator.router.route_parallel` dispatches those calls concurrently, bounded by `MAX_PARALLEL_SPECIALISTS`; calls past the cap get a skip tool_result.\n4. **Per-specialist RAG** — each specialist runs its own domain-filtered ChromaDB query, then reasons over the retrieved chunks and returns analysis as a tool_result.\n5. **Synthesis** — the Executive feeds the tool_results back to Claude and streams one coherent reply. Every tool round — not just a specialist one — emits an `activity` event naming what is running, immediately followed by a `thinking` keepalive. The label names the *activity*, never the internal agent: \"Putting time on the calendar…\", \"Looking up people…\", or, for an MCP call, the underlying tool by name. A round that really does fan out collapses to the generic \"Consulting specialists…\" — the one voice holds even in the progress line. The keepalive carries no tool information of its own; it used to drive a hardcoded \"Consulting specialists…\" string, so an MCP or calendar round misreported itself as a fan-out.\n6. **Optional committee review** — when enabled, `Executive.stream_chat_with_committee()` runs a silent draft, parallel reviewer critiques, then a streamed revision pass.\n7. **Side effects** — after the reply, every rostered speaker's turn (not only the principal's) schedules a fire-and-forget **open-loop pass** (Attunement) beside the episodic extraction: a keyword prefilter, then one forced-tool call that may open or close loops, every item quote-gated against the speaker's own words. The user message is persisted with `sender_person_id` — the resolved speaker, never the principal fallback a Discord / Telegram session uses for ownership — and the session records the speaker for the turn (`Session.caller_person_id`), which `close_open_loop` reads. A DM sent while proactive work is tagged (`attunement.outcomes.tag_proactive` — scheduler dispatch, reflection, research, alert review) also opens an outcome-ledger row at `_record_outbound_context`; a user's own turn is never tagged. Any side-effecting tool call surfaces an `action_taken` chip, which unlike the ephemeral `activity` label is persisted with the assistant message; the stream closes with a `done` event — preceded by a `stopped` event when the user halted the turn, in which case the partial reply is still persisted and flagged so it reads as cut short rather than complete, and is mirrored into the live in-memory session so the next turn's prompt matches what was saved. The stream still ends with `done` event. One side-effecting tool is gated server-side rather than by its description: `ack_alert` will only accept an `alert_id` from the live alert board the server itself derived this turn — the whole live set, not only the rows the `<briefing>` digest printed, since `/today` renders more cards than the digest lists and every one of them is Discuss-able — and it fails closed, so an id it cannot even parse is refused rather than waved through to the handler's own parse. That check runs on **every** session. It used to run only on turns that arrived from a chat channel, keyed on `origin_channel`, which the browser never sets — so the web, the surface the principal actually uses, was unchecked and the model could ack any id, including one quoted out of an alert body by the briefing page's Discuss handoff. What that buys is bounded and worth stating plainly: an id that is invented, closed, snoozed or expired is refused, including one quoted out of an attacker-written alert body; the model being argued into acking the wrong *live* card is not prevented. The board is recorded on the turn's `Session`, and the route binds that session for the **whole** SSE body (`schedule_tools.set_session`, alongside `set_turn`) rather than letting `stream_chat` bind it from inside its own generator. `_sse_body` drives the executive with `asyncio.wait_for(stream.__anext__())`, which runs each step in a fresh Task holding a *copy* of the context, so a binding made inside the generator is discarded with the step that made it: step one sees the session and every later step sees `None`. The tool-call loop runs on those later steps, so the whole guard read an empty set and refused every ack on the web — on live, open cards — until the binding moved out to the route. Anything reading `current_session` mid-turn has the same requirement, and two of them needed more than the binding to behave. `schedule_followup`'s seen-`channel_ref` anti-spam gate refuses a send to an address the session has not seen; with no session it skipped itself, so a web turn could schedule to **any** address, and with an empty one it refused even the principal's own. The route now seeds the caller's own addresses onto the session, so on web the gate means what it means on every other surface. Reply linkage (`_record_outbound_context`, read back by `inbound_hydration` to quote the originating conversation into the turn handling a recipient's reply) is the other: it was never reachable on web, and rather than switch that on for the principal's broadest surface as a side effect it is held back, keyed on an explicit `Session.from_web_chat` flag. Not on an empty `origin_channel` — that names an inbound chat adapter, and the email poller, alert review, the CLI and the unattended workflows all leave it empty while legitimately recording linkage. `scheduled_actions` rows also take their `session_id` from the session. A session that was shown no board has an empty trusted set and can ack nothing, so the unattended passes (the nightly reflection, the research synthesis) are refused by default — they also still withhold the tool outright, which is belt-and-braces rather than the only thing stopping them. After the stream closes, the turn is also handed to the episodic memory extractor (`memory.episodic.schedule_extraction`, fire-and-forget) — on every turn where the principal said anything at all, and only the principal: a turn naming an `origin_channel` must resolve to a person marked `is_principal`, because the quote validator downstream cannot tell whose words it is checking. Both this path and the committee path call the same `should_extract` predicate, and it applies no length floor: the gate used to sum in the assistant's reply, which let a verbose answer drag a trivial turn in and discarded the short, decisive instructions that are the whole point of extracting. A user-side floor would fare no better — \"Do B.\" and \"Done\" are one character apart. See **Memory** for what that cost on a live tenant.\n8. **Tool failures** — a handler that raises instead of returning its JSON error is isolated: both tool gathers run with `return_exceptions=True`, the model gets an error `tool_result` naming only the exception's TYPE — a message can carry a filesystem path, a validation error echoing the input, or a third-party HTTP body, and anything in model context can be quoted back to the user, so the full repr stays in the log and the audit row — and the failure is audited with `ok=false`. Only `CancelledError` is re-raised, so turn-timeout and client-disconnect handling still work. Before this one crashing tool aborted the whole turn, which reached the user as an unexplained apology with no audit row (#136).\n\nWeb search, when invoked on the Anthropic path, executes inside the Anthropic API itself (`web_search_20250305`) and returns within the same generation; for any model routed via OpenRouter the same tool becomes OpenRouter's `openrouter:web_search` server tool, which also runs inside the generation with the same search cap and domain lists.","mermaid": "sequenceDiagram\n participant C as Client\n participant API as FastAPI /chat\n participant E as Executive\n participant CL as Claude\n participant S as Specialists\n participant KB as ChromaDB\n C->>API: POST /chat message\n API->>E: start turn\n E->>CL: messages (tool-use loop)\n CL-->>E: consult_specialist calls\n E->>S: route_parallel fan-out\n S->>KB: domain-filtered RAG\n KB-->>S: chunks\n S-->>E: analysis tool_results\n E->>CL: synthesize\n CL-->>E: streamed reply\n E-->>API: SSE chunks then done\n API-->>C: streamed response",- "generated_at": "2026-09-22T21:20:28.764157+00:00"+ "generated_at": "2026-09-22T23:07:13.054261+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/memory.json b/packages/core/openexecutive/architecture/prebuilt/memory.jsonindex 39fb9b14..f5d393f4 100644--- a/packages/core/openexecutive/architecture/prebuilt/memory.json+++ b/packages/core/openexecutive/architecture/prebuilt/memory.json@@ -1,7 +1,7 @@{"section_id": "memory","title": "Memory System",- "markdown": "The Executive's durable memory is an episodic SQLite store at `./episodic_memory.db`, managed by `openexecutive.memory.episodic`. It holds four tables:\n\n- `decisions` — choices made, with `domain`, `summary`, `rationale`, `outcome`, and `tags`.\n- `initiatives` — tracked efforts with a `status` and `summary` (idempotent upserts).\n- `advice_given` — query/advice pairs per domain.\n- `scheduled_actions` — a dispatch queue, treated separately from recall memory.\n\n### What gets extracted, and when\n\n`episodic.extract_and_store` runs after a turn and asks a utility-fast model for decisions, initiatives and advice. Every candidate must carry a `user_commitment_quote` that appears verbatim in the principal's own message (`_is_valid_user_commitment`) — the model has repeatedly tried to log the Executive's *recommendations* as the user's commitments, and that quote is the hard gate against it.\n\nA turn reaches the extractor if `should_extract(user_message)` is true, which means only that the principal said something — there is deliberately **no length floor**. There used to be one, on the combined user+assistant length, and on a live tenant it selected almost exactly the wrong turns: 9 of 16 exchanges were blocked, and the 9 held every instruction the principal gave, while the 7 admitted were long analytical exchanges with no commitment in them. The extractor ran 13 times and stored nothing.\n\nMoving that floor to the user's side would relocate the bug, not fix it. The canonical executive decision is a long analysis answered with \"Approve option B.\" (17 chars) or \"Do B.\" (5), and any floor high enough to skip \"Done\" (4) also skips those — \"Do B.\" and \"Done\" differ by one character and mean opposite things. Length cannot separate a decision from an acknowledgement; the verbatim-quote check can, so `_is_valid_user_commitment` is the gate that decides. The price is one utility-fast call on turns that propose nothing.\n\nThat quote check is only meaningful when `user_message` holds the **principal's** words, and on a chat channel it does not — `Executive.chat()` is reached from Slack, Discord, Telegram, Google Chat and the email poller. A teammate's line would be written to `decisions` with no speaker attached, indistinguishable from the principal's own; an inbound email body is text the sender chose, so a self-quote is free. Removing the length floor is what makes this bite — short channel traffic used to fall under it incidentally — so `should_extract` also takes the turn's `origin_channel` and `person_id`. No channel means the web app, the CLI or the API, all of them the principal's own authenticated surfaces, where `person_id` is legitimately null in a single-user install. A turn that names a channel must resolve to a person marked `is_principal`, and an unresolvable speaker fails closed.\n\nEach pass writes a `memory_extraction` audit row — in a `finally`, so a pass that crashed is recorded too, with the exception type as its `failure` reason: how many items the model proposed, how many were stored, a `malformed` count so a pass where the model returned only garbage does not read as one that found nothing, and a `{kind, reason}` record per drop — `bad_quote` and `missing_field` for an item the model proposed, `not_a_list`, `item_not_a_dict` and `payload_not_a_dict` for a shape that was never a usable item. Every proposed item is either stored or dropped, so `proposed == stored + item drops` is the arithmetic that says whether anything was lost silently. The tool payload is not schema-checked anywhere, so a malformed shape is counted as a drop rather than raised — it used to abort the whole pass, discarding the other two kinds with it and suppressing the row, which read exactly like \"extraction never ran\". Without it, \"the model found nothing\" and \"the model found things and every one was rejected\" are indistinguishable from outside the database — which is why the failure above survived undetected and took a SQLite session on the tenant to find. A `proposed>0, stored=0` streak is the signal to watch.\n\nThe validator rejects a paraphrase, and the model paraphrases: on one install two of three real commitments were lost that way, the quote beginning \"SVN's engagement covers only …\" where the person had typed something else. So a `bad_quote` drop earns exactly one corrective call. The model is shown the rejected items and the quotes it gave, told to copy the span character-for-character (typos and casing included) or return empty arrays, and the tool is forced where the provider supports tool choice. Every retry item is validated first; a still-invalid one adds no second drop and is counted `still_invalid`. A valid item is then classified in order: its label matches a pending drop record → a recovery, stored and the record released; else its quote (terminal punctuation ignored) already supports a stored item of that kind → a re-send, ignored and counted `repeated`, so a model that re-sends everything cannot double-count `stored`; else a new proposal, stored and counted — a reworded label cannot be told from a different item, and crediting it would erase the very `bad_quote` census the row exists to show, so its original drop stands. Recovery is checked before re-send because two commitments can rest on one sentence. Malformed shapes at any level — a kind that is not a list, an item or payload that is not a dict, a response with no tool call — are counted `malformed`, so a retry that returned garbage does not read like one that obediently returned nothing. The row's `retry` block (`rejected`, `recovered`, `repeated`, `still_invalid`, `malformed`, `failure`) is always present, zeros when nothing was rejected; `rejected` is set from the complete drop list when the row is written, so neither a store failure before the retry nor a cancellation during it can zero it. The arithmetic above still holds after the retry. An exception on the retry is recorded as the retry's own `failure` and leaves the first pass's results untouched; the cost is one utility-model call, only on turns that dropped something. `memory_extraction` is a declared event type, so the audit page's filter can select it.\n\n### Session scoping\n\n`decisions` and `advice_given` rows carry a `session_id`, so per-thread channels (Discord, Telegram) can pull just-this-thread history without leaking cross-conversation context. A null `session_id` falls back to a global view.\n\n### Surfacing\n\n`openexecutive.memory.episodic.format_for_prompt` renders recent decisions and initiatives into a compact `<past_decisions>` block injected into the user turn — alongside `<retrieved_context>` and peer memory — never into a cached system block.\n\nThe chat route also injects a `<briefing>` block into the same user turn: a compact digest of the current open (unread) alerts, built by `openexecutive.briefing.context.format_open_alerts_for_prompt` (company-wide, `status=\"unread\"`, mirroring `/today`). This is what lets the Executive discuss a briefing item the principal clicked or named on `/today` (e.g. \"Gulf Coast Port Cyberattack\"). It is resolved in parallel with the other context fetches, omitted when there are no open alerts, and never placed in a cached system block.\n\nOn the Pulse page the Memory section shows the three lists as Decisions, Initiatives and Advice tabs, with a fourth **People** tab for peer memory (what Honcho has derived about each person, read-only, see the peer memory section). The header's Memories tile counts the three lists plus the peer notes, and says how many of the number are peer notes in its hint, since the People tab's badge counts people rather than notes.\n\n### System of record\n\nSQL is the system of record; the peer-memory service is a recall layer mirrored from it, not a replacement. When `store_decision` / `store_initiative` / `store_advice` insert a row whose `department` is non-empty and not `\"general\"`, the row is mirrored as a kind-tagged note into that department's peer via `append_department_note`. The mirror fires only after a successful INSERT, is fire-and-forget, and never rolls back the SQL row on peer-memory failure. `scheduled_actions` is never mirrored — it is a queue, not memory.\n\nThe episodic extractor still learns only from the principal's own words. Commitments and asks from everyone else on the roster are tracked as **open loops** (see Attunement) — `scheduled_actions` rows with `kind='open_loop'`, opened and closed by a separate quote-gated pass after each attributed turn. That pass depends on `chat_messages.sender_person_id`, which records who actually wrote each persisted user message. An open loop counts toward `list_awaiting_replies_by_person` only once it is due, and `list_scheduled_actions(exclude_internal=True)` filters `__internal__` rows in SQL so readers that want real sends are not starved by them.",+ "markdown": "The Executive's durable memory is an episodic SQLite store at `./episodic_memory.db`, managed by `openexecutive.memory.episodic`. It holds four tables:\n\n- `decisions` — choices made, with `domain`, `summary`, `rationale`, `outcome`, and `tags`.\n- `initiatives` — tracked efforts with a `status` and `summary` (idempotent upserts).\n- `advice_given` — query/advice pairs per domain.\n- `scheduled_actions` — a dispatch queue, treated separately from recall memory.\n\n### What gets extracted, and when\n\n`episodic.extract_and_store` runs after a turn and asks a utility-fast model for decisions, initiatives and advice. Every candidate must carry a `user_commitment_quote` that appears verbatim in the principal's own message (`_is_valid_user_commitment`) — the model has repeatedly tried to log the Executive's *recommendations* as the user's commitments, and that quote is the hard gate against it.\n\nA turn reaches the extractor if `should_extract(user_message)` is true, which means only that the principal said something — there is deliberately **no length floor**. There used to be one, on the combined user+assistant length, and on a live tenant it selected almost exactly the wrong turns: 9 of 16 exchanges were blocked, and the 9 held every instruction the principal gave, while the 7 admitted were long analytical exchanges with no commitment in them. The extractor ran 13 times and stored nothing.\n\nMoving that floor to the user's side would relocate the bug, not fix it. The canonical executive decision is a long analysis answered with \"Approve option B.\" (17 chars) or \"Do B.\" (5), and any floor high enough to skip \"Done\" (4) also skips those — \"Do B.\" and \"Done\" differ by one character and mean opposite things. Length cannot separate a decision from an acknowledgement; the verbatim-quote check can, so `_is_valid_user_commitment` is the gate that decides. The price is one utility-fast call on turns that propose nothing.\n\nThat quote check is only meaningful when `user_message` holds the **principal's** words, and on a chat channel it does not — `Executive.chat()` is reached from Slack, Discord, Telegram, Google Chat and the email poller. A teammate's line would be written to `decisions` with no speaker attached, indistinguishable from the principal's own; an inbound email body is text the sender chose, so a self-quote is free. Removing the length floor is what makes this bite — short channel traffic used to fall under it incidentally — so `should_extract` also takes the turn's `origin_channel` and `person_id`. No channel means the web app, the CLI or the API, all of them the principal's own authenticated surfaces, where `person_id` is legitimately null in a single-user install. A turn that names a channel must resolve to a person marked `is_principal`, and an unresolvable speaker fails closed.\n\nEach pass writes a `memory_extraction` audit row — in a `finally`, so a pass that crashed is recorded too, with the exception type as its `failure` reason: how many items the model proposed, how many were stored, a `malformed` count so a pass where the model returned only garbage does not read as one that found nothing, and a `{kind, reason}` record per drop — `bad_quote` and `missing_field` for an item the model proposed, `not_a_list`, `item_not_a_dict` and `payload_not_a_dict` for a shape that was never a usable item. Every proposed item is either stored or dropped, so `proposed == stored + item drops` is the arithmetic that says whether anything was lost silently. The tool payload is not schema-checked anywhere, so a malformed shape is counted as a drop rather than raised — it used to abort the whole pass, discarding the other two kinds with it and suppressing the row, which read exactly like \"extraction never ran\". Without it, \"the model found nothing\" and \"the model found things and every one was rejected\" are indistinguishable from outside the database — which is why the failure above survived undetected and took a SQLite session on the tenant to find. A `proposed>0, stored=0` streak is the signal to watch.\n\nThe validator rejects a paraphrase, and the model paraphrases: on one install two of three real commitments were lost that way, the quote beginning \"SVN's engagement covers only …\" where the person had typed something else. So a `bad_quote` drop earns exactly one corrective call. The model is shown the rejected items and the quotes it gave, told to copy the span character-for-character (typos and casing included) or return empty arrays, and the tool is forced where the provider supports tool choice. Every retry item is validated first; a still-invalid one adds no second drop and is counted `still_invalid`. A valid item is then classified in order: its label matches a pending drop record → a recovery, stored and the record released; else its quote (terminal punctuation ignored) already supports a stored item of that kind → a re-send, ignored and counted `repeated`, so a model that re-sends everything cannot double-count `stored`; else a new proposal, stored and counted — a reworded label cannot be told from a different item, and crediting it would erase the very `bad_quote` census the row exists to show, so its original drop stands. Recovery is checked before re-send because two commitments can rest on one sentence. Malformed shapes at any level — a kind that is not a list, an item or payload that is not a dict, a response with no tool call — are counted `malformed`, so a retry that returned garbage does not read like one that obediently returned nothing. The row's `retry` block (`rejected`, `recovered`, `repeated`, `still_invalid`, `malformed`, `failure`) is always present, zeros when nothing was rejected; `rejected` is set from the complete drop list when the row is written, so neither a store failure before the retry nor a cancellation during it can zero it. The arithmetic above still holds after the retry. An exception on the retry is recorded as the retry's own `failure` and leaves the first pass's results untouched; the cost is one utility-model call, only on turns that dropped something. `memory_extraction` is a declared event type, so the audit page's filter can select it.\n\n### Session scoping\n\n`decisions` and `advice_given` rows carry a `session_id`, so per-thread channels (Discord, Telegram) can pull just-this-thread history without leaking cross-conversation context. A null `session_id` falls back to a global view.\n\n### Surfacing\n\n`openexecutive.memory.episodic.format_for_prompt` renders recent decisions and initiatives into a compact `<past_decisions>` block injected into the user turn — alongside `<retrieved_context>` and peer memory — never into a cached system block.\n\nThe chat route also injects a `<briefing>` block into the same user turn: a compact digest of the current open (unread) alerts, built by `openexecutive.briefing.context.format_open_alerts_for_prompt` (company-wide, `status=\"unread\"`, mirroring `/today`). This is what lets the Executive discuss a briefing item the principal clicked or named on `/today` (e.g. \"Gulf Coast Port Cyberattack\"). It is resolved in parallel with the other context fetches, omitted when there are no open alerts, and never placed in a cached system block.\n\nOn the Pulse page the Memory section shows the three lists as Decisions, Initiatives and Advice tabs, with a fourth **People** tab for peer memory (what Honcho has derived about each person, read-only, see the peer memory section). The header's Memories tile counts the three lists plus the peer notes, and says how many of the number are peer notes in its hint, since the People tab's badge counts people rather than notes.\n\n### System of record\n\nSQL is the system of record; the peer-memory service is a recall layer mirrored from it, not a replacement. When `store_decision` / `store_initiative` / `store_advice` insert a row whose `department` is non-empty and not `\"general\"`, the row is mirrored as a kind-tagged note into that department's peer via `append_department_note`. The mirror fires only after a successful INSERT, is fire-and-forget, and never rolls back the SQL row on peer-memory failure. `scheduled_actions` is never mirrored — it is a queue, not memory.\n\nThe episodic extractor still learns only from the principal's own words. Commitments and asks from everyone else on the roster are tracked as **open loops** (see Attunement) — `scheduled_actions` rows with `kind='open_loop'`, opened and closed by a separate quote-gated pass after each attributed turn. That pass depends on `chat_messages.sender_person_id`, which records who actually wrote each persisted user message. An open loop counts toward `list_awaiting_replies_by_person` only once it is due, and `list_scheduled_actions(exclude_internal=True)` filters `__internal__` rows in SQL so readers that want real sends are not starved by them. `mark_outbound_context_consumed` also resolves the Attunement outcome row for that DM as `replied` — a matched reply is the clearest sign proactive outreach landed — and `store_initiative` / `update_initiative` on an existing initiative mark its check-in nudges `acted`.","mermaid": "flowchart TD\n Store[\"store_decision / store_initiative / store_advice\"]\n DB[\"episodic_memory.db<br/>decisions / initiatives<br/>advice_given / scheduled_actions\"]\n Fmt[\"format_for_prompt\"]\n Turn[\"User turn<br/>past_decisions block\"]\n Mirror[\"append_department_note\"]\n Peer[\"Department peer<br/>(Honcho)\"]\n Store --> DB\n DB --> Fmt\n Fmt --> Turn\n Store -->|\"dept set & not general\"| Mirror\n Mirror -->|\"fire-and-forget\"| Peer\n class Store entry\n class DB storage\n class Fmt compute\n class Turn hot\n class Peer external\n",- "generated_at": "2026-09-22T22:50:33.153068+00:00"+ "generated_at": "2026-09-22T23:17:20.508677+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/scheduler.json b/packages/core/openexecutive/architecture/prebuilt/scheduler.jsonindex a84dd654..18f578e7 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. A cadence definition may not contain an approval gate — a cron fire has no human to ask — and the runner now enforces that at execution too: it calls `workflows.gate.ensure_workflow_event`, which raises on a gate so the run is recorded as failed. It previously ignored the gate and stored a completed run with `\"(no artifact)\"` as its body, which looked like a success every period.\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). Rows left pending by the removed staff-onboarding kinds drain through that same `__internal__` short-circuit (marked done, no dispatch); the removed talent workflows' *ad-hoc* reminders sat on the principal's real DM channel instead, so a one-shot startup sweep (`memory.episodic.cancel_orphaned_talent_reminders`) cancels them — `ad_hoc`, no department, `pending` or `running`, matching the five generated reminder shapes (outreach, interview coordination, reference checks, onboarding check-in, offer expiry) — and clears the awaiting-reply flag on delivered ones so the nudge engine stops chasing them. The marker row in `app_migrations` is claimed first with `INSERT OR IGNORE` in the same transaction, so concurrent boots cannot double-run or crash. 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\nThe stale-commitment source also chases **open loops** (see Attunement): `scheduled_actions` rows with `kind='open_loop'`, recorded `done` on the `__internal__` channel so the runner never dispatches them, whose `awaiting_response_since` is the loop's *due time*. They are chased as soon as they are overdue — not after `NUDGE_COMMITMENT_STALE_DAYS` — with a check-in intent addressed to the loop's owner (which quotes only the owner's own verbatim words and tells the dispatching turn to treat them as data), through the same `prefer_channel_for` routing, availability windows and outbound guard. Until open loops existed nothing in production set `awaiting_response_since`, so this source had nothing to chase. Each scan first closes loops older than `ATTUNEMENT_LOOP_TTL_DAYS` (21) as `expired`.\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## 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. A cadence definition may not contain an approval gate — a cron fire has no human to ask — and the runner now enforces that at execution too: it calls `workflows.gate.ensure_workflow_event`, which raises on a gate so the run is recorded as failed. It previously ignored the gate and stored a completed run with `\"(no artifact)\"` as its body, which looked like a success every period.\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). Rows left pending by the removed staff-onboarding kinds drain through that same `__internal__` short-circuit (marked done, no dispatch); the removed talent workflows' *ad-hoc* reminders sat on the principal's real DM channel instead, so a one-shot startup sweep (`memory.episodic.cancel_orphaned_talent_reminders`) cancels them — `ad_hoc`, no department, `pending` or `running`, matching the five generated reminder shapes (outreach, interview coordination, reference checks, onboarding check-in, offer expiry) — and clears the awaiting-reply flag on delivered ones so the nudge engine stops chasing them. The marker row in `app_migrations` is claimed first with `INSERT OR IGNORE` in the same transaction, so concurrent boots cannot double-run or crash. 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\nThe stale-commitment source also chases **open loops** (see Attunement): `scheduled_actions` rows with `kind='open_loop'`, recorded `done` on the `__internal__` channel so the runner never dispatches them, whose `awaiting_response_since` is the loop's *due time*. They are chased as soon as they are overdue — not after `NUDGE_COMMITMENT_STALE_DAYS` — with a check-in intent addressed to the loop's owner (which quotes only the owner's own verbatim words and tells the dispatching turn to treat them as data), through the same `prefer_channel_for` routing, availability windows and outbound guard. Until open loops existed nothing in production set `awaiting_response_since`, so this source had nothing to chase. Each scan first closes loops older than `ATTUNEMENT_LOOP_TTL_DAYS` (21) as `expired`, then marks proactive outreach nobody answered within `ATTUNEMENT_IGNORE_AFTER_HOURS` as `ignored` in the outcome ledger. Ranking uses that ledger: a candidate whose person left their last five resolved nudges of that kind unanswered ranks after all others and waits three times its cooldown; a single answer lifts it. Approving a stalled run (however it's approved) and updating an initiative count as acting on the nudges that chased them. The generic dispatch path tags each send with its source (`_outreach_source`) so the ledger can attribute it.\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## 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-22T22:50:33.153068+00:00"+ "generated_at": "2026-09-22T23:17:20.508677+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/schemas.json b/packages/core/openexecutive/architecture/prebuilt/schemas.jsonindex f298e520..2dddf5b1 100644--- a/packages/core/openexecutive/architecture/prebuilt/schemas.json+++ b/packages/core/openexecutive/architecture/prebuilt/schemas.json@@ -1,7 +1,7 @@{"section_id": "schemas","title": "Data Schemas",- "markdown": "The shapes below are the load-bearing data structures: episodic SQLite tables (in `episodic_memory.db`) and the Pydantic models for departments and people.\n\n### Episodic tables\n\n| Table | Key columns |\n|---|---|\n| `decisions` | `id`, `timestamp`, `domain`, `summary`, `rationale`, `outcome`, `tags`, `department`, `session_id` |\n| `initiatives` | `id`, `title`, `status`, `created_at`, `updated_at`, `summary`, `department` |\n| `advice_given` | `id`, `timestamp`, `domain`, `query_summary`, `advice_summary`, `department`, `session_id` |\n| `scheduled_actions` | `id`, `created_at`, `run_at`, `channel`, `channel_ref`, `intent_text`, `status`, `attempts`, `kind`, `department`, `assigned_to_person_id`, `awaiting_response_since`, `scope_key`, `required_scope` |\n| `outbound_context` | `id`, `created_at`, `channel`, `channel_ref`, `recipient_person_id`, `outbound_text`, `originating_session_id`, `outbound_message_id`, `consumed_at`, `status` |\n| `chat_messages` | `id`, `session_id`, `role`, `content`, `created_at`, `action_chips`, `stopped`, `sender_person_id`, `feedback`, `feedback_note` |\n| `attunement_usage` | `day` (PK, UTC date), `calls` — the per-day ceiling on open-loop extraction model calls |\n\n| `dynamic_workflows` | `name` (PK), `definition` (JSON of `DynamicWorkflowDef`), `is_active`, `created_at`, `updated_at` |\n| `app_migrations` | `name` (PK), `applied_at` — one-shot data migrations (sweeps that must run exactly once per DB); schema DDL stays idempotent and is not recorded here |\n\n`department` and `session_id` are additive columns (default `''`); `session_id` scopes per-thread recall. `scheduled_actions.status` ∈ pending / running / done / failed / cancelled, and `scheduled_actions.kind` includes `dynamic_workflow` (a cadence-fired user-created workflow run) and `open_loop` (an Attunement open loop: `assigned_to_person_id` is the owner, `awaiting_response_since` the due time — cleared when the loop closes — and `scope_key` `loop:{owner}:{hash}`, unique among open loops via the partial index `idx_scheduled_open_loop_scope`). `chat_messages.sender_person_id` is the resolved rostered sender of a user message (never the session owner's principal fallback; NULL on legacy rows and for unrostered senders); `feedback` is `up` / `down` on an assistant reply. `dynamic_workflows` stores user-created (dynamic) workflow definitions interpreted by the generic `DynamicWorkflow` engine; the JSON `definition` holds free-text input fields and an ordered step list (specialist / approval_gate / synthesis) plus an optional cadence.\n\n### Legacy tables (talent / staff onboarding)\n\nThe talent (executive-search) and staff-onboarding features were removed. Their tables —\n`engagements`, `candidates`, `offers`, `onboarding_templates`, `onboarding_plans`,\n`onboarding_tasks` — are **not dropped**: no code creates, reads or writes them any more,\nbut rows survive on upgraded installs. `clients.slots` still wipes them when a blank client\nslot is activated (existence-guarded, a no-op on fresh installs) so a slot can never inherit\na previous client's candidate data.\n\n### Department / Goal / ChecklistItem\n\n| Model | Fields |\n|---|---|\n| `DepartmentConfig` | `slug`, `title`, `specialist_key`, `charter`, `authority_level`, `head_person_id`, `head_persona_slug`, `cadences`, `slack_channel_id`, `discord_channel_id`, `telegram_chat_id` |\n| `Goal` | `id`, `department_slug`, `period_type`, `period_value`, `key_result`, `target`, `current`, `status`, `created_at`, `updated_at`, `last_reviewed_at` |\n| `DepartmentState` | `config`, `goals`, `headcount`, `budget_usd`, `member_person_ids`, `updated_at` |\n\n`authority_level` ∈ `auto_execute` / `propose_only` / `escalate`; `Goal.status` ∈ `on_track` / `at_risk` / `off_track`.\n\n### Person\n\n| Field group | Fields |\n|---|---|\n| Identity | `id`, `full_name`, `role`, `is_principal`, `department_slugs` |\n| Contact | `email`, `slack_user_id`, `telegram_chat_id`, `discord_user_id`, `preferred_channel` |\n| Routing | `availability`, `authority_scope`, `response_sla_hours`, `on_leave_until`, `reports_to_person_id` |\n| Lifecycle | `archived`, `created_at`, `updated_at` |\n\nExactly one `Person` should have `is_principal=True` — the fallback approver when no delegated person matches.",+ "markdown": "The shapes below are the load-bearing data structures: episodic SQLite tables (in `episodic_memory.db`) and the Pydantic models for departments and people.\n\n### Episodic tables\n\n| Table | Key columns |\n|---|---|\n| `decisions` | `id`, `timestamp`, `domain`, `summary`, `rationale`, `outcome`, `tags`, `department`, `session_id` |\n| `initiatives` | `id`, `title`, `status`, `created_at`, `updated_at`, `summary`, `department` |\n| `advice_given` | `id`, `timestamp`, `domain`, `query_summary`, `advice_summary`, `department`, `session_id` |\n| `scheduled_actions` | `id`, `created_at`, `run_at`, `channel`, `channel_ref`, `intent_text`, `status`, `attempts`, `kind`, `department`, `assigned_to_person_id`, `awaiting_response_since`, `scope_key`, `required_scope` |\n| `outbound_context` | `id`, `created_at`, `channel`, `channel_ref`, `recipient_person_id`, `outbound_text`, `originating_session_id`, `outbound_message_id`, `consumed_at`, `status` |\n| `chat_messages` | `id`, `session_id`, `role`, `content`, `created_at`, `action_chips`, `stopped`, `sender_person_id`, `feedback`, `feedback_note` |\n| `attunement_usage` | `day` (PK, UTC date), `calls` — the per-day ceiling on open-loop extraction model calls |\n| `proactive_outcomes` | `id`, `created_at`, `person_id`, `source`, `ref`, `channel`, `channel_ref`, `outbound_context_id`, `outcome` (`replied` / `acted` / `ignored` / `void`, NULL while open), `resolved_at` — one row per proactive DM (Attunement outcome ledger) |\n\n| `dynamic_workflows` | `name` (PK), `definition` (JSON of `DynamicWorkflowDef`), `is_active`, `created_at`, `updated_at` |\n| `app_migrations` | `name` (PK), `applied_at` — one-shot data migrations (sweeps that must run exactly once per DB); schema DDL stays idempotent and is not recorded here |\n\n`department` and `session_id` are additive columns (default `''`); `session_id` scopes per-thread recall. `scheduled_actions.status` ∈ pending / running / done / failed / cancelled, and `scheduled_actions.kind` includes `dynamic_workflow` (a cadence-fired user-created workflow run) and `open_loop` (an Attunement open loop: `assigned_to_person_id` is the owner, `awaiting_response_since` the due time — cleared when the loop closes — and `scope_key` `loop:{owner}:{hash}`, unique among open loops via the partial index `idx_scheduled_open_loop_scope`). `chat_messages.sender_person_id` is the resolved rostered sender of a user message (never the session owner's principal fallback; NULL on legacy rows and for unrostered senders); `feedback` is `up` / `down` on an assistant reply. `dynamic_workflows` stores user-created (dynamic) workflow definitions interpreted by the generic `DynamicWorkflow` engine; the JSON `definition` holds free-text input fields and an ordered step list (specialist / approval_gate / synthesis) plus an optional cadence.\n\n### Legacy tables (talent / staff onboarding)\n\nThe talent (executive-search) and staff-onboarding features were removed. Their tables —\n`engagements`, `candidates`, `offers`, `onboarding_templates`, `onboarding_plans`,\n`onboarding_tasks` — are **not dropped**: no code creates, reads or writes them any more,\nbut rows survive on upgraded installs. `clients.slots` still wipes them when a blank client\nslot is activated (existence-guarded, a no-op on fresh installs) so a slot can never inherit\na previous client's candidate data.\n\n### Department / Goal / ChecklistItem\n\n| Model | Fields |\n|---|---|\n| `DepartmentConfig` | `slug`, `title`, `specialist_key`, `charter`, `authority_level`, `head_person_id`, `head_persona_slug`, `cadences`, `slack_channel_id`, `discord_channel_id`, `telegram_chat_id` |\n| `Goal` | `id`, `department_slug`, `period_type`, `period_value`, `key_result`, `target`, `current`, `status`, `created_at`, `updated_at`, `last_reviewed_at` |\n| `DepartmentState` | `config`, `goals`, `headcount`, `budget_usd`, `member_person_ids`, `updated_at` |\n\n`authority_level` ∈ `auto_execute` / `propose_only` / `escalate`; `Goal.status` ∈ `on_track` / `at_risk` / `off_track`.\n\n### Person\n\n| Field group | Fields |\n|---|---|\n| Identity | `id`, `full_name`, `role`, `is_principal`, `department_slugs` |\n| Contact | `email`, `slack_user_id`, `telegram_chat_id`, `discord_user_id`, `preferred_channel` |\n| Routing | `availability`, `authority_scope`, `response_sla_hours`, `on_leave_until`, `reports_to_person_id` |\n| Lifecycle | `archived`, `created_at`, `updated_at` |\n\nExactly one `Person` should have `is_principal=True` — the fallback approver when no delegated person matches.","mermaid": null,- "generated_at": "2026-09-22T21:20:28.764157+00:00"+ "generated_at": "2026-09-22T23:17:20.508677+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/today.json b/packages/core/openexecutive/architecture/prebuilt/today.jsonindex 9ff210a3..60750bad 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). That digest (`briefing.context.format_open_alerts_for_prompt`) is capped at 30 items; when the board is longer the header says so explicitly and tells the Executive to point at this page for the rest — it previously presented the capped list as the complete board, so the Executive described a slice as everything that was open (#136). Chat adapters get the digest too, but Slack gates it to the principal's DMs: the board is company-wide and must not be pulled into a shared channel. The `[alert_id]` at the start of each line is also what `ack_alert` trusts, because an id quoted inside an alert's own body came from inbound mail or chat and is attacker-controlled. This page's `[Discuss mode — alert_id=N]` handoff primer is a pointer to which item is under discussion, not authority on its own: the server accepts it only if that id is on the live board too. Two things enforce that. Every field the digest interpolates — headline, body, suggested action, tags, review note — is collapsed to a single line, since a newline in any of them would forge a whole extra `[N]` line and with it a fabricated instruction to clear someone else's alert. And the server records the live board it derived, so `ack_alert` refuses any id outside it — on **every** session, not just the chat adapters. The recorded set is the whole live board, not just the rows the digest printed, so a card past the render cap stays ackable. The control stops invented, closed, snoozed and expired ids; it does not stop the model being argued into acking the wrong *live* card. That check used to run only when `origin_channel` was set, which the browser never sets, so the one surface where the principal actually reads their board had no check at all and the model could ack any id, including one quoted out of an alert body by the Discuss handoff. Rendering the block and recording its ids now happen together in `briefing.context.render_and_trust`, which both the web chat route and the channel adapters call: render without recording and the tool refuses everything, record without rendering and the model gets reach it was never shown. A turn that was shown nothing trusts nothing. Recording it is only half the wiring: the tool reads the board off the turn's session through a ContextVar, and the chat route binds that session for the whole SSE body (`set_session`, next to `set_turn`). Bound from inside the Executive's own generator instead, it survives exactly one stream step — `asyncio.wait_for` runs each step in a fresh Task with a copy of the context — and the tool-call loop, which runs later, sees nothing. That shipped, and every web ack was refused on cards that were open the whole time. The digest also carries a short **already handled** tail — recently acked / dismissed / resolved rows, named but deliberately NOT trusted for acking — because a card cleared on the page minutes ago is otherwise simply absent from chat: asked to \"record that as fixed\", the Executive could not tell a settled item from one it had never heard of, and sent the principal back to dismiss a card that was already gone. That tail renders even when nothing is open, which is exactly when it matters. Note it is a different window from the `handled_overnight` rail above: that one runs since the last delivered morning brief, while the chat tail looks back 14 days (matching the action-alert TTL, so it still covers an item cleared late in its life), so chat can name a settled item the rail no longer shows. The narrative is held to what is **live**, and to what it is actually for. The `alert_raised` source is dropped from the activity it reasons over (`_build_activity(..., include_alert_raised=False)`): a closed alert reads as work the principal already settled, and a *live* one is worse than redundant — `lifecycle.is_live` is the very predicate behind `list_live_alerts`, so every live raise is already a proposal card below the header, which the prompt forbids re-listing. The `/today/activity` rail keeps the whole source, because a raise really happened. The activity block is only labelled \"since last brief\" when the caller bounded it with `since` (the standalone briefs do; the header does not), since calling an unbounded history rail a delta made the header present weeks-old rows as overnight news. When the viewer's slice holds nothing that wants a decision — no action proposal, no at-risk/off-track department, nobody awaiting — the regen skips the model call entirely and writes the fixed quiet line (`Quiet right now — nothing pressing.`, or `… nothing needs you.` for a teammate). **The cache key is a hash of the rendered context itself** (`today._narrative_context` builds it once and both the hot path and the background task key off that one string, which is also handed to the model verbatim). That makes the key a function of the model's input: everything the prompt renders is covered, and nothing it omits can trigger a regeneration. Keying on hand-picked fields broke one half or the other each time — headlines alone left the rendered activity block uncovered, while the proposals' review fields are never rendered by this header yet are rewritten with fresh prose by every `alerts.review` pass, so they regenerated each viewer's narrative several times a day to re-synthesize identical input. A quiet board keys off a fixed sentinel instead, so a moving rail cannot re-key an entry whose text is constant. Together: on a fully dismissed board every other input was empty, the rail became the only context, and the model synthesized a confident header out of closed items.\n- **`in_flight`** / **`awaiting`** — upcoming Executive commitments and people we are waiting on.\n- **`handled_overnight`** — the autonomous moves the Executive *completed* since the last delivered morning brief: the alert review's (routed, nudged, escalated, drafted, merged, closed) 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`). A `changed` verdict (the review rewrote an open alert's headline / body / severity) is deliberately **not** here: the alert is still open in \"Needs you\" and its card carries the note, so the brief reports it under \"what changed\" (a REWRITTEN block) rather than as done. Each row is structured, not just a sentence: `kind`, the audit `summary` (nudge bookkeeping marker stripped), `at`, `alert_id`, `event_type` (for a pre-filtered `/audit` deep link), `headline` (the alert's headline at move time; a watch's slug), `target` (person name for routed / nudged, survivor headline for merged, new severity for escalated, draft title, workflow name), `detail` (the cited evidence or the watch policy's reason), `outcome` (`resolved` | `dismissed` for a close, `proposed` for a route that went through the authority gate), `evidence_ref` (S1 / R2 / A3), `superseded_by_alert_id`, and `status` — the alert's lifecycle state **now** (`open` = live in the queue per `lifecycle.is_live` | `resolved` | `dismissed` | `expired` | `merged` | `acked` | `inactive` for snoozed / past-TTL rows), looked up per row so a close the principal already undid renders as reopened instead of offering a second Undo, and a \"still open\" jump link only appears when there is a card to land on. The morning brief also carries a one-line count of research watch suggestions waiting on `/watchlist`.\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 rail (anchor of the \"Executive handled N overnight\" pill) is deliberately one sentence by default: a first-person heading built from counts only — \"Since your last brief: N off your plate (closes still standing, and merges whose survivor is not itself listed; a merge into a listed survivor counts on that survivor's row), N in others' hands (routed / nudged), N waiting on you (escalated)\", plus \"N drafts ready\", \"N workflows suggested\", \"N watch changes\", \"N other moves\" (a kind the UI does not know) and \"N back on your plate\" (a close that is open again) when present — with the rows behind a \"details\" disclosure, and nothing rendered at all when the grouped rows are empty. The pure logic (grouping, headline, links) lives in `packages/ui/src/lib/handled.ts` and is covered by `npm test`. Expanded, it shows one first-person row per alert (\"Resolved *X* — evidence\", \"Dismissed *X* as stale — evidence\", \"Handed *X* to Dana Kim\" / \"Proposed *X* to Dana Kim (awaiting their approval)\", \"Chased Dana Kim on *X*\", \"Raised *X* to high\", \"Drafted *T* from *X*\", \"Folded *X* into *Y*\", \"Started watching *slug*\"), escalations first; rows sharing an alert collapse to the newest move with the others as an \"also …\" trailer — a close always keeps the visible slot (it carries Undo), otherwise an escalation beats routed / nudged / drafted; a merge whose survivor is listed becomes \"N duplicates folded in\" on the survivor. Every row links its `evidence_ref` (or \"evidence\") to `/audit?event_type=…&q=…` (the audit page pre-fills those filters from the query string), a still-open row jumps to its card (`#alert-<id>`), drafted rows link `/artifacts`, watch rows `/watchlist`. Undo is offered only while the close still stands (`status` not `open`); a reverted close shows \"Reopened\". 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). That digest (`briefing.context.format_open_alerts_for_prompt`) is capped at 30 items; when the board is longer the header says so explicitly and tells the Executive to point at this page for the rest — it previously presented the capped list as the complete board, so the Executive described a slice as everything that was open (#136). Chat adapters get the digest too, but Slack gates it to the principal's DMs: the board is company-wide and must not be pulled into a shared channel. The `[alert_id]` at the start of each line is also what `ack_alert` trusts, because an id quoted inside an alert's own body came from inbound mail or chat and is attacker-controlled. This page's `[Discuss mode — alert_id=N]` handoff primer is a pointer to which item is under discussion, not authority on its own: the server accepts it only if that id is on the live board too. Two things enforce that. Every field the digest interpolates — headline, body, suggested action, tags, review note — is collapsed to a single line, since a newline in any of them would forge a whole extra `[N]` line and with it a fabricated instruction to clear someone else's alert. And the server records the live board it derived, so `ack_alert` refuses any id outside it — on **every** session, not just the chat adapters. The recorded set is the whole live board, not just the rows the digest printed, so a card past the render cap stays ackable. The control stops invented, closed, snoozed and expired ids; it does not stop the model being argued into acking the wrong *live* card. That check used to run only when `origin_channel` was set, which the browser never sets, so the one surface where the principal actually reads their board had no check at all and the model could ack any id, including one quoted out of an alert body by the Discuss handoff. Rendering the block and recording its ids now happen together in `briefing.context.render_and_trust`, which both the web chat route and the channel adapters call: render without recording and the tool refuses everything, record without rendering and the model gets reach it was never shown. A turn that was shown nothing trusts nothing. Recording it is only half the wiring: the tool reads the board off the turn's session through a ContextVar, and the chat route binds that session for the whole SSE body (`set_session`, next to `set_turn`). Bound from inside the Executive's own generator instead, it survives exactly one stream step — `asyncio.wait_for` runs each step in a fresh Task with a copy of the context — and the tool-call loop, which runs later, sees nothing. That shipped, and every web ack was refused on cards that were open the whole time. The digest also carries a short **already handled** tail — recently acked / dismissed / resolved rows, named but deliberately NOT trusted for acking — because a card cleared on the page minutes ago is otherwise simply absent from chat: asked to \"record that as fixed\", the Executive could not tell a settled item from one it had never heard of, and sent the principal back to dismiss a card that was already gone. That tail renders even when nothing is open, which is exactly when it matters. Note it is a different window from the `handled_overnight` rail above: that one runs since the last delivered morning brief, while the chat tail looks back 14 days (matching the action-alert TTL, so it still covers an item cleared late in its life), so chat can name a settled item the rail no longer shows. The narrative is held to what is **live**, and to what it is actually for. The `alert_raised` source is dropped from the activity it reasons over (`_build_activity(..., include_alert_raised=False)`): a closed alert reads as work the principal already settled, and a *live* one is worse than redundant — `lifecycle.is_live` is the very predicate behind `list_live_alerts`, so every live raise is already a proposal card below the header, which the prompt forbids re-listing. The `/today/activity` rail keeps the whole source, because a raise really happened. The activity block is only labelled \"since last brief\" when the caller bounded it with `since` (the standalone briefs do; the header does not), since calling an unbounded history rail a delta made the header present weeks-old rows as overnight news. When the viewer's slice holds nothing that wants a decision — no action proposal, no at-risk/off-track department, nobody awaiting — the regen skips the model call entirely and writes the fixed quiet line (`Quiet right now — nothing pressing.`, or `… nothing needs you.` for a teammate). **The cache key is a hash of the rendered context itself** (`today._narrative_context` builds it once and both the hot path and the background task key off that one string, which is also handed to the model verbatim). That makes the key a function of the model's input: everything the prompt renders is covered, and nothing it omits can trigger a regeneration. Keying on hand-picked fields broke one half or the other each time — headlines alone left the rendered activity block uncovered, while the proposals' review fields are never rendered by this header yet are rewritten with fresh prose by every `alerts.review` pass, so they regenerated each viewer's narrative several times a day to re-synthesize identical input. A quiet board keys off a fixed sentinel instead, so a moving rail cannot re-key an entry whose text is constant. Together: on a fully dismissed board every other input was empty, the rail became the only context, and the model synthesized a confident header out of closed items.\n- **`in_flight`** / **`awaiting`** — upcoming Executive commitments and people we are waiting on.\n- **`handled_overnight`** — the autonomous moves the Executive *completed* since the last delivered morning brief: the alert review's (routed, nudged, escalated, drafted, merged, closed) 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`). A `changed` verdict (the review rewrote an open alert's headline / body / severity) is deliberately **not** here: the alert is still open in \"Needs you\" and its card carries the note, so the brief reports it under \"what changed\" (a REWRITTEN block) rather than as done. Each row is structured, not just a sentence: `kind`, the audit `summary` (nudge bookkeeping marker stripped), `at`, `alert_id`, `event_type` (for a pre-filtered `/audit` deep link), `headline` (the alert's headline at move time; a watch's slug), `target` (person name for routed / nudged, survivor headline for merged, new severity for escalated, draft title, workflow name), `detail` (the cited evidence or the watch policy's reason), `outcome` (`resolved` | `dismissed` for a close, `proposed` for a route that went through the authority gate), `evidence_ref` (S1 / R2 / A3), `superseded_by_alert_id`, and `status` — the alert's lifecycle state **now** (`open` = live in the queue per `lifecycle.is_live` | `resolved` | `dismissed` | `expired` | `merged` | `acked` | `inactive` for snoozed / past-TTL rows), looked up per row so a close the principal already undid renders as reopened instead of offering a second Undo, and a \"still open\" jump link only appears when there is a card to land on. The morning brief also carries a one-line count of research watch suggestions waiting on `/watchlist`.\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 rail (anchor of the \"Executive handled N overnight\" pill) is deliberately one sentence by default: a first-person heading built from counts only — \"Since your last brief: N off your plate (closes still standing, and merges whose survivor is not itself listed; a merge into a listed survivor counts on that survivor's row), N in others' hands (routed / nudged), N waiting on you (escalated)\", plus \"N drafts ready\", \"N workflows suggested\", \"N watch changes\", \"N other moves\" (a kind the UI does not know) and \"N back on your plate\" (a close that is open again) when present — with the rows behind a \"details\" disclosure, and nothing rendered at all when the grouped rows are empty. The pure logic (grouping, headline, links) lives in `packages/ui/src/lib/handled.ts` and is covered by `npm test`. Expanded, it shows one first-person row per alert (\"Resolved *X* — evidence\", \"Dismissed *X* as stale — evidence\", \"Handed *X* to Dana Kim\" / \"Proposed *X* to Dana Kim (awaiting their approval)\", \"Chased Dana Kim on *X*\", \"Raised *X* to high\", \"Drafted *T* from *X*\", \"Folded *X* into *Y*\", \"Started watching *slug*\"), escalations first; rows sharing an alert collapse to the newest move with the others as an \"also …\" trailer — a close always keeps the visible slot (it carries Undo), otherwise an escalation beats routed / nudged / drafted; a merge whose survivor is listed becomes \"N duplicates folded in\" on the survivor. Every row links its `evidence_ref` (or \"evidence\") to `/audit?event_type=…&q=…` (the audit page pre-fills those filters from the query string), a still-open row jumps to its card (`#alert-<id>`), drafted rows link `/artifacts`, watch rows `/watchlist`. Undo is offered only while the close still stands (`status` not `open`); a reverted close shows \"Reopened\". 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`. Acknowledging or resolving an alert — including the review closing it itself — marks the review's DMs about it `acted` in the Attunement outcome ledger, for the person it is routed to and the principal only; dismissing it or finding it stale voids them (counted neither way). Review DMs are tagged `alert_review` with `alert:<id>`.\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 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 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 NARR compute\n class MB compute",- "generated_at": "2026-09-18T20:28:52.031310+00:00"+ "generated_at": "2026-09-22T23:17:20.508677+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/workflows.json b/packages/core/openexecutive/architecture/prebuilt/workflows.jsonindex 41c8f49d..90eae510 100644--- a/packages/core/openexecutive/architecture/prebuilt/workflows.json+++ b/packages/core/openexecutive/architecture/prebuilt/workflows.json@@ -1,7 +1,7 @@{"section_id": "workflows","title": "Workflows",- "markdown": "Workflows are deterministic, multi-step orchestrations. The built-ins are registered in `openexecutive.workflows.WORKFLOW_REGISTRY`; user-created (dynamic) workflows are stored as data (see below). Each follows the same contract: structured input feeds an ordered list of named steps that render a Markdown artifact, persisted via `complete_run` into `workflow_runs.artifact`. Every step emits a `WorkflowEvent` (start/progress/complete) streamed over SSE at `/workflows/{name}/runs`.\n\nThe registry holds 24 built-in workflows, plus any number of user-created ones. Representative built-ins:\n\n- `board_prep`, `quarterly_plan`, `annual_plan` — planning and governance deliverables.\n- `performance_review`, `comp_refresh`, `org_design`, `exec_search_brief` — people and org artifacts (the last is an advisory hiring brief / scorecard from the CHRO, kept when the recruiting pipeline was removed).\n- `crisis_comms`, `churn_deep_dive`, `competitive_teardown` — situational analyses.\n- `department_check_in` — runs on department cadence; its `goal_status` step returns structured verdicts persisted back to `department_goals.status`.\n\n### Change-aware principal briefs\n\n`morning_brief` and `end_of_day_digest` are the two recurring briefs the scheduler DMs to the principal. Both are now a *delta*, not a re-list: the window is \"since the last **delivered** brief\" (`briefing.brief_state.since_for`; 24 h on a cold store, clamped to 7 days), activity comes from `_build_activity(limit, since=…)`, proposals (action category only) split into *new since last brief* — enumerated, with each item's why-now and next move — versus a one-line carried-over count, a *rewritten* block lists carried items the review rewrote inside the window (`brief_state.rewritten_since`: verdict `changed`, still open — the brief reports them under \"what changed\", never as done), and a *handled overnight* block lists what the Executive's alert review **completed** on its own (`brief_state.handled_since`; the `changed` verdict is excluded because the alert is still open). Section order: top call → what changed → handled overnight → needs you (new only) → waiting on → at risk. A date-free fingerprint of the inputs is compared to the last delivered one; if unchanged the artifact is the one-liner \"Nothing new since yesterday's brief — N items still waiting on you.\" and no model call is made (`PRINCIPAL_BRIEF_SUPPRESS_UNCHANGED`; `force_full=true` on a manual run bypasses it). The workflow yields a `result` event with the fingerprint; only the scheduler records it, after a successful delivery, in `briefing_narrative` under scope `brief:<kind>` — so manual runs never advance the window.\n\nNeither the nightly reflection nor the research synthesis can call `ack_alert`: both run unattended with open alerts rendered into their context, and those headlines are minted from inbound mail and chat, so an injected \"the principal already dismissed 13\" would be acted on with nobody watching. Closing an alert is the alert review's job, with evidence.\n\n`executive_reflection` now carries memory: yesterday's standup (the previous completed run's artifact) is rendered into the context and the prompt forbids re-acting on anything listed there unless it changed; open alerts render with their id, review verdict and recommended move. Reflection never closes alerts — the alert review does, with evidence. It also renders an **OPEN LOOPS** block (up to 10, soonest due first, overdue flagged) from Attunement so the standup can connect a slipped promise to the rest of the org state; the nudge engine already chases overdue loops, so the prompt tells it not to DM about a loop merely for being overdue. `close_open_loop` is withheld from reflection for the same reason as `ack_alert`: loop text is quoted from what people wrote.\n\n### Wait-for-human pause\n\n`wait_for_human` (`openexecutive/workflows/wait_for_human.py`) is a first-class step primitive that pauses a run: the runner calls `save_checkpoint`, the `workflow_runs` row moves to `status='awaiting_human'`, and the serialized `WaitForHumanEvent` is stored in `state_json`. (Department authority is a *separate* mechanism — `propose_only` departments file a briefing alert via `departments.authority.propose_via_alert` and mark the scheduled action done; they do not route through this gate.)\n\n**Delivery.** Both checkpoint sites — the SSE route and the `run_workflow` chat tool — call `workflows.gate_delivery.deliver_gate_question` immediately *before* checkpointing, so `state_json` carries the routing fields a reply is matched against. Two modes. When the approver is the person already in the conversation (the chat session's `origin_channel` is set and its `caller_person_id` is the gate's `person_id`), nothing is sent — the question rides in the Executive's own reply — and the gate records `origin_session_id` plus the session's channel. Otherwise the question is delivered through `schedule_tools.handle_message_person`, which picks the person's preferred channel, falls through on a failed send, and falls back to a briefing alert; the gate then records the channel, address and provider message id that send returned, plus the id of the DM session it landed in — that send is always 1:1, so the answer belongs in that conversation and nowhere else. Without it the gate matched on person and channel alone, so an unrelated @mention in a public channel resolved it and had the acknowledgement, run title included, posted where everyone could read it. Delivery is not guaranteed: the outbound guard can suppress it (duplicate, rate cap, quiet hours) and an unreachable person gets the alert fallback. Both cases leave the routing fields empty and report `delivery` as `suppressed` / `alerted` rather than claiming someone was asked, and the chat tool's presentation hint changes accordingly.\n\n**Matching a reply.** Each inbound adapter passes the message to `inbound_resolver.resolve_inbound_message` with its `session_id`. Matching is three-tier: an explicit `in_reply_to` against a stored `outbound_message_id`; otherwise a single open run on that channel; otherwise one utility-fast disambiguation call gated at 0.85 confidence. An unmatched explicit reference rules out only the candidates that carry a stored outbound id — the ones it could have matched — and the rest continue; rejecting outright meant an adapter that passes a thread id on every message (Slack's `thread_ts`) short-circuited the later tiers forever, and a global test let one delivered gate's id block an unrelated self-approval gate. Channel names are normalized (`slack_dm` ≡ `slack`), the delivered address is compared when both sides know it, a row whose `state_json` will not parse is refused (a corrupt row otherwise presents as a legacy one), and an empty stored channel is treated as a wildcard only for rows checkpointed before gate delivery existed. Two guards keep an open gate from swallowing unrelated traffic: a gate carrying an `origin_session_id` matches replies only from the conversations the adapter names (a Slack or Discord thread offers its parent channel session too, mirroring the history double-write, since a gate raised on a mention recorded that session while the answer arrives under the thread's — on Slack only when that person rooted the thread, or the alias would reach into a colleague's), and the parser can return `unrelated`, which declines to resolve and lets the message reach the normal chat path. The parser is handed the gate's own question, so a bare \"yes\" is judged against something. Its fallback is flagged by a key the model cannot emit rather than by a magic note string it could, and a fallback declines to resolve on *every* reply shape — recording the empty string a `free_text` fallback fabricates would close a sign-off on a parser outage. Every shape can answer `unrelated`, not just `approve_reject`: without it an open `free_text` gate turned the person's next message into its answer verbatim, and a `numeric` one swallowed any message containing a number. `resumer.apply_resolution` then records the decision, marks the run `resolved`, and writes an audit row. A timeout applies the step's `on_timeout` policy (escalate / auto_proceed / fail). The outcome surfaces on the Today dashboard.\n\n**Resuming past the gate.** A paused run continues on its own. Re-entering it was long assumed to mean serializing a Python generator frame; it does not. The only state alive across a dynamic workflow's steps is its inputs (already persisted), a company-profile block that is recomputed, the completed steps' output strings, and the loop cursor — so the engine hands the checkpoint a small JSON `WorkflowResumeState` (workflow name, the gate's id and index, the next index, the outputs so far), stored in `workflow_runs.resume_state_json`, and `DynamicWorkflow.resume` replays its step loop from the recorded index. `run()` and `resume()` share that one loop, which is why a second gate needs no special handling — it is simply another pause raised from the same place. The payload rides on a `WaitForHumanEvent` field declared `exclude=True`, so it can never leak into `state_json`, whose exact key set the resolver branches on. A gate with no payload is *pause-only*: the decision is recorded and the run stops, which is what every caller got before resume existed.\n\n`resumer._process_resumable` claims a resolved run with one guarded UPDATE — `resolved` → `running`, stamping `resumed_at` and minting a claim token — and drives it to a terminal row. It runs two ways: immediately, via a task `apply_resolution` kicks off so a Slack approval starts moving in seconds, and every 60s from the poll loop as the durable backstop. Both share the claim, so a run executes exactly once even with two resumers against one database. The poll runs the executor *after* the timeout loop, which is what finally makes `on_timeout='auto_proceed'` do what its name says: the timeout resolves the run and the same tick executes it.\n\n**The claim is fenced, because it is not a lease.** The stale sweep decides a worker is dead from a wall-clock guess, so a slow but *alive* worker will eventually be declared dead and replaced. Every write the executor makes carries its claim token and is refused once superseded — otherwise the replaced worker's late completion lands on top of its replacement's result, or its checkpoint at a later gate resurrects an already-finished run and asks the approver a second time. The retry budget resets at each new gate (a gate is new work, not a retry), and a run that exhausts it is *ended* rather than dropped: an exhausted run sits in `running` with a payload, in neither queue, and would otherwise show as in-progress forever.\n\n**The gate fails closed.** Continuing is an allowlist — `approve` and the synthetic `auto_proceed` — not \"anything that is not a stop word\". `decision` is whatever a fast model extracted from free-form chat and it drifts; under a denylist, \"rejected\", \"Reject\", \"decline\" and \"no\" would all continue, so the approver declines and the deliverable is produced anyway. Reply shapes that ask a question rather than seek permission always continue, since the answer *is* the value. A stop ends the run at `error` with the human's note. Either way the decision becomes the gate step's own output, so it reads as a section *in* the artifact — capped and blockquoted, because that text reaches the synthesis specialist as prompt context.\n\n**A definition edited during the pause is refused.** Resume re-validates the payload's version, the recorded gate, *and* a fingerprint of the whole step list, and derives the index to continue at rather than reading it from the payload. Pinning only the gate would not be enough: definitions are overwritten by name and any rostered user can save one, so someone could keep the gate identical and replace every step after it — and the approver's sign-off would be recorded against work they never saw, which defeats the one thing an approval gate is for. No built-in workflow yields the gate; only user-created dynamic workflows do.\n\n### Launching from chat\n\nWorkflows are not only reachable from the `/jobs` UI — the Executive can list and run any of them mid-conversation. `openexecutive.orchestrator.workflow_run_tools` wires two tools into the main chat loop: `list_workflows` (the launchable catalog, with each workflow's input fields) and `run_workflow` (runs one to completion and returns its Markdown artifact, using the same engine as `POST /workflows/{name}/runs`). `run_workflow` resolves both built-ins and custom workflows via `get_workflow`, validates `inputs` against the workflow's input model, persists the run (`create_run` → `complete_run` / `fail_run`), and on an approval-gate step checkpoints the run as `awaiting_human` exactly as the HTTP route does — literally the same code, since both call `workflows.gate.checkpoint_gate`, which delivers the question and writes the checkpoint in one place. It never hangs waiting on a human, and it reports both whether the question reached them and whether the run will continue by itself once answered. The runners that *cannot* pause — the schedulers, evals, client rotation, onboarding, the research tools — call `gate.ensure_workflow_event`, which raises on a gate rather than letting one be swallowed; the scheduler's dynamic-workflow branch used to ignore it and record a successful run containing nothing. `executive_research` is excluded (it has the dedicated `run_executive_research` tool). Running a workflow from chat delivers nothing on its own — it renders the artifact into the conversation, and the recurring principal briefs (`morning_brief`, `end_of_day_digest`) reach anyone only via the scheduler's own `_deliver_to_principal`. The tool description used to claim those two DM the principal when run and to confirm before firing them, which had the model soliciting a confirmation on a false premise; it now names `executive_reflection` as the one workflow that really does execute tool calls of its own (DMs to heads, broadcasts, alerts). A successful run surfaces an `action_taken` chip linking to `/jobs/runs/{run_id}`.\n\n### Dynamic (user-created) workflows\n\nUsers create reusable workflows on the fly — from the executive chat or a builder UI on `/jobs` — without shipping code. A dynamic workflow is a stored JSON definition (the `dynamic_workflows` table) interpreted at runtime by one generic `DynamicWorkflow` engine (`openexecutive/workflows/dynamic.py`) that implements the same `Workflow` ABC as the built-ins, so the run path, SSE streaming, run persistence, and `/jobs/[name]` form rendering are unchanged. `get_workflow` / `list_workflows` fall through to the dynamic store after the static registry (built-ins win on a name collision).\n\nA definition declares free-text input fields and an ordered step list of three kinds: **specialist** (consult a specialist with a goal prompt, optionally grounded by RAG), **approval_gate** (a `wait_for_human` pause), and a terminal **synthesis** step that assembles the artifact. `validate_definition` enforces the structural rules: exactly one terminal synthesis step, valid specialists, `{placeholder}` tokens that reference declared input fields, rostered approval/cadence people, and a parseable cadence.\n\nAuthoring from chat uses a **draft → confirm** handshake: the Executive calls `draft_workflow` (validate; return a `confirm_token` plus a plan summary), shows the user the plan, then calls `save_workflow` with the same definition and token — a token mismatch is rejected, so the saved workflow is exactly what the user approved. The builder UI drives the `/workflows/custom` CRUD endpoints directly. An optional cadence (`daily@` / `weekly@` / `quarterly@`) re-uses the scheduler via the `dynamic_workflow` action kind, which runs the workflow on schedule and DMs the artifact to a rostered recipient. A gate followed by further steps pauses at `awaiting_human` and then resumes once answered, so gates no longer have to sit immediately before synthesis. They remain forbidden in cadence-enabled definitions: a scheduled fire has no interactive human to ask.\n\nCompleted artifacts are discoverable in the unified Artifacts section (`/artifacts`) alongside their run-detail page at `/jobs/runs/{run_id}`.\n\n## Data-driven retrospectives\n\n`engagement_value_report` introduces a new workflow pattern: instead of the user typing the substance into a form (the `investor_update` / `mbr` shape), the workflow **reads its substance from the database**. A deterministic gatherer (`clients/engagement_activity.py`) pulls the period's decisions, initiatives, advisory consultations, delivered workflow artifacts (excluding prior value reports), follow-through counts, and alerts handled — from the live DB for the active client, or a parked client slot's `state.db` opened read-only. A single board-comms call narrates those facts (the prompt forbids inventing anything not in them; an empty period skips the LLM entirely), and the artifact's lists are assembled deterministically. Built for renewal conversations — the engagement record is the evidence.",+ "markdown": "Workflows are deterministic, multi-step orchestrations. The built-ins are registered in `openexecutive.workflows.WORKFLOW_REGISTRY`; user-created (dynamic) workflows are stored as data (see below). Each follows the same contract: structured input feeds an ordered list of named steps that render a Markdown artifact, persisted via `complete_run` into `workflow_runs.artifact`. Every step emits a `WorkflowEvent` (start/progress/complete) streamed over SSE at `/workflows/{name}/runs`.\n\nThe registry holds 24 built-in workflows, plus any number of user-created ones. Representative built-ins:\n\n- `board_prep`, `quarterly_plan`, `annual_plan` — planning and governance deliverables.\n- `performance_review`, `comp_refresh`, `org_design`, `exec_search_brief` — people and org artifacts (the last is an advisory hiring brief / scorecard from the CHRO, kept when the recruiting pipeline was removed).\n- `crisis_comms`, `churn_deep_dive`, `competitive_teardown` — situational analyses.\n- `department_check_in` — runs on department cadence; its `goal_status` step returns structured verdicts persisted back to `department_goals.status`.\n\n### Change-aware principal briefs\n\n`morning_brief` and `end_of_day_digest` are the two recurring briefs the scheduler DMs to the principal. Both are now a *delta*, not a re-list: the window is \"since the last **delivered** brief\" (`briefing.brief_state.since_for`; 24 h on a cold store, clamped to 7 days), activity comes from `_build_activity(limit, since=…)`, proposals (action category only) split into *new since last brief* — enumerated, with each item's why-now and next move — versus a one-line carried-over count, a *rewritten* block lists carried items the review rewrote inside the window (`brief_state.rewritten_since`: verdict `changed`, still open — the brief reports them under \"what changed\", never as done), and a *handled overnight* block lists what the Executive's alert review **completed** on its own (`brief_state.handled_since`; the `changed` verdict is excluded because the alert is still open). Section order: top call → what changed → handled overnight → needs you (new only) → waiting on → at risk. A date-free fingerprint of the inputs is compared to the last delivered one; if unchanged the artifact is the one-liner \"Nothing new since yesterday's brief — N items still waiting on you.\" and no model call is made (`PRINCIPAL_BRIEF_SUPPRESS_UNCHANGED`; `force_full=true` on a manual run bypasses it). The workflow yields a `result` event with the fingerprint; only the scheduler records it, after a successful delivery, in `briefing_narrative` under scope `brief:<kind>` — so manual runs never advance the window.\n\nNeither the nightly reflection nor the research synthesis can call `ack_alert`: both run unattended with open alerts rendered into their context, and those headlines are minted from inbound mail and chat, so an injected \"the principal already dismissed 13\" would be acted on with nobody watching. Closing an alert is the alert review's job, with evidence.\n\n`executive_reflection` now carries memory: yesterday's standup (the previous completed run's artifact) is rendered into the context and the prompt forbids re-acting on anything listed there unless it changed; open alerts render with their id, review verdict and recommended move. Reflection never closes alerts — the alert review does, with evidence. It also renders an **OPEN LOOPS** block (up to 10, soonest due first, overdue flagged) from Attunement so the standup can connect a slipped promise to the rest of the org state; the nudge engine already chases overdue loops, so the prompt tells it not to DM about a loop merely for being overdue. A **WHAT LANDS** block (from the Attunement outcome ledger) shows, per person, how often each kind of proactive DM got answered over 30 days; the prompt steers DMs toward kinds that land and away from kinds a person reliably ignores. Reflection and research tag their tool execution as proactive (`tag_proactive`) so their DMs are counted. Resolving a wait-for-human approval (`resumer.apply_resolution`) marks the nudges that chased it `acted`. `close_open_loop` is withheld from reflection for the same reason as `ack_alert`: loop text is quoted from what people wrote.\n\n### Wait-for-human pause\n\n`wait_for_human` (`openexecutive/workflows/wait_for_human.py`) is a first-class step primitive that pauses a run: the runner calls `save_checkpoint`, the `workflow_runs` row moves to `status='awaiting_human'`, and the serialized `WaitForHumanEvent` is stored in `state_json`. (Department authority is a *separate* mechanism — `propose_only` departments file a briefing alert via `departments.authority.propose_via_alert` and mark the scheduled action done; they do not route through this gate.)\n\n**Delivery.** Both checkpoint sites — the SSE route and the `run_workflow` chat tool — call `workflows.gate_delivery.deliver_gate_question` immediately *before* checkpointing, so `state_json` carries the routing fields a reply is matched against. Two modes. When the approver is the person already in the conversation (the chat session's `origin_channel` is set and its `caller_person_id` is the gate's `person_id`), nothing is sent — the question rides in the Executive's own reply — and the gate records `origin_session_id` plus the session's channel. Otherwise the question is delivered through `schedule_tools.handle_message_person`, which picks the person's preferred channel, falls through on a failed send, and falls back to a briefing alert; the gate then records the channel, address and provider message id that send returned, plus the id of the DM session it landed in — that send is always 1:1, so the answer belongs in that conversation and nowhere else. Without it the gate matched on person and channel alone, so an unrelated @mention in a public channel resolved it and had the acknowledgement, run title included, posted where everyone could read it. Delivery is not guaranteed: the outbound guard can suppress it (duplicate, rate cap, quiet hours) and an unreachable person gets the alert fallback. Both cases leave the routing fields empty and report `delivery` as `suppressed` / `alerted` rather than claiming someone was asked, and the chat tool's presentation hint changes accordingly.\n\n**Matching a reply.** Each inbound adapter passes the message to `inbound_resolver.resolve_inbound_message` with its `session_id`. Matching is three-tier: an explicit `in_reply_to` against a stored `outbound_message_id`; otherwise a single open run on that channel; otherwise one utility-fast disambiguation call gated at 0.85 confidence. An unmatched explicit reference rules out only the candidates that carry a stored outbound id — the ones it could have matched — and the rest continue; rejecting outright meant an adapter that passes a thread id on every message (Slack's `thread_ts`) short-circuited the later tiers forever, and a global test let one delivered gate's id block an unrelated self-approval gate. Channel names are normalized (`slack_dm` ≡ `slack`), the delivered address is compared when both sides know it, a row whose `state_json` will not parse is refused (a corrupt row otherwise presents as a legacy one), and an empty stored channel is treated as a wildcard only for rows checkpointed before gate delivery existed. Two guards keep an open gate from swallowing unrelated traffic: a gate carrying an `origin_session_id` matches replies only from the conversations the adapter names (a Slack or Discord thread offers its parent channel session too, mirroring the history double-write, since a gate raised on a mention recorded that session while the answer arrives under the thread's — on Slack only when that person rooted the thread, or the alias would reach into a colleague's), and the parser can return `unrelated`, which declines to resolve and lets the message reach the normal chat path. The parser is handed the gate's own question, so a bare \"yes\" is judged against something. Its fallback is flagged by a key the model cannot emit rather than by a magic note string it could, and a fallback declines to resolve on *every* reply shape — recording the empty string a `free_text` fallback fabricates would close a sign-off on a parser outage. Every shape can answer `unrelated`, not just `approve_reject`: without it an open `free_text` gate turned the person's next message into its answer verbatim, and a `numeric` one swallowed any message containing a number. `resumer.apply_resolution` then records the decision, marks the run `resolved`, and writes an audit row. A timeout applies the step's `on_timeout` policy (escalate / auto_proceed / fail). The outcome surfaces on the Today dashboard.\n\n**Resuming past the gate.** A paused run continues on its own. Re-entering it was long assumed to mean serializing a Python generator frame; it does not. The only state alive across a dynamic workflow's steps is its inputs (already persisted), a company-profile block that is recomputed, the completed steps' output strings, and the loop cursor — so the engine hands the checkpoint a small JSON `WorkflowResumeState` (workflow name, the gate's id and index, the next index, the outputs so far), stored in `workflow_runs.resume_state_json`, and `DynamicWorkflow.resume` replays its step loop from the recorded index. `run()` and `resume()` share that one loop, which is why a second gate needs no special handling — it is simply another pause raised from the same place. The payload rides on a `WaitForHumanEvent` field declared `exclude=True`, so it can never leak into `state_json`, whose exact key set the resolver branches on. A gate with no payload is *pause-only*: the decision is recorded and the run stops, which is what every caller got before resume existed.\n\n`resumer._process_resumable` claims a resolved run with one guarded UPDATE — `resolved` → `running`, stamping `resumed_at` and minting a claim token — and drives it to a terminal row. It runs two ways: immediately, via a task `apply_resolution` kicks off so a Slack approval starts moving in seconds, and every 60s from the poll loop as the durable backstop. Both share the claim, so a run executes exactly once even with two resumers against one database. The poll runs the executor *after* the timeout loop, which is what finally makes `on_timeout='auto_proceed'` do what its name says: the timeout resolves the run and the same tick executes it.\n\n**The claim is fenced, because it is not a lease.** The stale sweep decides a worker is dead from a wall-clock guess, so a slow but *alive* worker will eventually be declared dead and replaced. Every write the executor makes carries its claim token and is refused once superseded — otherwise the replaced worker's late completion lands on top of its replacement's result, or its checkpoint at a later gate resurrects an already-finished run and asks the approver a second time. The retry budget resets at each new gate (a gate is new work, not a retry), and a run that exhausts it is *ended* rather than dropped: an exhausted run sits in `running` with a payload, in neither queue, and would otherwise show as in-progress forever.\n\n**The gate fails closed.** Continuing is an allowlist — `approve` and the synthetic `auto_proceed` — not \"anything that is not a stop word\". `decision` is whatever a fast model extracted from free-form chat and it drifts; under a denylist, \"rejected\", \"Reject\", \"decline\" and \"no\" would all continue, so the approver declines and the deliverable is produced anyway. Reply shapes that ask a question rather than seek permission always continue, since the answer *is* the value. A stop ends the run at `error` with the human's note. Either way the decision becomes the gate step's own output, so it reads as a section *in* the artifact — capped and blockquoted, because that text reaches the synthesis specialist as prompt context.\n\n**A definition edited during the pause is refused.** Resume re-validates the payload's version, the recorded gate, *and* a fingerprint of the whole step list, and derives the index to continue at rather than reading it from the payload. Pinning only the gate would not be enough: definitions are overwritten by name and any rostered user can save one, so someone could keep the gate identical and replace every step after it — and the approver's sign-off would be recorded against work they never saw, which defeats the one thing an approval gate is for. No built-in workflow yields the gate; only user-created dynamic workflows do.\n\n### Launching from chat\n\nWorkflows are not only reachable from the `/jobs` UI — the Executive can list and run any of them mid-conversation. `openexecutive.orchestrator.workflow_run_tools` wires two tools into the main chat loop: `list_workflows` (the launchable catalog, with each workflow's input fields) and `run_workflow` (runs one to completion and returns its Markdown artifact, using the same engine as `POST /workflows/{name}/runs`). `run_workflow` resolves both built-ins and custom workflows via `get_workflow`, validates `inputs` against the workflow's input model, persists the run (`create_run` → `complete_run` / `fail_run`), and on an approval-gate step checkpoints the run as `awaiting_human` exactly as the HTTP route does — literally the same code, since both call `workflows.gate.checkpoint_gate`, which delivers the question and writes the checkpoint in one place. It never hangs waiting on a human, and it reports both whether the question reached them and whether the run will continue by itself once answered. The runners that *cannot* pause — the schedulers, evals, client rotation, onboarding, the research tools — call `gate.ensure_workflow_event`, which raises on a gate rather than letting one be swallowed; the scheduler's dynamic-workflow branch used to ignore it and record a successful run containing nothing. `executive_research` is excluded (it has the dedicated `run_executive_research` tool). Running a workflow from chat delivers nothing on its own — it renders the artifact into the conversation, and the recurring principal briefs (`morning_brief`, `end_of_day_digest`) reach anyone only via the scheduler's own `_deliver_to_principal`. The tool description used to claim those two DM the principal when run and to confirm before firing them, which had the model soliciting a confirmation on a false premise; it now names `executive_reflection` as the one workflow that really does execute tool calls of its own (DMs to heads, broadcasts, alerts). A successful run surfaces an `action_taken` chip linking to `/jobs/runs/{run_id}`.\n\n### Dynamic (user-created) workflows\n\nUsers create reusable workflows on the fly — from the executive chat or a builder UI on `/jobs` — without shipping code. A dynamic workflow is a stored JSON definition (the `dynamic_workflows` table) interpreted at runtime by one generic `DynamicWorkflow` engine (`openexecutive/workflows/dynamic.py`) that implements the same `Workflow` ABC as the built-ins, so the run path, SSE streaming, run persistence, and `/jobs/[name]` form rendering are unchanged. `get_workflow` / `list_workflows` fall through to the dynamic store after the static registry (built-ins win on a name collision).\n\nA definition declares free-text input fields and an ordered step list of three kinds: **specialist** (consult a specialist with a goal prompt, optionally grounded by RAG), **approval_gate** (a `wait_for_human` pause), and a terminal **synthesis** step that assembles the artifact. `validate_definition` enforces the structural rules: exactly one terminal synthesis step, valid specialists, `{placeholder}` tokens that reference declared input fields, rostered approval/cadence people, and a parseable cadence.\n\nAuthoring from chat uses a **draft → confirm** handshake: the Executive calls `draft_workflow` (validate; return a `confirm_token` plus a plan summary), shows the user the plan, then calls `save_workflow` with the same definition and token — a token mismatch is rejected, so the saved workflow is exactly what the user approved. The builder UI drives the `/workflows/custom` CRUD endpoints directly. An optional cadence (`daily@` / `weekly@` / `quarterly@`) re-uses the scheduler via the `dynamic_workflow` action kind, which runs the workflow on schedule and DMs the artifact to a rostered recipient. A gate followed by further steps pauses at `awaiting_human` and then resumes once answered, so gates no longer have to sit immediately before synthesis. They remain forbidden in cadence-enabled definitions: a scheduled fire has no interactive human to ask.\n\nCompleted artifacts are discoverable in the unified Artifacts section (`/artifacts`) alongside their run-detail page at `/jobs/runs/{run_id}`.\n\n## Data-driven retrospectives\n\n`engagement_value_report` introduces a new workflow pattern: instead of the user typing the substance into a form (the `investor_update` / `mbr` shape), the workflow **reads its substance from the database**. A deterministic gatherer (`clients/engagement_activity.py`) pulls the period's decisions, initiatives, advisory consultations, delivered workflow artifacts (excluding prior value reports), follow-through counts, and alerts handled — from the live DB for the active client, or a parked client slot's `state.db` opened read-only. A single board-comms call narrates those facts (the prompt forbids inventing anything not in them; an empty period skips the LLM entirely), and the artifact's lists are assembled deterministically. Built for renewal conversations — the engagement record is the evidence.","mermaid": "flowchart TD\n Input[\"Structured input\"]\n Steps[\"Ordered named steps\"]\n Wait[\"wait_for_human pause\"]\n Sched[\"workflow_runs<br/>(awaiting_human)\"]\n Resolver[\"inbound_resolver<br/>+ resumer\"]\n Artifact[\"Markdown artifact<br/>(workflow_runs.artifact)\"]\n Today[\"Today / Artifacts\"]\n Input --> Steps\n Steps --> Wait\n Wait --> Sched\n Sched -- \"human reply\" --> Resolver\n Resolver -- \"resolved → claim\" --> Steps\n Steps -- \"complete_run\" --> Artifact\n Artifact --> Today\n class Input entry\n class Steps compute\n class Wait compute\n class Sched storage\n class Resolver compute\n class Artifact storage\n class Today external",- "generated_at": "2026-09-22T21:20:28.764157+00:00"+ "generated_at": "2026-09-22T23:17:20.508677+00:00"}diff --git a/packages/core/openexecutive/attunement/__init__.py b/packages/core/openexecutive/attunement/__init__.pyindex 831f7285..13c21135 100644--- a/packages/core/openexecutive/attunement/__init__.py+++ b/packages/core/openexecutive/attunement/__init__.py@@ -8,4 +8,7 @@ here ever reads an outsider's words as someone on the roster.- :mod:`openexecutive.attunement.open_loops` — commitments and asks from anyoneon the roster become open loops the nudge engine chases once due, and closewhen the owner says they're done.+- :mod:`openexecutive.attunement.outcomes` — every proactive DM to a person is+ resolved replied / acted / dismissed / ignored, and the rates steer which+ outreach the nudge engine and the morning standup send to whom."""diff --git a/packages/core/openexecutive/attunement/open_loops.py b/packages/core/openexecutive/attunement/open_loops.pyindex 47afc1e6..587ae38f 100644--- a/packages/core/openexecutive/attunement/open_loops.py+++ b/packages/core/openexecutive/attunement/open_loops.py@@ -84,6 +84,9 @@ _CLOSE_HINT = re.compile(_SELF_OWNER = {"me", "i", "myself", "self"}+# Closure reasons that mean the thing was actually done.+_DONE_REASONS = frozenset({"reported_done", "done"})+# Attachment text is inlined into the message (``integrations.attachments``# labels each document "[Attached: <name>]"), before the words on some# channels and after on others. A quote found there is a document's words, not@@ -315,12 +318,30 @@ def close_open_loop(if not resolved.exists():return Falsewith _get_conn(resolved) as conn:+ owner_row = conn.execute(+ "SELECT assigned_to_person_id FROM scheduled_actions WHERE id = ? AND kind = ?",+ (loop_id, OPEN_LOOP_KIND),+ ).fetchone()cur = conn.execute("UPDATE scheduled_actions SET awaiting_response_since = NULL ""WHERE id = ? AND kind = ? AND awaiting_response_since IS NOT NULL",(loop_id, OPEN_LOOP_KIND),)closed = cur.rowcount > 0+ owner_id = owner_row["assigned_to_person_id"] if owner_row else None+ # Only the owner's own "it's done" credits the chases. The principal+ # tidying a loop away ("done" is the default in the UI and the tool) says+ # nothing about whether the owner answered.+ owner_did_it = reason == "reported_done" or (+ reason in _DONE_REASONS and closed_by_person_id is not None+ and closed_by_person_id == owner_id+ )+ if closed and owner_did_it:+ # The chases for this loop landed: the owner (or the principal) says+ # it's done. Other closures (expiry, archive, cancelled) prove nothing.+ from openexecutive.attunement.outcomes import OUTCOME_ACTED, resolve_by_ref++ resolve_by_ref(f"nudge:commitment:{loop_id}", OUTCOME_ACTED, db_path=db_path)if closed:_audit(f"open loop #{loop_id} closed ({reason})",diff --git a/packages/core/openexecutive/attunement/outcomes.py b/packages/core/openexecutive/attunement/outcomes.pynew file mode 100644index 00000000..e1598756--- /dev/null+++ b/packages/core/openexecutive/attunement/outcomes.py@@ -0,0 +1,351 @@+"""Proactive-outcome ledger — which outreach lands, per person and source.++Nothing used to measure whether the Executive's proactive messages worked. A+nudge that was always ignored kept being sent, and one that always got an+answer was ranked no higher. This ledger records every proactive DM to a+rostered person and resolves it deterministically, with no model call:++- **replied** — the recipient's reply was matched to the DM+ (``memory.episodic.mark_outbound_context_consumed``);+- **acted** — the thing it was about got done: the open loop it chased was+ reported done by its owner, the approval it nudged was resolved, the+ initiative it checked on was updated, or the alert it was about was+ acknowledged or resolved;+- **void** — the alert it was about was dismissed or found stale: the DM+ neither landed nor was ignored, so it counts toward neither;+- **ignored** — nothing of the above within ``ATTUNEMENT_IGNORE_AFTER_HOURS``+ (swept at the start of each nudge scan and whenever rates are read).++Recording happens at the one place every proactive DM passes through —+``orchestrator.schedule_tools._record_outbound_context`` — but only while a+proactive source is tagged with :func:`tag_proactive`. Callers that start+proactive work (the scheduler's dispatch of nudges and follow-ups, the+reflection and research workflows, alert review) wrap their sends in it. A+user's own chat turn is never tagged, so replies in conversation are not+counted as outreach.++Rates feed back into the nudge engine (``muted_pairs``), the reflection+prompt (``render_for_reflection``) and the person page (``acceptance``).+"""+from __future__ import annotations++import contextlib+import contextvars+import logging+from collections.abc import Iterator+from dataclasses import dataclass, field+from datetime import UTC, datetime, timedelta+from pathlib import Path+from typing import Any++logger = logging.getLogger(__name__)++# Sources, as stored. Kept small and stable: they key the nudge engine's+# per-person ranking and the reflection summary.+SOURCE_NUDGE_STALLED = "nudge_stalled"+SOURCE_NUDGE_COMMITMENT = "nudge_commitment"+SOURCE_NUDGE_INITIATIVE = "nudge_initiative"+SOURCE_OPEN_LOOP = "open_loop"+SOURCE_FOLLOWUP = "followup"+SOURCE_REFLECTION = "reflection"+SOURCE_RESEARCH = "research"+SOURCE_ALERT_REVIEW = "alert_review"++SOURCE_LABELS: dict[str, str] = {+ SOURCE_NUDGE_STALLED: "approval nudges",+ SOURCE_NUDGE_COMMITMENT: "commitment chases",+ SOURCE_NUDGE_INITIATIVE: "initiative check-ins",+ SOURCE_OPEN_LOOP: "open-loop chases",+ SOURCE_FOLLOWUP: "scheduled follow-ups",+ SOURCE_REFLECTION: "standup DMs",+ SOURCE_RESEARCH: "research DMs",+ SOURCE_ALERT_REVIEW: "alert-review DMs",+}++OUTCOME_REPLIED = "replied"+OUTCOME_ACTED = "acted"+OUTCOME_IGNORED = "ignored"+# The thing the DM was about turned out not to matter (its alert was+# dismissed): the DM neither landed nor was ignored, so it counts toward+# neither. Keeps a dismissed alert — which anyone with API access can do —+# from dragging down the rate of the person who was DM'd about it.+OUTCOME_VOID = "void"+POSITIVE_OUTCOMES = frozenset({OUTCOME_REPLIED, OUTCOME_ACTED})++# Window the rates are computed over.+_STATS_WINDOW_DAYS = 30+# A person needs this many resolved sends from one source before the reflection+# summary mentions it; below that the rate is noise.+_REFLECTION_MIN_RESOLVED = 3+_REFLECTION_MAX_PEOPLE = 10++# (source, ref) of the proactive work currently sending, if any.+_proactive: contextvars.ContextVar[tuple[str, str] | None] = contextvars.ContextVar(+ "attunement_proactive_source", default=None+)+++def tag_proactive(source: str, ref: str = "") -> Iterator[None]:+ """Mark every DM sent inside the block as proactive outreach from+ ``source``. ``ref`` names what it is about (a nudge scope key,+ ``alert:<id>``) so a later action on that thing resolves it.++ Wrap only non-yielding code: a ContextVar set inside an async generator+ would leak across its ``yield``."""+ token = _proactive.set((source, ref))+ try:+ yield+ finally:+ _proactive.reset(token)+++def current_tag() -> tuple[str, str] | None:+ return _proactive.get()+++def _db(db_path: Path | None) -> Path:+ from openexecutive.memory.episodic import _resolve_db_path++ return _resolve_db_path(db_path)+++def record_send(+ *,+ person_id: int | None,+ channel: str,+ channel_ref: str,+ outbound_context_id: int | None,+ db_path: Path | None = None,+) -> int | None:+ """Record one proactive DM if a source is tagged and the recipient is a+ rostered person. Returns the row id, or None when nothing was recorded.+ Never raises: it runs right after a send that already succeeded."""+ tag = _proactive.get()+ if tag is None or person_id is None:+ return None+ source, ref = tag+ if source == SOURCE_FOLLOWUP and _is_principal(person_id):+ # A reminder the principal set for themselves is not outreach, and+ # would otherwise read as "the principal ignores follow-ups".+ return None+ try:+ from openexecutive.memory.episodic import _get_conn++ with _get_conn(_db(db_path)) as conn:+ cur = conn.execute(+ "INSERT INTO proactive_outcomes "+ "(created_at, person_id, source, ref, channel, channel_ref, outbound_context_id) "+ "VALUES (?, ?, ?, ?, ?, ?, ?)",+ (datetime.now(UTC).isoformat(), person_id, source, ref or None,+ channel, channel_ref, outbound_context_id),+ )+ return int(cur.lastrowid or 0) or None+ except Exception:+ logger.warning("outcomes: record_send failed (non-fatal)", exc_info=True)+ return None+++def _is_principal(person_id: int) -> bool:+ try:+ from openexecutive.people.store import get_person++ person = get_person(person_id)+ return bool(person is not None and person.is_principal)+ except Exception:+ return False+++def _resolve(where: str, params: tuple[Any, ...], outcome: str, db_path: Path | None) -> int:+ """Set ``outcome`` on still-open rows matching ``where``. Never raises."""+ try:+ from openexecutive.memory.episodic import _get_conn++ resolved = _db(db_path)+ if not resolved.exists():+ return 0+ with _get_conn(resolved) as conn:+ cur = conn.execute(+ "UPDATE proactive_outcomes SET outcome = ?, resolved_at = ? "+ f"WHERE outcome IS NULL AND {where}",+ (outcome, datetime.now(UTC).isoformat(), *params),+ )+ return int(cur.rowcount)+ except Exception:+ logger.warning("outcomes: resolve failed (non-fatal)", exc_info=True)+ return 0+++def resolve_by_ref(+ ref: str,+ outcome: str,+ *,+ person_ids: set[int] | None = None,+ db_path: Path | None = None,+) -> int:+ """Resolve open outcomes about ``ref`` (a nudge scope key, an alert).++ ``person_ids`` limits it to DMs sent to those people — an alert can be+ DM'd to several people over successive review passes, and acting on it+ credits only the ones it now belongs to."""+ if not ref:+ return 0+ if person_ids is None:+ return _resolve("ref = ?", (ref,), outcome, db_path)+ ids = sorted(person_ids)+ if not ids:+ return 0+ placeholders = ",".join("?" * len(ids))+ return _resolve(f"ref = ? AND person_id IN ({placeholders})", (ref, *ids), outcome, db_path)+++def resolve_by_outbound_context(+ context_id: int, outcome: str, *, db_path: Path | None = None+) -> int:+ """Resolve the outcome recorded for one outbound DM (a matched reply)."""+ return _resolve("outbound_context_id = ?", (context_id,), outcome, db_path)+++def sweep_ignored(+ now: datetime | None = None,+ *,+ after_hours: int | None = None,+ db_path: Path | None = None,+) -> int:+ """Mark outcomes still open after ``after_hours`` as ignored."""+ from openexecutive.config import get_settings++ hours = after_hours if after_hours is not None else get_settings().attunement_ignore_after_hours+ if hours <= 0:+ return 0+ cutoff = ((now or datetime.now(UTC)) - timedelta(hours=hours)).isoformat()+ return _resolve("created_at < ?", (cutoff,), OUTCOME_IGNORED, db_path)+++@dataclass+class SourceStats:+ sent: int = 0+ counts: dict[str, int] = field(default_factory=dict)++ @property+ def resolved(self) -> int:+ return sum(self.counts.values())++ @property+ def positive(self) -> int:+ return sum(n for o, n in self.counts.items() if o in POSITIVE_OUTCOMES)++ @property+ def pending(self) -> int:+ return self.sent - self.resolved++ def rate(self) -> float:+ """Smoothed share of resolved sends that landed — a Laplace prior+ keeps one or two sends from swinging it to 0 or 1."""+ return (self.positive + 1) / (self.resolved + 2)+++def acceptance(+ *,+ person_id: int | None = None,+ days: int = _STATS_WINDOW_DAYS,+ db_path: Path | None = None,+) -> dict[tuple[int, str], SourceStats]:+ """Per (person, source) counts over the last ``days``."""+ from openexecutive.memory.episodic import _get_conn++ resolved = _db(db_path)+ if not resolved.exists():+ return {}+ # Sweep on read as well as in the nudge scan: with the scan disabled,+ # unanswered DMs would otherwise stay pending forever and the rates would+ # only ever see the answers.+ sweep_ignored(db_path=db_path)+ since = (datetime.now(UTC) - timedelta(days=days)).isoformat()+ sql = (+ "SELECT person_id, source, outcome, COUNT(*) AS n FROM proactive_outcomes "+ "WHERE created_at >= ? AND (outcome IS NULL OR outcome != 'void')"+ )+ params: list[Any] = [since]+ if person_id is not None:+ sql += " AND person_id = ?"+ params.append(person_id)+ sql += " GROUP BY person_id, source, outcome"+ out: dict[tuple[int, str], SourceStats] = {}+ try:+ with _get_conn(resolved) as conn:+ rows = conn.execute(sql, params).fetchall()+ except Exception:+ logger.warning("outcomes: acceptance query failed", exc_info=True)+ return {}+ for r in rows:+ stats = out.setdefault((int(r["person_id"]), str(r["source"])), SourceStats())+ n = int(r["n"])+ stats.sent += n+ if r["outcome"]:+ stats.counts[str(r["outcome"])] = stats.counts.get(str(r["outcome"]), 0) + n+ return out+++def muted_pairs(+ *,+ min_sends: int,+ days: int = _STATS_WINDOW_DAYS,+ db_path: Path | None = None,+) -> set[tuple[int, str]]:+ """``(person, source)`` pairs this person reliably ignores: their most+ recent ``min_sends`` resolved DMs from that source all went unanswered.++ Judged on the most recent sends, not the 30-day share, so a single answer+ lifts it at once — a demoted source gets fewer chances to be answered,+ and a share would keep it demoted long after the person came back."""+ from openexecutive.memory.episodic import _get_conn++ resolved = _db(db_path)+ if min_sends <= 0 or not resolved.exists():+ return set()+ sweep_ignored(db_path=db_path)+ since = (datetime.now(UTC) - timedelta(days=days)).isoformat()+ try:+ with _get_conn(resolved) as conn:+ rows = conn.execute(+ "SELECT person_id, source, outcome FROM proactive_outcomes "+ "WHERE created_at >= ? AND outcome IS NOT NULL AND outcome != 'void' "+ "ORDER BY person_id, source, resolved_at DESC, id DESC",+ (since,),+ ).fetchall()+ except Exception:+ logger.warning("outcomes: muted_pairs query failed", exc_info=True)+ return set()+ recent: dict[tuple[int, str], list[str]] = {}+ for r in rows:+ seq = recent.setdefault((int(r["person_id"]), str(r["source"])), [])+ if len(seq) < min_sends:+ seq.append(str(r["outcome"]))+ return {+ key for key, seq in recent.items()+ if len(seq) >= min_sends and not any(o in POSITIVE_OUTCOMES for o in seq)+ }+++def render_for_reflection(*, db_path: Path | None = None) -> list[str]:+ """One line per person with enough history: how each source lands."""+ from openexecutive.people.store import list_people++ stats = acceptance(db_path=db_path)+ if not stats:+ return []+ try:+ names = {p.id: p.full_name for p in list_people() if p.id is not None}+ except Exception:+ names = {}+ by_person: dict[int, list[str]] = {}+ for (pid, source), s in sorted(stats.items()):+ if s.resolved < _REFLECTION_MIN_RESOLVED or pid not in names:+ continue+ label = SOURCE_LABELS.get(source, source)+ by_person.setdefault(pid, []).append(f"{label} {s.positive}/{s.resolved} answered")+ return [+ f"- {names[pid]} (id={pid}): " + "; ".join(parts)+ for pid, parts in list(by_person.items())[:_REFLECTION_MAX_PEOPLE]+ ]diff --git a/packages/core/openexecutive/cli/fixture_loader.py b/packages/core/openexecutive/cli/fixture_loader.pyindex 3227af75..baef8bb7 100644--- a/packages/core/openexecutive/cli/fixture_loader.py+++ b/packages/core/openexecutive/cli/fixture_loader.py@@ -773,15 +773,16 @@ async def reset_all_state(),)- # Attunement's daily call counter. Created by initialize_db, which an+ # Attunement's daily call counter and outcome ledger. Created by initialize_db, which an# older DB may not have run yet, so guarded per table (the helper# above only guards the file).if EPISODIC_DB_PATH.exists():with sqlite3.connect(str(EPISODIC_DB_PATH)) as _conn:- if _conn.execute(- "SELECT 1 FROM sqlite_master WHERE type='table' AND name='attunement_usage'"- ).fetchone():- _conn.execute("DELETE FROM attunement_usage")+ for _table in ("attunement_usage", "proactive_outcomes"):+ if _conn.execute(+ "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (_table,)+ ).fetchone():+ _conn.execute(f"DELETE FROM {_table}")# 3c. Knowledge review state (same DB as the episodic rows above). A# "factory reset" that keeps the previous operator's approvals,diff --git a/packages/core/openexecutive/clients/slots.py b/packages/core/openexecutive/clients/slots.pyindex ff1598e0..3046c19a 100644--- a/packages/core/openexecutive/clients/slots.py+++ b/packages/core/openexecutive/clients/slots.py@@ -122,6 +122,7 @@ _BLANK_WIPE_TABLES = (# Attunement's daily model-call counter (open loops themselves live in# scheduled_actions, and sender/feedback columns in chat_messages)."attunement_usage",+ "proactive_outcomes",# Legacy talent / staff-onboarding tables. Both features are gone and# nothing writes these any more, but the rows may still exist on upgraded# installs and they carry candidate PII (names, employers, screeningdiff --git a/packages/core/openexecutive/config.py b/packages/core/openexecutive/config.pyindex dab4ec12..c2cf4f59 100644--- a/packages/core/openexecutive/config.py+++ b/packages/core/openexecutive/config.py@@ -727,6 +727,16 @@ class Settings(BaseSettings):)# Ceiling on open-loop extraction model calls per UTC day, across everyone.attunement_max_calls_per_day: int = Field(200, alias="ATTUNEMENT_MAX_CALLS_PER_DAY")+ # Outcome ledger: a proactive DM with no reply / action after this long is+ # counted as ignored.+ attunement_ignore_after_hours: int = Field(72, alias="ATTUNEMENT_IGNORE_AFTER_HOURS")+ # A person whose last ATTUNEMENT_MUTE_MIN_SENDS resolved sends from one+ # nudge source all went unanswered is chased less for that source: ranked+ # last and on a longer cooldown. A single answer lifts it.+ attunement_mute_min_sends: int = Field(5, alias="ATTUNEMENT_MUTE_MIN_SENDS")+ attunement_mute_cooldown_multiplier: int = Field(+ 3, alias="ATTUNEMENT_MUTE_COOLDOWN_MULTIPLIER"+ )# External-condition monitoring — heartbeat that polls source adapters# (vendor_status in PR-A; RSS + stock in PR-B) and emits external_signalsdiff --git a/packages/core/openexecutive/memory/episodic.py b/packages/core/openexecutive/memory/episodic.pyindex 4f1a469c..6fbc7a75 100644--- a/packages/core/openexecutive/memory/episodic.py+++ b/packages/core/openexecutive/memory/episodic.py@@ -336,6 +336,36 @@ def initialize_db(db_path: Path = DB_PATH) -> None:")")+ # Attunement outcome ledger: one row per proactive DM to a rostered+ # person, resolved replied / acted / dismissed / ignored+ # (attunement/outcomes.py).+ conn.execute(+ "CREATE TABLE IF NOT EXISTS proactive_outcomes ("+ " id INTEGER PRIMARY KEY AUTOINCREMENT,"+ " created_at TEXT NOT NULL,"+ " person_id INTEGER NOT NULL,"+ " source TEXT NOT NULL,"+ " ref TEXT,"+ " channel TEXT NOT NULL,"+ " channel_ref TEXT NOT NULL,"+ " outbound_context_id INTEGER,"+ " outcome TEXT,"+ " resolved_at TEXT"+ ")"+ )+ conn.execute(+ "CREATE INDEX IF NOT EXISTS idx_proactive_outcomes_person "+ "ON proactive_outcomes(person_id, created_at)"+ )+ conn.execute(+ "CREATE INDEX IF NOT EXISTS idx_proactive_outcomes_ref "+ "ON proactive_outcomes(ref) WHERE ref IS NOT NULL"+ )+ conn.execute(+ "CREATE INDEX IF NOT EXISTS idx_proactive_outcomes_ctx "+ "ON proactive_outcomes(outbound_context_id) WHERE outbound_context_id IS NOT NULL"+ )+# Attunement open loops: at most one OPEN loop per scope_key. Closing a# loop clears awaiting_response_since, which takes it out of the index,# so the same ask can be reopened later. The insert path relies on this@@ -555,6 +585,8 @@ def store_initiative("INSERT INTO initiatives (title, status, created_at, updated_at, summary, department) VALUES (?, ?, ?, ?, ?, ?)",(title, status, now, now, summary, department),)+ if existing:+ _resolve_initiative_outreach(int(existing["id"]), db_path)# Mirror only on a new initiative OR a real status transition.# Idempotent upserts (same title + same status) don't fire — that# would spam the dept peer with redundant notes on every routine@@ -797,7 +829,17 @@ def update_initiative(cursor = conn.execute(f"UPDATE initiatives SET {set_clause} WHERE id = ?", values)- return cursor.rowcount > 0+ updated = cursor.rowcount > 0+ if updated:+ _resolve_initiative_outreach(initiative_id, db_path)+ return updated+++def _resolve_initiative_outreach(initiative_id: int, db_path: Path | None) -> None:+ """An initiative got an update, so the check-in nudges about it landed."""+ from openexecutive.attunement.outcomes import OUTCOME_ACTED, resolve_by_ref++ resolve_by_ref(f"nudge:initiative:{initiative_id}", OUTCOME_ACTED, db_path=db_path)def update_advice(@@ -1012,7 +1054,13 @@ def mark_outbound_context_consumed("WHERE id = ? AND status = 'open'",(datetime.now(UTC).isoformat(), context_id),)- return cursor.rowcount > 0+ consumed = cursor.rowcount > 0+ if consumed:+ # A matched reply is the clearest sign a proactive DM landed.+ from openexecutive.attunement.outcomes import OUTCOME_REPLIED, resolve_by_outbound_context++ resolve_by_outbound_context(context_id, OUTCOME_REPLIED, db_path=db_path)+ return consumeddef scope_key_in_use(scope_key: str, db_path: Path | None = None) -> bool:diff --git a/packages/core/openexecutive/orchestrator/mcp_gateway.py b/packages/core/openexecutive/orchestrator/mcp_gateway.pyindex 24025be2..e877ca63 100644--- a/packages/core/openexecutive/orchestrator/mcp_gateway.py+++ b/packages/core/openexecutive/orchestrator/mcp_gateway.py@@ -594,12 +594,16 @@ def _record_email_outbound_context(arguments: dict[str, Any]) -> None:norm = addr.strip().lower()if not norm or norm == self_addr or norm in seen:continue+ # Only the first "to" address is who the email was addressed+ # to; every recipient still gets reply linkage.+ primary = field == "to" and not seenseen.add(norm)_record_outbound_context(channel="email",channel_ref=norm,text=body,outbound_message_id=None,+ record_outcome=primary,)except Exception:logger.exception(diff --git a/packages/core/openexecutive/orchestrator/schedule_tools.py b/packages/core/openexecutive/orchestrator/schedule_tools.pyindex 9d9b98f9..a6314160 100644--- a/packages/core/openexecutive/orchestrator/schedule_tools.py+++ b/packages/core/openexecutive/orchestrator/schedule_tools.py@@ -191,10 +191,15 @@ def _record_outbound_context(channel_ref: str,text: str,outbound_message_id: str | None = None,+ record_outcome: bool = True,) -> None:"""Persist an outbound→inbound DM linkage so the recipient's reply can behydrated with the originating conversation's context.+ ``record_outcome`` False keeps a secondary recipient (an email cc) out of+ the Attunement outcome ledger: the outreach was not addressed to them, and+ counting it would mark them as ignoring someone else's nudges.+Only writes when a live session is active (``current_session`` is set), andnot for browser turns. Best-effort — any failure here must never break thesend the caller just completed.@@ -232,7 +237,7 @@ def _record_outbound_context(recipient_person_id = _resolve_recipient_person_id(channel, channel_ref)from openexecutive.memory.episodic import insert_outbound_context- insert_outbound_context(+ context_id = insert_outbound_context(channel=channel,channel_ref=channel_ref,outbound_text=text,@@ -240,6 +245,17 @@ def _record_outbound_context(recipient_person_id=recipient_person_id,outbound_message_id=outbound_message_id,)+ # Proactive outreach (tagged by whoever started it) also opens an+ # outcome row; the reply that consumes this linkage resolves it.+ from openexecutive.attunement.outcomes import record_send++ if record_outcome:+ record_send(+ person_id=recipient_person_id,+ channel=channel,+ channel_ref=channel_ref,+ outbound_context_id=context_id,+ )except Exception:logger.exception("record_outbound_context: persist failed (non-fatal)")diff --git a/packages/core/openexecutive/scheduler/nudge_engine.py b/packages/core/openexecutive/scheduler/nudge_engine.pyindex 021d0893..3823e60b 100644--- a/packages/core/openexecutive/scheduler/nudge_engine.py+++ b/packages/core/openexecutive/scheduler/nudge_engine.py@@ -81,6 +81,9 @@ class NudgeCandidate:# fall back to the channel the original action already used.fallback_channel: str | None = Nonefallback_channel_ref: str | None = None+ # Outcome-ledger source (attunement.outcomes.SOURCE_*) this nudge counts+ # under, so the scan can rank by how this person answers that source.+ outcome_source: str = ""@dataclass@@ -159,6 +162,7 @@ def _select_stalled_workflow_candidates(urgency_seconds=(awaiting_until - now).total_seconds(),cooldown=cooldown,person_id=int(person_id),+ outcome_source="nudge_stalled",))return out@@ -239,6 +243,9 @@ def _select_stale_commitment_candidates(department=r["department"] or "",fallback_channel=r["channel"],fallback_channel_ref=r["channel_ref"],+ outcome_source=(+ "open_loop" if r["kind"] == "open_loop" else "nudge_commitment"+ ),))return out@@ -333,6 +340,7 @@ def _select_idle_initiative_candidates(cooldown=cooldown,person_id=person_id,department=slug,+ outcome_source="nudge_initiative",))return out@@ -468,18 +476,53 @@ def _static_channel_for_person(# Scan orchestration# ---------------------------------------------------------------------------+def _apply_outcome_feedback(+ candidates: list[NudgeCandidate],+ settings: Any,+ *,+ db_path: Path | None = None,+) -> tuple[list[NudgeCandidate], set[str]]:+ """Demote nudges a person reliably ignores, using the outcome ledger.++ A candidate whose person left their last ``ATTUNEMENT_MUTE_MIN_SENDS``+ resolved sends of the same source all unanswered gets a cooldown+ ``ATTUNEMENT_MUTE_COOLDOWN_MULTIPLIER`` times longer and ranks after every+ other candidate. It is never dropped outright, and a single answer lifts+ it. Returns the candidates and the scope keys that were demoted."""+ from dataclasses import replace++ from openexecutive.attunement.outcomes import muted_pairs++ min_sends = int(getattr(settings, "attunement_mute_min_sends", 5))+ multiplier = max(1, int(getattr(settings, "attunement_mute_cooldown_multiplier", 3)))+ muted = muted_pairs(min_sends=min_sends, db_path=db_path)+ if not muted:+ return candidates, set()+ out: list[NudgeCandidate] = []+ demoted: set[str] = set()+ for c in candidates:+ if c.person_id is not None and (c.person_id, c.outcome_source) in muted:+ c = replace(c, cooldown=c.cooldown * multiplier)+ demoted.add(c.scope_key)+ out.append(c)+ return out, demoted++def _apply_caps(candidates: list[NudgeCandidate],*,max_total: int,max_per_person: int,+ demoted: set[str] | None = None,) -> list[NudgeCandidate]:"""Sort by urgency, then truncate by per-person and global caps.`urgency_seconds` is ascending — smaller first (sooner deadline /- older awaiting_response_since / older updated_at).+ older awaiting_response_since / older updated_at). Candidates in+ ``demoted`` (sources this person reliably ignores) rank after all others."""- ranked = sorted(candidates, key=lambda c: c.urgency_seconds)+ demoted = demoted or set()+ ranked = sorted(candidates, key=lambda c: (c.scope_key in demoted, c.urgency_seconds))per_person: dict[int, int] = defaultdict(int)accepted: list[NudgeCandidate] = []for c in ranked:@@ -517,6 +560,14 @@ async def run_nudge_scan(expire_open_loops(now, ttl_days=settings.attunement_loop_ttl_days, db_path=db_path)except Exception:logger.exception("nudge_engine: open-loop expiry failed")+ # Resolve proactive outreach nobody answered as ignored, so this scan's+ # ranking sees it.+ try:+ from openexecutive.attunement.outcomes import sweep_ignored++ sweep_ignored(now, after_hours=settings.attunement_ignore_after_hours, db_path=db_path)+ except Exception:+ logger.exception("nudge_engine: outcome sweep failed")candidates: list[NudgeCandidate] = []try:@@ -557,10 +608,17 @@ async def run_nudge_scan(if not candidates:return 0+ demoted: set[str] = set()+ try:+ candidates, demoted = _apply_outcome_feedback(candidates, settings, db_path=db_path)+ except Exception:+ logger.exception("nudge_engine: outcome feedback failed — ranking by urgency only")+ranked = _apply_caps(candidates,max_total=settings.nudge_max_per_scan,max_per_person=settings.nudge_max_per_person_per_scan,+ demoted=demoted,)emitted = 0diff --git a/packages/core/openexecutive/scheduler/runner.py b/packages/core/openexecutive/scheduler/runner.pyindex 1f970c5b..92a0e0e2 100644--- a/packages/core/openexecutive/scheduler/runner.py+++ b/packages/core/openexecutive/scheduler/runner.py@@ -793,12 +793,16 @@ async def _execute_action()executive = Executive(mcp_gateway=gateway)- await executive.chat(- user_message=synthetic_message,- session=session,- retrieved_context=retrieved_context,- episodic_context=episodic_context,- )+ from openexecutive.attunement.outcomes import tag_proactive++ source, ref = _outreach_source(action)+ with tag_proactive(source, ref):+ await executive.chat(+ user_message=synthetic_message,+ session=session,+ retrieved_context=retrieved_context,+ episodic_context=episodic_context,+ )except Exception as exc:logger.exception("scheduler: action %d failed", action.id)@@ -1277,6 +1281,37 @@ async def _run_principal_brief(action: ScheduledAction, now: datetime) -> None:_enqueue_next_principal_brief(kind, after=datetime.now(UTC))+def _outreach_source(action: ScheduledAction) -> tuple[str, str]:+ """``(source, ref)`` for the outcome ledger of one dispatched action.++ A nudge is keyed by its scope key (``nudge:<source>:<id>``) so closing the+ thing it chased resolves it; a commitment nudge whose target is an open+ loop is reported as an open-loop chase. Anything else is a scheduled+ follow-up."""+ from openexecutive.attunement import outcomes++ if action.kind != "proactive_nudge" or not action.scope_key:+ return outcomes.SOURCE_FOLLOWUP, f"action:{action.id}"+ scope = action.scope_key+ parts = scope.split(":")+ kind = parts[1] if len(parts) > 2 else ""+ if kind == "commitment":+ from openexecutive.memory.episodic import get_scheduled_action++ try:+ target = get_scheduled_action(int(parts[2]))+ except Exception:+ # A malformed id or a lookup failure just means "not a loop".+ target = None+ if target is not None and target.kind == "open_loop":+ return outcomes.SOURCE_OPEN_LOOP, scope+ return outcomes.SOURCE_NUDGE_COMMITMENT, scope+ return {+ "stalled": outcomes.SOURCE_NUDGE_STALLED,+ "initiative": outcomes.SOURCE_NUDGE_INITIATIVE,+ }.get(kind, outcomes.SOURCE_FOLLOWUP), scope++# --------------------------------------------------------------------------- ## Executive reflection (Shift 5)# --------------------------------------------------------------------------- #diff --git a/packages/core/openexecutive/workflows/executive_reflection.py b/packages/core/openexecutive/workflows/executive_reflection.pyindex 856ec62f..24514d27 100644--- a/packages/core/openexecutive/workflows/executive_reflection.py+++ b/packages/core/openexecutive/workflows/executive_reflection.py@@ -150,6 +150,10 @@ def _build_reflection_system(configured: set[str], has_roster: bool = True) -> s"the nudge engine already chases overdue ones, so don't DM about a ""loop just because it's overdue — use them to connect signals or to ""flag a slipped promise that matters for the brief. "+ "WHAT LANDS shows, per person, how often each kind of proactive DM "+ "got an answer: prefer the kind of outreach that lands with that "+ "person, and don't DM someone through a kind they reliably ignore — "+ "raise it in the brief instead. ""Open alerts carry the review verdict of your alert-review job ""(relevant / changed / likely_stale) and its recommended move; you ""never close alerts here (that job does, with evidence).\n\n"@@ -183,6 +187,7 @@ def _render_reflection_context(external_signals: list[dict[str, Any]],previous_reflection: str | None = None,open_loops: list[str] | None = None,+ outreach: list[str] | None = None,) -> str:"""Pack /today + activity + open alerts + external signals into asingle user-turn block for the LLM to reason over.@@ -268,6 +273,13 @@ def _render_reflection_context(parts.extend(open_loops)parts.append("")+ if outreach:+ # Per-person answer rates by kind of outreach (attunement.outcomes),+ # last 30 days: which DMs actually land with whom.+ parts.append("WHAT LANDS (answered / resolved proactive DMs, last 30 days):")+ parts.extend(outreach)+ parts.append("")+if previous_reflection:parts.append("YESTERDAY'S STANDUP (already handled — do not repeat):")parts.append(previous_reflection.strip()[:_PREVIOUS_REFLECTION_CHARS])@@ -339,6 +351,17 @@ def _open_loop_lines() -> list[str]:return []+def _outreach_lines() -> list[str]:+ """How proactive DMs land per person; a lookup failure omits the block."""+ try:+ from openexecutive.attunement.outcomes import render_for_reflection++ return render_for_reflection()+ except Exception:+ logger.debug("reflection: outreach stats lookup failed", exc_info=True)+ return []++class ExecutiveReflectionWorkflow(Workflow):name = "executive_reflection"title = "Executive Reflection"@@ -508,6 +531,7 @@ class ExecutiveReflectionWorkflow(Workflow):external_signals=external_signals,previous_reflection=_previous_reflection_artifact(),open_loops=_open_loop_lines(),+ outreach=_outreach_lines(),)roster = _render_team_roster(people)if roster:@@ -593,7 +617,12 @@ class ExecutiveReflectionWorkflow(Workflow):)return- iter_summaries = await _execute_tool_calls(response, _ALL_SKILL_HANDLERS)+ # Only the await sits inside the tag — this is an async+ # generator, and a ContextVar set across a `yield` would leak.+ from openexecutive.attunement.outcomes import SOURCE_REFLECTION, tag_proactive++ with tag_proactive(SOURCE_REFLECTION):+ iter_summaries = await _execute_tool_calls(response, _ALL_SKILL_HANDLERS)tool_call_summaries.extend(iter_summaries)text = _extract_artifact_from_response(response)diff --git a/packages/core/openexecutive/workflows/executive_research.py b/packages/core/openexecutive/workflows/executive_research.pyindex f03201bd..f8612604 100644--- a/packages/core/openexecutive/workflows/executive_research.py+++ b/packages/core/openexecutive/workflows/executive_research.py@@ -851,11 +851,16 @@ async def _executive_synthesis_loop(ok_so_far = _routing_ok(tool_calls)budget_remaining = max(0, _MAX_ROUTING_TOOLS_PER_RUN - ok_so_far)- iter_calls = await execute_tool_calls(- response, _ALL_SKILL_HANDLERS,- budget_remaining=budget_remaining,- free_tools=_NON_ROUTING_TOOLS,- )+ # DMs the synthesis sends are proactive research outreach; the+ # outcome ledger records whether they land.+ from openexecutive.attunement.outcomes import SOURCE_RESEARCH, tag_proactive++ with tag_proactive(SOURCE_RESEARCH):+ iter_calls = await execute_tool_calls(+ response, _ALL_SKILL_HANDLERS,+ budget_remaining=budget_remaining,+ free_tools=_NON_ROUTING_TOOLS,+ )tool_calls.extend(iter_calls)text = extract_artifact_from_response(response)diff --git a/packages/core/openexecutive/workflows/resumer.py b/packages/core/openexecutive/workflows/resumer.pyindex 342675d0..9931b096 100644--- a/packages/core/openexecutive/workflows/resumer.py+++ b/packages/core/openexecutive/workflows/resumer.py@@ -95,6 +95,13 @@ async def apply_resolution(logger.info("resumer.apply_resolution: run %s not awaiting_human (no-op)", run_id)return False+ # The approver decided — however they did it (web, Slack, a reply) — so+ # the nudges chasing this approval landed.+ from openexecutive.attunement.outcomes import OUTCOME_ACTED, resolve_by_ref++ # The ledger lives in the episodic store, not necessarily at `db_path`.+ resolve_by_ref(f"nudge:stalled:{run_id}", OUTCOME_ACTED)+audit_log("human_resolution",f"WaitForHuman resolved: run_id={run_id} person={resolution.person_id} "diff --git a/packages/core/tests/unit/test_alert_review.py b/packages/core/tests/unit/test_alert_review.pyindex 96d3563e..d26eb3c2 100644--- a/packages/core/tests/unit/test_alert_review.py+++ b/packages/core/tests/unit/test_alert_review.py@@ -61,7 +61,12 @@ def audit_events(monkeypatch: pytest.MonkeyPatch) -> list[tuple[str, str, dict]]def dms(monkeypatch: pytest.MonkeyPatch) -> list[tuple[int, str]]:sent: list[tuple[int, str]] = []- async def fake_dm(person_id: int, text: str, *, headline: str = "") -> tuple[bool, str]:+ async def fake_dm(+ person_id: int, text: str, *, headline: str = "", alert_id: int | None = None+ ) -> tuple[bool, str]:+ # Every review DM must say which alert it is about, so acking or+ # dismissing that alert can resolve it in the outcome ledger.+ assert alert_id is not Nonesent.append((person_id, text))return True, "sent"@@ -839,7 +844,9 @@ def test_draft_is_idempotent_across_passes(db: Path, monkeypatch) -> None:def test_failed_escalation_dm_is_not_counted_and_is_retried(db: Path, audit_events, monkeypatch) -> None:attempts: list[int] = []- async def flaky_dm(person_id: int, text: str, *, headline: str = "") -> tuple[bool, str]:+ async def flaky_dm(+ person_id: int, text: str, *, headline: str = "", alert_id: int | None = None+ ) -> tuple[bool, str]:attempts.append(person_id)return (len(attempts) > 1), "ok" if len(attempts) > 1 else "no channel"diff --git a/packages/core/tests/unit/test_outcomes.py b/packages/core/tests/unit/test_outcomes.pynew file mode 100644index 00000000..ebf49be0--- /dev/null+++ b/packages/core/tests/unit/test_outcomes.py@@ -0,0 +1,375 @@+"""Attunement outcome ledger: recording, resolution, rates, and their uses."""+from __future__ import annotations++import sqlite3+from datetime import UTC, datetime, timedelta+from pathlib import Path+from types import SimpleNamespace++import pytest++from openexecutive.attunement import open_loops, outcomes+from openexecutive.memory import episodic+from openexecutive.people import registry as people_registry+from openexecutive.people import store as people_store+from openexecutive.scheduler import nudge_engine++[email protected](autouse=True)+def _isolated(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ db = tmp_path / "test.db"+ monkeypatch.setattr(people_store, "DB_PATH", db)+ monkeypatch.setattr(episodic, "DB_PATH", db)+ episodic.initialize_db(db)+ people_store.initialize_db(db)+ people_registry.invalidate()+ monkeypatch.setattr("openexecutive.audit.log_event", lambda *a, **k: None)+ yield+ people_registry.invalidate()+++def team() -> SimpleNamespace:+ principal = people_store.upsert_person(full_name="Pat Principal", is_principal=True,+ slack_user_id="U_PAT", preferred_channel="slack")+ sara = people_store.upsert_person(full_name="Sara Kim", slack_user_id="U_SARA",+ preferred_channel="slack")+ return SimpleNamespace(principal=principal, sara=sara)+++def _outcome_rows() -> list[sqlite3.Row]:+ with sqlite3.connect(str(episodic.DB_PATH)) as conn:+ conn.row_factory = sqlite3.Row+ return conn.execute("SELECT * FROM proactive_outcomes ORDER BY id").fetchall()+++def _send(channel_ref: str = "U_SARA", *, web: bool = False) -> None:+ """Drive the real send-side recording point for one Slack DM."""+ from openexecutive.orchestrator.schedule_tools import _record_outbound_context, current_session+ from openexecutive.orchestrator.session import Session++ token = current_session.set(Session(from_web_chat=web))+ try:+ _record_outbound_context(channel="slack_dm", channel_ref=channel_ref, text="ping")+ finally:+ current_session.reset(token)+++def _seed(person_id: int, source: str, outcome: str | None, n: int, *, ref: str = "") -> None:+ now = datetime.now(UTC).isoformat()+ with sqlite3.connect(str(episodic.DB_PATH)) as conn:+ for _ in range(n):+ conn.execute(+ "INSERT INTO proactive_outcomes (created_at, person_id, source, ref, channel, "+ "channel_ref, outcome) VALUES (?, ?, ?, ?, 'slack_dm', 'x', ?)",+ (now, person_id, source, ref or None, outcome),+ )+++# --------------------------------------------------------------------------- #+# Recording+# --------------------------------------------------------------------------- #+++def test_untagged_send_records_nothing(team: SimpleNamespace) -> None:+ _send()+ assert _outcome_rows() == []+++def test_tagged_send_records_one_row_linked_to_its_context(team: SimpleNamespace) -> None:+ with outcomes.tag_proactive(outcomes.SOURCE_REFLECTION, "r1"):+ _send()+ [row] = _outcome_rows()+ assert (row["person_id"], row["source"], row["ref"]) == (team.sara, "reflection", "r1")+ assert row["outbound_context_id"] and row["outcome"] is None+ # The tag does not outlive its block.+ assert outcomes.current_tag() is None+++def test_send_to_unrostered_or_from_web_records_nothing(team: SimpleNamespace) -> None:+ with outcomes.tag_proactive(outcomes.SOURCE_REFLECTION):+ _send("U_STRANGER")+ _send(web=True)+ assert _outcome_rows() == []+++# --------------------------------------------------------------------------- #+# Resolution+# --------------------------------------------------------------------------- #+++def test_matched_reply_resolves_replied(team: SimpleNamespace) -> None:+ with outcomes.tag_proactive(outcomes.SOURCE_FOLLOWUP):+ _send()+ ctx_id = _outcome_rows()[0]["outbound_context_id"]+ assert episodic.mark_outbound_context_consumed(ctx_id)+ assert _outcome_rows()[0]["outcome"] == "replied"+ # One-shot: a second consume changes nothing.+ assert not episodic.mark_outbound_context_consumed(ctx_id)+++def test_loop_reported_done_resolves_its_chases_acted(team: SimpleNamespace) -> None:+ loop_id = open_loops.open_loop(owner_person_id=team.sara, description="send the quote",+ due_at=datetime.now(UTC))+ assert loop_id is not None+ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, None, 1, ref=f"nudge:commitment:{loop_id}")+ open_loops.close_open_loop(loop_id, reason="reported_done")+ assert _outcome_rows()[0]["outcome"] == "acted"+++def test_loop_expiry_does_not_count_as_acted(team: SimpleNamespace) -> None:+ loop_id = open_loops.open_loop(owner_person_id=team.sara, description="send the quote",+ due_at=datetime.now(UTC))+ assert loop_id is not None+ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, None, 1, ref=f"nudge:commitment:{loop_id}")+ open_loops.close_open_loop(loop_id, reason="expired")+ assert _outcome_rows()[0]["outcome"] is None+++def _alert(alert_id: int, routed_to: int | None = None) -> SimpleNamespace:+ return SimpleNamespace(id=alert_id, topic_tags=[], routed_to_person_id=routed_to)+++def test_alert_ack_credits_only_its_owner_and_the_principal(team: SimpleNamespace) -> None:+ from openexecutive.alerts.lifecycle import record_ack_feedback++ ben = people_store.upsert_person(full_name="Ben Ortiz", slack_user_id="U_BEN")+ _seed(team.sara, outcomes.SOURCE_ALERT_REVIEW, None, 1, ref="alert:7")+ _seed(ben, outcomes.SOURCE_ALERT_REVIEW, None, 1, ref="alert:7")+ _seed(team.principal, outcomes.SOURCE_ALERT_REVIEW, None, 1, ref="alert:7")+ record_ack_feedback(_alert(7, routed_to=team.sara), "ack") # type: ignore[arg-type]+ # Ben was DM'd on an earlier pass but it isn't his any more.+ assert [r["outcome"] for r in _outcome_rows()] == ["acted", None, "acted"]+++def test_dismissed_alert_voids_its_dms_and_never_counts_against_anyone(team: SimpleNamespace) -> None:+ from openexecutive.alerts.lifecycle import record_ack_feedback++ _seed(team.sara, outcomes.SOURCE_ALERT_REVIEW, None, 1, ref="alert:7")+ record_ack_feedback(_alert(7, routed_to=team.sara), "dismissed") # type: ignore[arg-type]+ assert _outcome_rows()[0]["outcome"] == "void"+ assert (team.sara, outcomes.SOURCE_ALERT_REVIEW) not in outcomes.acceptance()+ record_ack_feedback(_alert(8), "read") # type: ignore[arg-type]+++def test_review_closing_its_own_alert_resolves_its_dms(team: SimpleNamespace) -> None:+ from openexecutive.alerts.lifecycle import resolve_alert_outreach++ _seed(team.sara, outcomes.SOURCE_ALERT_REVIEW, None, 1, ref="alert:9")+ _seed(team.sara, outcomes.SOURCE_ALERT_REVIEW, None, 1, ref="alert:10")+ resolve_alert_outreach(_alert(9, routed_to=team.sara), "resolved") # type: ignore[arg-type]+ resolve_alert_outreach(_alert(10, routed_to=team.sara), "stale") # type: ignore[arg-type]+ assert [r["outcome"] for r in _outcome_rows()] == ["acted", "void"]+++async def test_resolved_approval_credits_its_nudges(+ team: SimpleNamespace, monkeypatch: pytest.MonkeyPatch+) -> None:+ import json++ from openexecutive.workflows import persistence as wf_persistence+ from openexecutive.workflows.resumer import apply_resolution+ from openexecutive.workflows.wait_for_human import WaitForHumanResolution++ monkeypatch.setattr(wf_persistence, "DB_PATH", episodic.DB_PATH)+ wf_persistence.initialize_runs_db(episodic.DB_PATH)+ wf_persistence.create_run("run-1", "test_wf", "Test run", {})+ wf_persistence.save_checkpoint("run-1", json.dumps({"channel": "slack", "channel_ref": "U"}),+ team.sara, datetime.now(UTC) + timedelta(hours=1))+ _seed(team.sara, outcomes.SOURCE_NUDGE_STALLED, None, 1, ref="nudge:stalled:run-1")+ resolution = WaitForHumanResolution(+ run_id="run-1", reply_text="approved", source_channel="web", source_message_id="m",+ parsed_decision={"decision": "approve", "note": ""}, person_id=team.sara,+ )+ assert await apply_resolution("run-1", resolution)+ assert _outcome_rows()[0]["outcome"] == "acted"+++def test_initiative_update_credits_its_check_ins(team: SimpleNamespace) -> None:+ episodic.store_initiative("Launch", "active", db_path=episodic.DB_PATH)+ [init] = episodic.get_active_initiatives(db_path=episodic.DB_PATH)+ _seed(team.sara, outcomes.SOURCE_NUDGE_INITIATIVE, None, 1, ref=f"nudge:initiative:{init.id}")+ episodic.store_initiative("Launch", "active", summary="on track", db_path=episodic.DB_PATH)+ assert _outcome_rows()[0]["outcome"] == "acted"+++def test_principal_tidying_a_loop_does_not_credit_the_owner(team: SimpleNamespace) -> None:+ ids = [open_loops.open_loop(owner_person_id=team.sara, description=f"deliver thing {i}",+ due_at=datetime.now(UTC)) for i in range(2)]+ for loop_id in ids:+ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, None, 1, ref=f"nudge:commitment:{loop_id}")+ open_loops.close_open_loop(ids[0], reason="done", closed_by_person_id=team.principal)+ open_loops.close_open_loop(ids[1], reason="done", closed_by_person_id=team.sara)+ assert [r["outcome"] for r in _outcome_rows()] == [None, "acted"]+++def test_principal_self_reminders_are_not_outreach(team: SimpleNamespace) -> None:+ with outcomes.tag_proactive(outcomes.SOURCE_FOLLOWUP):+ _send("U_PAT")+ assert _outcome_rows() == []+++def test_email_cc_is_not_counted_as_outreach(team: SimpleNamespace, monkeypatch: pytest.MonkeyPatch) -> None:+ from openexecutive.orchestrator import mcp_gateway+ from openexecutive.orchestrator.schedule_tools import current_session+ from openexecutive.orchestrator.session import Session++ people_store.update_person(team.sara, email="[email protected]")+ people_store.update_person(team.principal, email="[email protected]")+ token = current_session.set(Session())+ try:+ with outcomes.tag_proactive(outcomes.SOURCE_NUDGE_COMMITMENT, "nudge:commitment:1"):+ mcp_gateway._record_email_outbound_context(+ {"to": "[email protected]", "cc": ["[email protected]"], "body": "Any update?"}+ )+ finally:+ current_session.reset(token)+ assert [r["person_id"] for r in _outcome_rows()] == [team.sara]+++def test_rates_sweep_on_read_even_without_a_nudge_scan(team: SimpleNamespace) -> None:+ old = (datetime.now(UTC) - timedelta(hours=100)).isoformat()+ with sqlite3.connect(str(episodic.DB_PATH)) as conn:+ conn.execute(+ "INSERT INTO proactive_outcomes (created_at, person_id, source, channel, channel_ref) "+ "VALUES (?, ?, 'reflection', 'slack_dm', 'x')", (old, team.sara))+ stats = outcomes.acceptance()[(team.sara, outcomes.SOURCE_REFLECTION)]+ assert (stats.resolved, stats.positive) == (1, 0)+++def test_sweep_marks_only_stale_open_rows_ignored(team: SimpleNamespace) -> None:+ _seed(team.sara, outcomes.SOURCE_REFLECTION, None, 1)+ _seed(team.sara, outcomes.SOURCE_REFLECTION, "replied", 1)+ assert outcomes.sweep_ignored(datetime.now(UTC) + timedelta(hours=73), after_hours=72) == 1+ assert [r["outcome"] for r in _outcome_rows()] == ["ignored", "replied"]+ assert outcomes.sweep_ignored(datetime.now(UTC), after_hours=72) == 0+++# --------------------------------------------------------------------------- #+# Rates+# --------------------------------------------------------------------------- #+++def test_acceptance_counts(team: SimpleNamespace) -> None:+ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, "ignored", 5)+ _seed(team.sara, outcomes.SOURCE_REFLECTION, "replied", 3)+ _seed(team.sara, outcomes.SOURCE_REFLECTION, None, 1)+ stats = outcomes.acceptance()+ loops = stats[(team.sara, outcomes.SOURCE_OPEN_LOOP)]+ assert (loops.sent, loops.resolved, loops.positive) == (5, 5, 0)+ refl = stats[(team.sara, outcomes.SOURCE_REFLECTION)]+ assert (refl.sent, refl.resolved, refl.pending) == (4, 3, 1)+++def test_muted_needs_the_last_n_all_unanswered(team: SimpleNamespace) -> None:+ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, "ignored", 5)+ _seed(team.principal, outcomes.SOURCE_OPEN_LOOP, "ignored", 4)+ assert outcomes.muted_pairs(min_sends=5) == {(team.sara, outcomes.SOURCE_OPEN_LOOP)}+++def test_reflection_block_needs_enough_history(team: SimpleNamespace) -> None:+ from openexecutive.workflows.executive_reflection import _render_reflection_context++ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, "replied", 3)+ _seed(team.sara, outcomes.SOURCE_RESEARCH, "ignored", 2)+ [line] = outcomes.render_for_reflection()+ assert "Sara Kim" in line and "open-loop chases 3/3 answered" in line+ assert "research" not in line+ text = _render_reflection_context(period_label="p", today_data={}, activity=[],+ recent_alerts=[], external_signals=[], outreach=[line])+ assert "WHAT LANDS" in text+++# --------------------------------------------------------------------------- #+# Uses: nudge ranking, source mapping, API+# --------------------------------------------------------------------------- #+++def _candidate(scope: str, person_id: int, urgency: float, source: str) -> nudge_engine.NudgeCandidate:+ return nudge_engine.NudgeCandidate(+ scope_key=scope, intent_text="x", source="commitment", urgency_seconds=urgency,+ cooldown=timedelta(hours=48), person_id=person_id, outcome_source=source,+ )+++def test_ignored_source_is_ranked_last_on_longer_cooldown(team: SimpleNamespace) -> None:+ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, "ignored", 5)+ muted = _candidate("nudge:commitment:1", team.sara, -9999, outcomes.SOURCE_OPEN_LOOP)+ fresh = _candidate("nudge:commitment:2", team.principal, 0, outcomes.SOURCE_NUDGE_COMMITMENT)+ settings = SimpleNamespace(attunement_mute_min_sends=5, attunement_mute_cooldown_multiplier=3)+ cands, demoted = nudge_engine._apply_outcome_feedback([muted, fresh], settings)+ assert demoted == {"nudge:commitment:1"}+ assert next(c for c in cands if c.scope_key == "nudge:commitment:1").cooldown == timedelta(hours=144)+ ranked = nudge_engine._apply_caps(cands, max_total=10, max_per_person=2, demoted=demoted)+ assert [c.scope_key for c in ranked] == ["nudge:commitment:2", "nudge:commitment:1"]+++def test_one_answer_lifts_the_demotion(team: SimpleNamespace) -> None:+ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, "ignored", 5)+ settings = SimpleNamespace(attunement_mute_min_sends=5, attunement_mute_cooldown_multiplier=3)+ cand = [_candidate("nudge:commitment:1", team.sara, 0, outcomes.SOURCE_OPEN_LOOP)]+ assert nudge_engine._apply_outcome_feedback(cand, settings)[1] == {"nudge:commitment:1"}+ # One reply, resolved after the ignores, is the most recent outcome.+ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, None, 1, ref="nudge:commitment:9")+ outcomes.resolve_by_ref("nudge:commitment:9", outcomes.OUTCOME_REPLIED)+ assert nudge_engine._apply_outcome_feedback(cand, settings)[1] == set()+++def test_commitment_selector_labels_open_loops(team: SimpleNamespace) -> None:+ now = datetime.now(UTC)+ open_loops.open_loop(owner_person_id=team.sara, description="send the quote",+ due_at=now - timedelta(hours=1))+ [cand] = nudge_engine._select_stale_commitment_candidates(now, stale_days=3, cooldown_hours=48)+ assert cand.outcome_source == outcomes.SOURCE_OPEN_LOOP+++def test_dispatch_source_mapping(team: SimpleNamespace) -> None:+ from openexecutive.scheduler.runner import _outreach_source++ loop_id = open_loops.open_loop(owner_person_id=team.sara, description="send the quote",+ due_at=datetime.now(UTC))++ def action(kind: str, scope: str | None) -> episodic.ScheduledAction:+ return episodic.ScheduledAction(id=5, created_at="", run_at="", channel="slack_dm",+ channel_ref="U", intent_text="x", kind=kind, scope_key=scope)++ assert _outreach_source(action("proactive_nudge", f"nudge:commitment:{loop_id}")) == (+ outcomes.SOURCE_OPEN_LOOP, f"nudge:commitment:{loop_id}")+ assert _outreach_source(action("proactive_nudge", "nudge:commitment:99999"))[0] == (+ outcomes.SOURCE_NUDGE_COMMITMENT)+ assert _outreach_source(action("proactive_nudge", "nudge:stalled:r1"))[0] == (+ outcomes.SOURCE_NUDGE_STALLED)+ assert _outreach_source(action("proactive_nudge", "nudge:initiative:3"))[0] == (+ outcomes.SOURCE_NUDGE_INITIATIVE)+ assert _outreach_source(action("ad_hoc", None)) == (outcomes.SOURCE_FOLLOWUP, "action:5")+++def test_outreach_route_is_principal_or_owner(+ team: SimpleNamespace, monkeypatch: pytest.MonkeyPatch+) -> None:+ from fastapi import HTTPException++ from openexecutive.api.routes import chat as chat_route+ from openexecutive.api.routes import people as route++ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, "replied", 2)+ _seed(team.sara, outcomes.SOURCE_OPEN_LOOP, None, 1)++ def call(caller: int | None) -> list[route.OutreachStat] | int:+ monkeypatch.setattr(chat_route, "_resolve_caller_person_id", lambda req: caller)+ try:+ return route.get_person_outreach(team.sara, request=None) # type: ignore[arg-type]+ except HTTPException as exc:+ return exc.status_code++ [row] = call(team.sara) # type: ignore[misc]+ assert (row.source, row.sent, row.replied, row.pending) == ("open_loop", 3, 2, 1)+ assert isinstance(call(team.principal), list)+ assert call(None) == 403+ assert call(team.sara + 100) == 403 # no existence probe before auth+++def test_reset_paths_wipe_the_ledger() -> None:+ from openexecutive.clients.slots import _BLANK_WIPE_TABLES++ assert "proactive_outcomes" in _BLANK_WIPE_TABLESdiff --git a/packages/ui/src/app/people/[id]/page.tsx b/packages/ui/src/app/people/[id]/page.tsxindex d9f0b40f..69892b43 100644--- a/packages/ui/src/app/people/[id]/page.tsx+++ b/packages/ui/src/app/people/[id]/page.tsx@@ -8,9 +8,11 @@ import {closeOpenLoop,getPerson,getPersonOpenLoops,+ getPersonOutreach,updatePerson,type AvailabilityWindow,type OpenLoop,+ type OutreachStat,type Person,} from "@/lib/api";@@ -32,6 +34,51 @@ const ALL_SCOPES = [const CHANNELS = ["any", "slack", "discord", "telegram", "email"];+// ---------------------------------------------------------------------------+// How they respond to outreach (attunement outcome ledger)+// ---------------------------------------------------------------------------++function OutreachSection({ personId }: { personId: number }) {+ const [rows, setRows] = useState<OutreachStat[] | null>(null);++ useEffect(() => {+ getPersonOutreach(personId)+ .then(setRows)+ .catch(() => setRows([]));+ }, [personId]);++ if (!rows || rows.length === 0) return null;+ return (+ <section className="mb-6">+ <h2 className="text-xs font-semibold uppercase tracking-wide text-fg-muted mb-1">+ How they respond+ </h2>+ <p className="text-xs text-fg-muted mb-3">+ Proactive messages over the last 30 days. Kinds they reliably ignore are+ sent less often.+ </p>+ <div className="space-y-1.5">+ {rows.map((r) => {+ const answered = r.replied + r.acted;+ const resolved = answered + r.ignored;+ return (+ <div+ key={r.source}+ className="flex items-center justify-between gap-3 px-4 py-2 rounded-lg border border-line bg-surface-elevated text-sm"+ >+ <span className="text-fg capitalize">{r.label}</span>+ <span className="text-xs text-fg-muted">+ {resolved > 0 ? `${answered} of ${resolved} answered` : "no answers yet"}+ {r.pending > 0 ? ` · ${r.pending} pending` : ""}+ </span>+ </div>+ );+ })}+ </div>+ </section>+ );+}+// ---------------------------------------------------------------------------// Open loops — what this person owes (attunement)// ---------------------------------------------------------------------------@@ -723,6 +770,7 @@ export default function PersonDetailPage() {</section>{!person.archived && <OpenLoopsSection personId={personId} />}+ {!person.archived && <OutreachSection personId={personId} />}{/* Archive */}{!person.is_principal && !person.archived && (diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.tsindex 5f16099e..bf66cb46 100644--- a/packages/ui/src/lib/api.ts+++ b/packages/ui/src/lib/api.ts@@ -2500,6 +2500,24 @@ export async function closeOpenLoop(if (!res.ok) throw new Error(`Failed to close open loop: ${res.statusText}`);}+// Attunement outcome ledger: how a person responded to proactive outreach+// over the last 30 days, per kind of outreach.+export interface OutreachStat {+ source: string;+ label: string;+ sent: number;+ replied: number;+ acted: number;+ ignored: number;+ pending: number;+}++export async function getPersonOutreach(id: number): Promise<OutreachStat[]> {+ const res = await fetch(`${API_BASE}/people/${id}/outreach`);+ if (!res.ok) throw new Error(`Failed to load outreach: ${res.statusText}`);+ return res.json();+}+// Explicit 👍/👎 on one assistant reply (null clears it).export async function setMessageFeedback(sessionId: string,