AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
feat(today): show the owner what the Executive did and tell people their tasks (#464)
Rufusde3c7888792b
diff --git a/.env.example b/.env.exampleindex 25da91a1..9478c05d 100644--- a/.env.example+++ b/.env.example@@ -675,6 +675,12 @@ NUDGE_MAX_PER_SCOPE=3# ATTUNEMENT_LOOP_DEFAULT_DUE_DAYS=2# ATTUNEMENT_LOOP_TTL_DAYS=21# ATTUNEMENT_MAX_OPEN_LOOPS_PER_PERSON=15+# Someone assigned a task by someone else is told once, on their own channel+# (their quiet hours apply). false keeps assignments silent until the first chase.+# ATTUNEMENT_ASSIGN_NOTIFY_ENABLED=true+# On the first weekday of each month the owner gets one message counting what+# the Executive did last month (Pulse -> Your month has the full view).+# VALUE_SUMMARY_MONTHLY_ENABLED=true# 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 resolveddiff --git a/packages/core/openexecutive/api/routes/people.py b/packages/core/openexecutive/api/routes/people.pyindex 9fd70e38..ed9a3a2a 100644--- a/packages/core/openexecutive/api/routes/people.py+++ b/packages/core/openexecutive/api/routes/people.py@@ -486,6 +486,17 @@ def archive_person(person_id: int, request: Request) -> Response:# Open loops (attunement) — what each person owes# --------------------------------------------------------------------------- #+class AssignNoticeOut(BaseModel):+ """Whether the person was told about a task just assigned to them:+ ``sent`` (on ``channel``), ``held`` for their quiet hours or brief,+ ``not_reached`` (no channel worked) or ``skipped`` (their own task, or+ notices are off). A teammate assigning gets no channel, and ``later``+ in place of ``held``: those are the person's own settings."""++ status: str+ channel: str | None = None++class OpenLoopOut(BaseModel):loop_id: intowner_person_id: int@@ -493,6 +504,8 @@ class OpenLoopOut(BaseModel):description: strdue_at: strcreated_at: str+ # Set only on the response to an assignment.+ notified: AssignNoticeOut | None = Noneclass OpenLoopClose(BaseModel):@@ -555,14 +568,19 @@ _ASSIGN_REFUSED: dict[str, tuple[int, str]] = {response_model=OpenLoopOut,status_code=status.HTTP_201_CREATED,)-def assign_person_open_loop(person_id: int, body: OpenLoopCreate, request: Request) -> OpenLoopOut:+async def assign_person_open_loop(+ person_id: int, body: OpenLoopCreate, request: Request+) -> OpenLoopOut:"""Assign this person a task: an open loop, followed up once it is due.The principal or any active team member may assign one to anyone on the- team (themselves included); nobody is messaged now. Listing stays the+ team (themselves included). Someone assigned a task by another person is+ told once on their own channel (``attunement.assignment_notice``), and+ ``notified`` says how that went. Listing stays theprincipal's or the owner's (``GET`` above), so a teammate who assigns Bena task gets it back here but does not see Ben's other loops."""from openexecutive.api.routes.chat import _resolve_caller_person_id+ from openexecutive.attunement.assignment_notice import notify_assigneefrom openexecutive.attunement.open_loops import assign_open_loop, get_open_loop_visible_person(person_id, request)@@ -582,6 +600,10 @@ def assign_person_open_loop(person_id: int, body: OpenLoopCreate, request: Requereason = "unknown_owner"code, detail = _ASSIGN_REFUSED.get(reason, (409, "Could not assign the task"))raise HTTPException(status_code=code, detail=detail)+ notice = await notify_assignee(+ loop_id=loop.id, owner_person_id=person_id, assigned_by_person_id=assigner.id,+ task=body.task, due_at=loop.due_at,+ )return OpenLoopOut(loop_id=loop.id,owner_person_id=loop.owner_person_id,@@ -589,6 +611,9 @@ def assign_person_open_loop(person_id: int, body: OpenLoopCreate, request: Requedescription=loop.description,due_at=loop.due_at,created_at=loop.created_at,+ notified=AssignNoticeOut.model_validate(+ notice.as_dict(for_principal=bool(assigner.is_principal))+ ),)diff --git a/packages/core/openexecutive/api/routes/today.py b/packages/core/openexecutive/api/routes/today.pyindex 28565b01..ee283e02 100644--- a/packages/core/openexecutive/api/routes/today.py+++ b/packages/core/openexecutive/api/routes/today.py@@ -33,6 +33,7 @@ from typing import TYPE_CHECKING, Anyfrom fastapi import APIRouter, BackgroundTasks, HTTPException, Query, Request, Responsefrom pydantic import BaseModel, Field+from openexecutive.briefing.value_summary import ValueSummaryfrom openexecutive.clients.cockpit import ClientCockpitCard, format_practice_for_todayif TYPE_CHECKING:@@ -2084,6 +2085,25 @@ async def get_brief_delivery(request: Request) -> BriefDeliveryNotice | None:return await asyncio.to_thread(_brief_delivery_notice)[email protected]("/today/value", response_model=ValueSummary, tags=["today"])+async def get_today_value(+ request: Request,+ period: str = Query("month", pattern="^(month|week)$"),+ offset: int = Query(0, ge=0, le=24),+) -> ValueSummary:+ """What the Executive did for the owner this calendar month or week+ (``offset`` periods back), with the period before beside each count and+ the finished reports (``briefing.value_summary``). Every number is counted from the record,+ none is written by a model. The owner's alone: it counts their private+ rows, so anyone else gets 403."""+ from openexecutive.api.routes.people import caller_is_principal+ from openexecutive.briefing.value_summary import summarize++ if not await asyncio.to_thread(caller_is_principal, request):+ raise HTTPException(status_code=403, detail="Only the owner sees this summary")+ return await asyncio.to_thread(summarize, "week" if period == "week" else "month", offset)++# --------------------------------------------------------------------------- ## Solo Briefing cards: today's top three and the latest weekly review# --------------------------------------------------------------------------- #diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex e7f85156..d6916627 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -3419,8 +3419,20 @@ attunement:committed to: {text}" when self-assigned (the principal included, ineither mode). due_date is a local date → `_resolve_due` (17:00 userzone, clamped [today, +60d], default 2 days). Audited op `loop_assigned`.- Nobody is messaged at assignment: the owner is chased once due, like- any loop (the Executive may also call message_person when asked).+ When someone assigns a task to somebody else, the owner is told once+ (`attunement.assignment_notice.notify_assignee`): fixed text naming+ the assigner, the task and the due day, via+ `scheduler.runner.deliver_to_person` under `tag_proactive("task_assigned",+ "nudge:commitment:<loop_id>")`. `people.notifications.hold_for` applies+ on every channel (quiet hours / "In my briefs" → `held_messages.hold`).+ Self-assigned sends nothing; ATTUNEMENT_ASSIGN_NOTIFY_ENABLED=false+ turns it off. The tool result and the route's response carry+ `notified` {status: sent|held|not_reached|skipped, channel}; a+ teammate assigner gets channel null and `later` for held. The task is+ quoted inert (`_quoted_task`: _MARKUP_DEFANG + a code span, no model+ in between, so no links or fake Executive text). Audited+ `task_assignment_notice`, private to the owner. Otherwise the owner is+ chased once due, like any loop.Who: the principal or any active team member may assign anyone on theteam. Tool gate (`open_loop_tools._assigner`): principal on a verifiedsurface (`is_principal_on_verified_surface`) or a teammate on one@@ -4514,6 +4526,18 @@ people:pay a daily model + Honcho call for a note nobody sees.scheduler:+ monthly_value: |+ The owner's monthly tally (briefing/value_summary.py). A tick hook,+ `_maybe_send_monthly_value` → `value_summary.maybe_send_monthly`+ (every 15 min, one task at a time), not a scheduled_actions row. On the+ first weekday of the month (Sat/Sun roll to Monday), 09:00-18:00 in the+ user's zone, it summarizes last month and, unless every line is zero,+ claims scope `value_summary:YYYY-MM` in `briefing_narrative` (INSERT OR+ IGNORE, never released: one try) and sends `render_message` (the+ non-zero headline lines and a link to UI_BASE_URL/memories?tab=value)+ via `_deliver_to_principal` with private audit rows. Both workspace+ modes. Audited value_summary_sent / value_summary_not_sent (private).+ Off with VALUE_SUMMARY_MONTHLY_ENABLED=false.client_rotation: |New recurring kind client_rotation (multi-client practice mode; seeclients.rotation for the full design). Scheduler-side specifics: the@@ -4735,6 +4759,7 @@ today:- "GET /today/activity/daily?days=N — Returns DailyActivityResponse(days), the per-day counts behind the Pulse page's 'heartbeat' heatmap (the GitHub-contributions-style grid at `/memories`). Same source set and exclusions as /today/activity — the union of `decisions`, `advice_given`, status=done `scheduled_actions` (excluding the `nudge_scan` heartbeat and `__internal__` channel), completed `workflow_runs`, `initiatives`, resolved `decision_instances`, and `alerts` — but bucketed by calendar day (UTC) in `episodic.count_activity_by_day` rather than returned as individual items — decisions/advice by their `timestamp`, fired actions by `run_at` (fire time, not `created_at` queue time, so a cadence queued the night before counts on the day it fires), workflow runs by `updated_at` (completion), initiatives by `created_at`, resolved decisions by `resolved_at`, alerts by `created_at`. The `workflow_runs` and `alerts` tables are owned by other stores (not `episodic.initialize_db`), so each UNION arm is included only when its table exists — `count_activity_by_day` checks `sqlite_master` and still counts the sources episodic owns on a DB initialised by episodic alone. The response is DENSE: every calendar day in the window is present (count 0 when nothing fired), oldest→newest, so the UI renders a gap-free grid without client-side fill. A decision instance whose proposed payload is private (`\"private\": true`) and an alert tagged `private:principal` are not counted, as the feed leaves them out. `days` defaults to 90, clamped to 1..365 via FastAPI Query validation (422 on out-of-range). Read-only, unauthenticated (matches /today/activity and /memories/*), uncached."- "GET /today/top-three — solo only, principal only. Returns TopThreeToday {items: [{key, kind, text, why, slot}]} or null: null in team mode (effective_workspace_mode) and for anyone the stricter principal-only-run rule (`workflows._caller_is_the_principal`: own email on a non-archived principal entry, or no x-caller-email; never an unclaimed roster) does not admit. Built from the morning brief's own inputs and code — `open_loops.principal_due_soon()` handed to `briefing.top_three.build_top_three` — so the items, order and free slots match the solo brief. `slot` is the free block ('10:00–11:00', the user's zone), '' when no block is left, null when no calendar was read (none connected, a failure or the 4 s timeout, a non-business day). A separate route, never part of GET /today, so the Briefing never waits on the calendar read; the UI loads it after /today."- "GET /today/weekly-review — solo only, principal only (same gate). Returns WeeklyReviewSummary {run_id, completed_at, period, top_three, excerpt} for the latest completed weekly_review run — `persistence.list_runs(workflow_name='weekly_review', status='done', limit=1)` (newest updated_at; failed, running and other workflows never count) then `get_run` — or null when none has completed or the store cannot be read. `weekly_review.summarize_review` reads the artifact back as plain text: `period` from the title line (TITLE_PREFIX), `top_three` from the last TOP_THREE_HEADING section, and `excerpt` when that list is empty (the section's own note, else the first lines). `completed_at` is the run's updated_at. The UI links the run page, /jobs/runs/{run_id}."+ - "GET /today/value?period=month|week&offset=N — owner only (people.caller_is_principal; 403 otherwise). Returns ValueSummary {period, label, start, end, lines: [{key, label, count, previous}], deliverables: [{run_id, title, workflow_name, finished_at}], deliverables_total} from `briefing.value_summary.summarize`: the calendar month or Monday-first week in the user's zone, offset periods back (0-24), each line beside the period before. Every count is SQL over rows that prove the thing happened, never a model: messages_sent (DM handlers' kind=outbound ok rows, not held or suppressed, to anyone but the owner's own Slack/Discord/Telegram ids, plus Gmail/Outlook send-tool mcp rows whose result_preview has no error, so chat-sent mail counts though Done recently misses it), inbox_drafted / inbox_sent (the owner's delegation_reply_drafted, delegation_drafted, delegation_reply_sent rows), meetings_booked (create_calendar_event / create_instant_meeting skill rows not ok=false), briefs_delivered (scheduled_action phase=delivered, kind principal_*), reports (done workflow_runs with owner_person_id NULL, minus RHYTHM workflows; a teammate's own run is theirs alone; latest 10 listed), follow_ups (scheduled_action rows with action_id, phase delivered|held), tasks_tracked (open_loop rows created), tasks_closed (op=loop_closed reason=done), decisions (decision_instances resolved to a verdict), alerts (created), answered (chat_turn direction=out). Audit rows private to another member (private_to_person set) never count. Tables are existence-guarded; a missing one reads as zero. No hours-saved and no cost line (cost next to value reads as a bill; GET /audit/usage has it). UI: Pulse's Your month card and /memories?tab=value. The monthly message: see scheduler.monthly_value."- GET /morning-brief — deprecated alias for GET /today, kept for one release for older UI builds and bookmarks. Sends a Deprecation header with a Sunset date.lifecycle: |`proposals` is now the LIVE unread set (`alerts.lifecycle.list_live_alerts`:diff --git a/packages/core/openexecutive/architecture/prebuilt/agents.json b/packages/core/openexecutive/architecture/prebuilt/agents.jsonindex ed2c36ef..6ad92425 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. That context is per call and never cached: `<company_stage>` (the stage from the company profile — specialists never see the profile itself), in solo mode `<principal_role>` (what kind of principal the advice is for, in plain words, with their title and remit — `router.principal_role_context`), `<department_memory>`, `<past_decisions>`, `<failure_cases>`, `<relevant_knowledge>` and `<conversation_context>`, outermost first. The specialist's own system prompt is a static domain constant under one `cache_control` block, so it stays byte-identical across companies and profile edits. A chat turn takes the stage from its session's profile (the one the Executive reasons over, and the one an eval scenario injects); workflow steps and the MCP server's `consult_specialist` read it fresh from the profile on disk. The role tag follows the turn's mode: a chat turn pins the role on its session with the mode (`pin_turn_principal_role`: the session's `principal_role` override, else the workspace settings) and sends it in solo and nothing in team, so the org block, every specialist in the turn and any workflow the turn starts see the same role; callers with no chat turn read it fresh (`load_principal_role`: the current session's mode and role, else the workspace's), and a failed read sends no tag rather than failing the consult. The CFO, CSO and sales prompts key their advice on it: for a bootstrapped, self-funded or solo company they drop venture fundraising benchmarks and work from cash, and raise only if the founder wants to.\n\nRouting uses one `consult_specialist` tool. Beside it the Executive carries two skill tools, `search_skills` and `load_skill` (skills are shown to users as **playbooks**, and every playbook belongs to a workflow: one that follows it, or its own Quick workflow). Chat finds and reads playbooks but never creates or changes one: work worth repeating is offered as a workflow through `draft_workflow`, with the method written into its steps, because workflows read playbooks at run time (approved scheduled ones included) and this loop also runs on inbound email and chat, so only a person can change what a workflow follows. A hidden built-in is invisible to search and load; each `search_skills` hit lists the `workflows` that follow it, Quick ones included, and the persona routes \"the finished deliverable\" to that workflow and quick or partial asks to the playbook inline; Tool calls made while proactive work is tagged (scheduler dispatch, reflection, research, alert review) feed the Attunement outcome ledger. Goals have three tools: `list_department_goals`, `update_department_goal` (progress the user reports) and `create_goal` (a new goal the principal states, filed under an area by slug or title and creating the area when none matches — see Org). `create_goal` runs only for the principal on a verified surface, and no unattended run is offered it: the tools in `schedule_tools.UNATTENDED_WITHHELD_TOOLS` are dropped from reflection's and research's toolkits by `unattended_toolkit`, and from the chat loop when its Session is marked `unattended` — the scheduler's PROACTIVE TRIGGER run, whose prompt quotes stored intent text; a call the model emits anyway gets an error tool_result. `record_decision_outcome` records how a past decision turned out — the weekly review lists decisions older than 30 days with no outcome as `[decision N]` — writing `decisions.outcome` (`episodic.update_decision`) and auditing the rationale; it has `create_goal`'s gate (the principal on a verified surface only; everyone else gets an audited refusal) and is in `UNATTENDED_WITHHELD_TOOLS` too. A missing or unknown id returns the decisions still waiting on an outcome, so the model can retry with the right one. Its schema is static; the solo persona has one line on it, and team mode learns it from the tool description, so the team persona is byte-identical. 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. `assign_open_loop` opens one on request (\"ask Ben to send me the Q3 numbers by Friday\") for the principal or a rostered teammate on a verified surface — never an email, a turn private to the principal or an unattended run, which are also withheld the tool — and only when `task` appears verbatim in what the speaker typed this turn, at most 5 per turn; that turn's extraction pass then opens no second loop for the same owner. The roster write tools (`upsert_person`, `archive_person`, `set_department_head`) are the principal's alone, and only on a surface that verified the speaker — the web chat, the principal's own Slack or Discord, or a private Telegram chat when `TELEGRAM_WEBHOOK_SECRET` is set to a value Telegram can send (Telegram identifies the chat rather than the sender, and without that secret its webhook accepts anyone's update). A teammate, an email (even from the principal's address), Google Chat, the CLI, the MCP server and unattended runs get `status: refused` (audited, and no action chip), because a team member's People row is also the web sign-in and outbound-email allow-list. `upsert_person` takes `kind` (`team` / `contact`; a new person defaults to `contact` in solo mode, an update keeps the current kind) and `email_aliases` (other addresses the person writes from — the full list, replacing the current one; they match mail and may be emailed but never sign in, and one already on someone else is refused), and after every write any pending roster request whose sender now matches someone is closed and its held messages replayed. `resolve_roster_request` answers a **roster request** — someone not on the People list who wrote in and is waiting (see Org): `approve` (a new person; `kind` defaults to team for a company-domain sender, else contact, when the principal did not say), `link` (someone already listed, by `person_id`; `replace_channel_id` only when the principal said so) or `decline`. It has the roster tools' gate (the principal on a verified surface; audited refusal otherwise), is in `UNATTENDED_WITHHELD_TOOLS`, and answers only an id in `Session.trusted_roster_request_ids` — the ids the server printed that turn in a `<roster_requests>` block (`briefing.context.format_roster_requests_for_prompt`, up to 10 pending requests), which `render_and_trust` appends to the `<briefing>` digest on the principal's own verified turn only and records on the session in the same step, so an id the model invents or reads out of a message adds nobody. Each line is server-derived — id, channel, address or account id, the sender's name sanitised and marked unverified, a company-domain hint, the message count — and never what they wrote. The block rides in the **user turn**, like the digest, so the cached system blocks are unchanged; the tool definition is static, and the new tool only extends the sorted tool list. The web chat route resets the trusted set every turn, and a resolved id is removed from it. and `list_people` returns both kinds with `kind` — contacts only on the principal's own verified turn (they are private to the principal; anyone else gets the team as if no contact existed) — while `lookup_person` searches the team only. `ask_about_person` reads a person's peer memory fully only on their own verified turn; anyone else's answers only to a verified principal or teammate, and only when that person turned on \"Share my work style with the team\", framed to how they work and never their view of a colleague, and otherwise returns the same \"hasn't chosen to share\" result whether or not anything is known. A teammate's own mail with the Executive is theirs the same way: every mailbox call the model makes through the MCP gateway (Gmail or Outlook, by `call_tool`, from a script, or a workflow step run from chat) passes through `orchestrator.teammate_mail`. A search excludes every other teammate's address server-side and is filtered again entry by entry; any other call that names a message or thread (read, attachment, reply, forward, label) must use an id a filtered search returned to the same reader in this conversation (`Session.mail_ids_seen`) or the inbound email the turn answers; reads are filtered message by message, so a message naming another teammate is left out unless the reader is in its From / To / Cc; a reply that would quote such a thread, or an Outlook forward, reply or attachment read of such a message, is refused; and a conversation in which a teammate other than the principal was shown their own mail becomes theirs alone, as Act as me's do. Outside mail and the reader's own are untouched; an email turn reads as its sender only when Gmail authenticated it, and any other unverified reader sees no teammate's mail, a background run the model drives reads as the principal and a workflow step outside any session as nobody, an Outlook inbox rule that forwards or names another teammate is refused, and the poller and the brief, which read the mailbox themselves, are unaffected. Their own chats are theirs too: every audit row of a teammate's verified turn is theirs (`people_tools.teammate_turn_owner`, see Audit; the principal sees the actions, never the words), and a teammate's web chat or DM opens for them alone (`chat._session_access`), the principal included. The same verified-principal rule, as `people_tools.contacts_reachable_now()`, decides whether a turn may reach a **contact** at all: `message_person`, the raw DM tools, `create_calendar_event` / `create_instant_meeting` attendees and the MCP gateway's Gmail / Calendar / Drive / OneDrive gates treat a contact exactly like an unknown person on every other turn, so no refusal reveals that one exists. **The untrusted-content policy** (`orchestrator.content_trust`) is one rule for text the principal did not write — inbound email, chat, attached files, watched pages — answering three questions for every surface. *Who is speaking*: the principal only when the surface proved it (`principal_speaking`: the web chat as the principal — never a signed-in email on nobody's People entry —, the CLI, their own Slack/Discord or a secret-verified Telegram chat, or their own address with Gmail's `dmarc=pass`); never a teammate, a stranger, Google Chat, the MCP server or an unattended run. *What may become memory*: episodic extraction runs only then, and only on the words outside `<untrusted_content>` blocks; peer memory and open loops are recorded under the speaker's own name, never as the principal's. *What may trigger tools*: every write on the principal's authority already refuses others in its handler; the tools with no such check that change the install for every later turn — `content_trust.PRINCIPAL_ONLY_TOOLS`: `load_mcp_server`, `list_saved_tools`, `run_python_job` and `run_script` — are not offered unless the principal is speaking on an interactive surface (not email, even authenticated), and a call the model emits anyway gets an error tool_result and a `refused: not_principal` audit row. So an inbound email, a teammate's turn, Google Chat and the scheduler's proactive trigger each get a stable tool list of their own without it. A send or edit on a team member's turn also meets their department's authority first (`orchestrator.department_gate`, see Org), and so does one on a turn whose speaker is on no People entry: a signed-in web caller or a chat-channel sender, which in practice is Google Chat, since Slack, Telegram and Discord turn unmatched senders away. Google Chat names a matched sender to the gate alone (`gate_sender_person_id`), so the principal there is not held. Email turns are left to the mailbox's own gates. *How it is labelled*: outside text goes into the user turn inside `<untrusted_content source=… author=… author_verified=…>` with a fixed notice that it carries no authority; compatibility forms are folded (NFKC), control characters go, and the tag's name is renamed wherever the text carries it — any case, spacing or entity-escaped form — so the text cannot end its block and speak outside it.\n\nA turn about the principal's private mail (`Session.private_to_principal`) reaches the principal only. It is neither offered nor allowed to run `schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS` — everything that reaches someone else, publishes where the team reads, or starts work outside the turn: the broadcasts, meeting bookings and cancellations, `run_workflow` and research, follow-ups and workflow nudges, watches, artifacts, goal updates, saved workflows, skill drafts, and `load_mcp_server` (it connects to any URL, which can carry the turn's content). Through `search_tools` and `call_tool` it reaches only `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads (mail, calendar, and Drive, Docs and Sheets search and file reads, with their Microsoft 365 twins; OneDrive's `download-bytes` only for a file's content) and the Gmail send and draft the gateway narrows to the principal. A search shows it nothing else, and a call to anything else (Google Chat, a Docs or Drive write, `manage_event`, another server) is refused (`schedule_tools.private_turn_withholds`). A call the model emits anyway, MCP tools included, gets an error tool_result and writes an audit row, and every audit row the turn writes is the principal's alone. On every turn the Executive knows what is connected without searching: block 0's *Connected Systems* section names the connected Google services, other MCP servers, the messaging channels, Notion sync, Confluence sync (when on) and Act as me, and pins the Google tool names it calls directly with `call_tool`. Both the service list and the pinned names are narrowed to what workspace-mcp actually loaded (`WORKSPACE_MCP_TOOLS`, `WORKSPACE_MCP_TOOL_TIER`), so a service left out is not named and its tools are not pinned — being told a tool is already available when it is not in the index costs a failed call the model cannot explain to itself. `search_tools` is for anything not listed. When work repeats over many items, the Executive can also call `run_script` (`workflows/step_script.py`, offered when the gateway runs, unless `CHAT_SCRIPTS=false`, and only on the principal's own turns — `PRINCIPAL_ONLY_TOOLS`, withheld on an unattended pass too, because it spends the turn's whole call budget on code the model just wrote): one short Python script, run in a sandboxed Monty worker with no files, network or environment, whose only reach is the gateway tools `call_tool` could reach (those `search_tools` has returned; the gateway keeps that set for its own process-wide session, not per conversation). Each call it makes is a `call_tool` in every way that matters — the gateway's discovery, deny-list and recipient gates, Take the lead's gate on an unattended run (or the department gate on a team member's turn, see Org), and the same action chip and `tool_invocation` row (marked `via: run_script`, `ok: false` when it raised), as each call happens; the script itself gets a `kind: script` row with its source and result. Its wall clock is half the turn's deadline, so a long script ends with the list of calls it made rather than being cut off with the turn, and a stopped turn closes it and its worker. A turn private to the principal is not offered it, and the Act as me lockdown withholds it whole. Besides gateway tools, a chat script may call a fixed list of the Executive's own tools (`step_script.CHAT_OWN_TOOLS`: reads, alerts, open loops, goals, the watch list, follow-ups, `message_person`, `upsert_person` — nothing that broadcasts, books calendars, edits memory or skills, or starts workflows or research), each only when the turn is offered it and through the turn's own handler (Take the lead's gate included), with the same chip and a `kind: skill`, `via: run_script` audit row. A direct call needs a `tool_use` each, so a turn's scripts share a budget instead: `CHAT_SCRIPT_MAX_CALLS` (default 200) calls in all, and per-turn caps on own tools that could otherwise act in bulk (`CHAT_OWN_TOOL_CAPS`: `message_person` 10 — messaging the whole roster would be a broadcast — `upsert_person` 25, `create_alert` 50); a refused call tells the model to say what is left. A call stopped mid-flight by the script's clock or the turn still gets a `cancelled` audit row, since it may have run. Because every round re-reads the conversation, the loop also nudges at the moment of choice: after a round whose results include a list of five or more items (`step_script.lists_many`), with `run_script` on offer and not used that round, it adds the constant `FANOUT_HINT` as a text block in that round's user message (never a cached block), once a turn, pointing the per-item work at one built tool. For library work on files (PDFs, spreadsheets, charts, images) the chat also has `run_python_job` (see Workflows → Python jobs): Python with a fixed library set in a Deno-isolated WebAssembly sandbox, fed Knowledge files by name, the message's own attachments as sent, or text it already holds, and able to keep a job that worked as a Custom tool, with result files linked for the principal to download; it is offered only on the principal's own turns and only where the sandbox is installed (not offered otherwise, so the tool prefix stays fixed per process). Agent Activity shows each run as one \"Built tool\" card (debug event `script_run`: ok, the calls it made, how many, how long, and the kept or reused tool's name). The persona's tool-building section is present only when chat scripts can actually run (the setting and Monty installed). `TOOL_BUILDING_ADDENDUM` in the cached persona tells the Executive when to build a tool — a job that looks something up and then checks or acts on each result, paged results, more than about ten items, or an answer that needs three or more reads (find, open, read; the tool returns only what answers the question, not whole documents, and only what is about to be edited or quoted at length is read in full), while a handful of items already named go as direct calls in one turn — and never to say it has none, and to talk about it as building a tool or doing it in one go. On the principal's own verified, interactive turns, a script that works can be saved as a named tool (`save_as`; elsewhere the script runs but is not saved) and run again with `run_script(tool=…, inputs=…)`; `list_saved_tools` (a constant definition, in `PRINCIPAL_ONLY_TOOLS` with `load_mcp_server`, so offered only while the principal is speaking on a verified, interactive surface; `run_script(tool=…)` is refused on any other turn) lists them, and each call a saved tool makes is a gateway call like any other (see Workflows → Saved tools). The tool's definition is a constant, so the cached tool prefix does not move. 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 (3 built-in and 2 company chunks by default, see the RAG section) before the specialist sees the question. The fan-out is failure-isolated per call: a specialist that raises or returns no text becomes an `UNAVAILABLE` tool_result (`router.specialist_unavailable_result`) instead of failing the whole turn, and its area — \"finance\", \"legal\", never the specialist's name — is reported to the user under the web reply, or by the Executive in its reply on other channels, unless another call to it answered that turn. A failed specialist does not count as consulted, so it takes no committee seat. Cancellation (Stop) still propagates. The Executive then synthesizes the returned analyses into one reply.\n\n`remember_fact`, `forget_fact` and `update_company_profile` (`orchestrator/fact_tools.py`) make a correction stick: the first two keep or retire a standing fact in `memory.facts`, and the third changes one field of the company profile. They share `record_decision_outcome`'s gate (the principal on a verified surface, an audited refusal for everyone else) and are in `UNATTENDED_WITHHELD_TOOLS`. `remember_fact` alone also admits a rostered teammate on a verified surface (web signed in, their own Slack or Discord): the fact is stored attributed (`recorded_by_role=\"teammate\"`, rendered `(per <name>)`), and is held as a `proposed` row (`awaiting_approval`) until the principal approves it, unless the principal marked that teammate trusted (\"needs my approval\" off; on by default) — and even then when it would replace the principal's fact. All three are also in `PRIVATE_TURN_WITHHELD_TOOLS`, since what they write or retire is read on everyone's turns. On the principal's own authenticated email (primary address, with Gmail's own `Authentication-Results` reporting `dmarc=pass`, not forwarded) the three tools check the request as usual, then hold it as `awaiting_confirmation`. It applies only when the principal replies to a one-time token emailed to their own address (`integrations.fact_confirmation`); the split into a check step and an `apply_*` step lets chat and the confirmed reply share one apply path. Each write also needs a `source_quote` found in the speaker's own words this turn. The active facts reach every specialist as a `<standing_facts>` user-turn tag: `route_to_specialist` reads them (None → the store, \"\" → none) for chat consults and workflow steps alike, and `BaseAgent.analyze` places the tag next to `<past_decisions>`, never in the cached specialist system prompt.\n\nThe ten 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| `sales` | `SalesAgent` | sales |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5-5`; the deep-reasoning tier (CSO, CFO, GC, Board) runs on `DEEP_REASONING_MODEL`, `claude-sonnet-5-5` by default, with adaptive thinking; routing/fast classification uses `claude-haiku-5-5`. Requests are fitted to the model's generation on the way out (`feature_gate.fit_claude_generation`): 5-generation Claude models never receive `temperature` / `top_p` / `top_k`, and Haiku 5.5, which thinks unless told otherwise, gets thinking turned off when the caller asked for none. 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. A PDF `document` block is translated too: it becomes an OpenAI `file` part, and OpenRouter requests carrying one add the `file-parser` plugin (`native` for models whose catalog entry lists `file` input, else `PDF_OPENROUTER_ENGINE`, default `mistral-ocr`). `FeatureSpec.supports_pdf_input` gates it per model — off for a local server unless `LOCAL_PDF_INPUT` — and a gated-off PDF becomes a text note rather than vanishing. The Council picks a model in two steps: a **Provider** dropdown (Anthropic, OpenAI, Google, Meta, DeepSeek, xAI, Local, …), then a **Model** dropdown limited to that provider, with readable names (\"Claude Opus 5.5\") and the raw id and serving route shown underneath. The Anthropic group combines the direct Claude models (`claude-fable-5-1`, `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5-5`, `claude-sonnet-5`, `claude-haiku-5-5`, `claude-haiku-4-5`) with any Claude generation that exists only on OpenRouter, and never lists a model twice. With `OPENROUTER_ENABLED`, the 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. Every Council agent also takes **additional instructions** (`agent_overrides.instructions`): text appended after its prompt by `agents.overrides.append_instructions` inside an `<additional_instructions>` block. `BaseAgent.base_system_prompt()` is the built-in prompt or its full replacement (what the Council's editor shows); `effective_system_prompt()` is that plus the instructions (what every call sends), and the Executive gets the same text through `build_system_blocks(persona_instructions=…)`. Unlike a replaced prompt, instructions leave the agent on its built-in prompt, so prompt improvements keep reaching it. A **Quality** choice above the agents (`agents.presets`) sets every agent's model and deep reasoning at once: **Fast** puts every agent on a small model (`claude-haiku-5-5`, else `claude-haiku-4-5`) with deep reasoning off, **Balanced** returns each agent to its built-in defaults, and **Thorough** puts the Executive and the domain specialists on the largest allowed model (`claude-opus-5-5`, else `claude-opus-5`) with deep reasoning on where the model supports it, leaving triage and the helpers below on their defaults. Presets change quality only; they never cap spend. Each preset resolves against the install's model allowlist at request time and is offered only when one of its models is allowed. Applying one writes ordinary per-agent overrides (model and deep reasoning only), so history, rollback and later per-agent edits keep working; an agent changed on its own afterwards shows as **Custom**. Each Council agent has a **visibility**: `core` for the Executive and the domain specialists (`BaseAgent.visibility = \"core\"`, which a new specialist must declare) and `internal` (the default) for triage and the helper agents below. Thorough moves only core agents. The Council opens in a **simple view**: the Quality choice, the voice picker, and only the core agents, each with its additional instructions and a model badge. **Show all agents** lists the internal ones too, and **Advanced** opens the full page (the browser remembers the choice). Eight 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), `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments), `workflow_designer` (runs the conversational New workflow wizard on `/jobs/new`: searches the available tools, asks clarifying questions, then drafts a validated dynamic-workflow definition for the user to review), and `workflow_actor` (runs a workflow's `action` steps: a bounded tool-use loop limited to the tools the user approved for that step). `fixture_generator`, `engagement_intake` and `onboarding_interviewer` 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. When the workspace is in solo mode, `onboarding_interviewer`'s first user turn is prefixed with a short hint (`interview.solo_hint(role_kind)`, one static constant per role kind from the onboarding role step): the draft names only the principal, as principal, and no departments; an owner is asked about the offer, customers, pricing, cash and runway, an in-house executive about their organisation (drafted as the company — their employer), function, remit, manager, team size as context and what they are measured on, an independent about their practice, clients and pricing, and with no role given the role-neutral `SOLO_HINT` asks which they are. The hint rides in the user turn and the tool array is unchanged, so the cached system prompt and tool prefix are the same in both modes.\n\n**Voice.** The Executive answers in one voice persona, substituted into block 0 at `{VOICE_PERSONA}` (`personas/loader.get_active_body`) from the Executive override's `voice_persona_slug`. Three general voices ship in `personas/builtin/`: **Direct** (`default`, the slug used when none is set: answer first, brief and decisive), **Supportive** (a warm coach who explains the why and checks how the plan sits) and **Analytical** (numbers first, options and trade-offs, then one recommendation). They are offered by a shared picker in setup (`/onboard`, after the workspace choice) and in Settings → Executive, which saves through `PATCH /agents/executive`; a built-in voice's frontmatter carries the picker's one-line `description` and `sample` reply. The named-executive voices are marked `legacy: true`: the picker hides them, but they still load, so an install that picked one keeps it, and the Agent Council lists them under \"Legacy voices\". Voice files hold disposition only; the response-length ladder lives in `prompts/executive_persona.py`, and a test keeps numeric length rules out of every voice file. An eval scenario may set `voice_persona` to answer in a voice; it rides on `Session.voice_persona_slug`, which wins over the override for that session only.\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\n**Solo mode.** When the workspace (or the turn's session) is solo — one person using Open Executive for themselves — the Executive works for that one person, the principal, whatever their role: they may run their own business, lead a function inside a larger organisation, or work independently, and the persona reads which from the context instead of assuming it — the role lines under \"Your Principal\" in the org block, when the principal gave their role (workspace settings: kind, title, reports to, remit, measured on). Its persona swaps the team sections (\"You Are a Member of This Executive Team\", \"Choosing Who to Tell\", \"Departments & Org Coordination\") for \"You Work for One Person\", \"The People in Their World\", \"Who Hears From You\" and \"Goals and Areas\". Solo means only the principal uses Open Executive — not that they have no people: their manager, direct reports, peers, clients, investors and board are contacts. The Executive helps the principal work with them (a 1:1 or review prep, an update or budget case for their manager or board, a negotiation) but does not coordinate them, contacts them only when the principal asks and only if they are a contact, and never offers to loop the principal in. Every specialist stays relevant — HR for the principal's own reports, board and investor communications for reporting upward. Goals are grouped by *area* (the tools' `department_slug` is the area's slug). The chat loop withholds `send_department_message`, `send_company_broadcast` and `set_department_head` from its tool list, and a call to one of them anyway gets a JSON error tool_result instead of running. The mode is resolved once per turn and pinned on the session, so the persona, the org block, the tools and every tool handler agree — a switch made mid-turn applies from the next turn. Team mode is unchanged.\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\n`recall_history` (Always in the loop, `orchestrator.history_tools`) reads the speaker's own notes, on the same terms as `ghostwrite_email` below: its own registry, offered only on a verified turn in a conversation private to them with their switch on; its `due` flag lists only dated notes, soonest first (see Memory). The ghostwriter below also gets the writer's notes from mail every recipient was on, as a consistency check (`<writer_noted>`).\n\nThe morning reflection, which has no question to look up and no specialist to consult, gets one more read-only tool of its own: `search_knowledge` (`orchestrator.knowledge_tools`), the same knowledge lookup a chat turn makes, for what the company's documents say about a customer, contract, price or policy before it acts.\n\nA fifth, `remind_me` (`orchestrator.reminder_tools`), sets a plain-text reminder sent to the speaker alone when it is due; it opens no mailbox, so it never locks a turn. A sixth, `propose_actions` (`orchestrator.action_card_tools`), does nothing itself: it leaves the speaker a card of up to five actions (a meeting, a message, a new contact) that happen only when they tap Approve, so it stays on after a turn read mail; it is where what an email itself asks for goes, since that is never done on the email's say-so. Four read-only tools beside it read the speaker's own mailbox on the same terms — `search_my_email`, `read_my_email`, `read_my_email_attachment`, `my_email_awaiting_reply` (`orchestrator.mail_read_tools`) — capped per turn, other people's messages and attached files returned as untrusted blocks (see Act as me). One tool writes under someone else's name, and it is fenced in code rather than the prompt. `ghostwrite_email` (**Act as me**, `orchestrator.delegation_tools`) writes an email as the person the Executive is speaking with and saves it as a draft in their own mailbox, Gmail or Outlook (`delegation.gmail.gmail_for` picks the client by the person's credential); chat never sends it (the person sends it themselves, or taps Send on its card). It lives in its own registry, never `_ALL_SKILL_TOOLS`, so reflection, research and workflow toolkits can never carry it. The chat loop adds it only on a turn `delegation.settings.pin_turn_delegation` offered it to — the principal, or a team member once the owner lets them, with it on, verified, in a conversation private to them (the web chat, a Slack or Discord DM, a verified private Telegram chat), on an attended turn — and builds that turn's handler map from both registries, so on any other turn a call to it is an unknown tool. From the round that calls it until the turn ends, the dispatch guard refuses only what opens an outside address, runs a script or workflow, or posts to everyone (`delegation.lockdown`), without changing the offered list; messages and invites to the roster, follow-ups, facts in the person's own words and a contact they name still run, each fenced in its own path. A later turn in the conversation stays private to its owner but holds nothing: the person asking again, having read the reply, is their own request. A contact add the lockdown refuses becomes an approval card in the chat instead (`propose_actions`). Recipients are chosen in code, never by the model (a draft's new email may go to any address, named back to check when it is neither on the roster nor typed), and the text comes from the **ghostwriter** (`delegation.ghostwriter`), a tool-less call with a constant prompt plus the person's \"How I write\" profile. The ghostwriter is deliberately not a Council agent: the Council's edit routes have no principal check. See **Act as Me (Delegation)**. A second tool joins the same way: `recall_history` (`orchestrator.history_tools`, Always in the loop) reads the speaker's own notes of what they said, by email or in chat. It has its own registry and per-turn handler map too, and the loop adds it only when `history_tools.recall_person` finds the speaker verified, in a conversation private to them, on an interactive turn that isn't private to the principal, with their notes switch on. It doesn't need Act as me. After every chat turn the Executive also hands the speaker's own words to `history_chat.schedule_chat_notes`, which takes notes in the background when their switch is on and the surface verified them (see **Memory**).\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`). `run_workflow` runs the weekly review, and in solo mode the morning brief, only for the principal on a verified surface (`Workflow.principal_only_modes`, `create_goal`'s rule); anyone else gets an audited refusal that does not name the rule. A run whose `result` event reports `private_to_principal` (the morning brief on the principal's own verified turn, when it read their private rows) still returns its artifact into that turn, but the stored run keeps `persistence.PRIVATE_RUN_ARTIFACT` instead of the text, since run history is readable by everyone signed in. This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nDeliverables are first-class too. `orchestrator.artifact_tools` gives the Executive three tools: `draft_artifact` publishes a memo, web page (`html`), Word document (`docx`), spreadsheet (`xlsx`, from structured `sheets`) or a `link` to something it created in one of the principal's connected apps through the generic MCP gateway (`search_tools` → `call_tool`, any server — no vendor is named), and returns the artifact's id and link; `list_artifacts` and `get_artifact` let it find and reread its own past work (drafts and workflow outputs alike, through the same `artifact_records` read model the API uses). Every artifact belongs to someone: a draft to the person whose turn published it (`artifact_records.current_viewer`; with nobody speaking, the scheduler or the CLI, the principal), and a run someone started by hand to them, while scheduled runs are the team's. The tools, the recall, `message_person`'s link and mail attachments only ever reach the speaker's own (a link is refused when the recipient couldn't open it), not even the principal sees a teammate's, and a speaker who isn't on the People list publishes nothing. A workflow's own session inside someone's turn (the research synthesis) is pinned to that turn's viewer (`Session.documents_viewer`). Revising is `draft_artifact(supersedes=<id>)`, which archives the earlier version. When the principal asks for a deliverable the tool is always used; the \"quiet is the right default\" bar applies only to unprompted drafts. The format enum is a hard-coded sorted tuple so the cached tool schema stays byte-stable. Delivery: `message_person(person_id, text, artifact_id?)` appends the artifact's title and a `UI_BASE_URL/artifacts/<id>` link (through the same outbound guard as any DM; the link needs Open Executive access), and a Gmail send/draft can attach the file itself by `artifact_id` — see Integrations.\n\n**Extensions** (`orchestrator.extensions`). An install can add chat tools and kinds of document without changing this code. `OPENEXECUTIVE_EXTENSIONS` names Python modules. The first turn, or the first Documents read, imports each one and calls its `register()`. A module that fails is logged and skipped. `register_tool` takes an `ExtraTool`: a definition, an async handler, an optional `tool_groups` group (new or existing) and an optional chip. It refuses a name the loop already knows (`executive.builtin_tool_names`). An extension tool is never in `_ALL_SKILL_TOOLS`, so reflection, research and the synthesis never see it. The chat loop adds it per turn, like the Act as me tools, but never on an unattended run, a turn private to the principal or to a speaker who isn't on the People list (mail from a stranger), and only where its own `offered(session)` says. That predicate depends only on the kind of turn, so each kind of turn keeps one cached tool list. Act as me's lockdown refuses it once the turn has read the owner's mail, because it is unclassified and the lockdown fails closed. Its chip goes through `action_chips.summarize_action`, which applies the same no-chip rules for an error or refusal and keeps a link to a path inside the app. `register_collection` adds a kind of document: a drafted artifact tagged `collection:<name>` carries that collection on its record. The Documents page gives each collection its own filter. The collection's `on_change` hears about archive, restore and delete before they happen; if it raises, the change does not happen. `draft_artifact(supersedes=…)` refuses a collection's document. The alert pipeline strips `collection:` tags, so only the extension's own code files a document in its collection. A module that fails partway through `register()` leaves nothing registered. A tool registered with `workflow=True` is also offered to workflow action steps as `oe__<name>` (see Workflows); `read_only=True` marks one that only reads. A step runs with nobody in the turn, so `offered` isn't asked: `extensions.in_workflow_step(name)` is True for that tool, during its call only, and the handler decides what an unattended call may do.\n\nDocuments come in the other way through `read_document` (`orchestrator.document_tools`): it reads a PDF, Word, Excel, CSV, Markdown or text file by `path` — one another tool saved, such as a Gmail attachment (`get_gmail_attachment_content`) or a Drive file (`get_drive_file_download_url`) — or a company document by `filename`, with an optional PDF `pages` range. A scanned PDF is converted (`knowledge.pdf_reader`: local OCR by default; with `PDF_PROVIDER_READING=true`, the deployment's own model through its provider's PDF support, falling back to local OCR) rather than returned empty. Reads are confined to the tool download folders — the same resolve-then-contain check as `oe__read_file` — plus the company docs folder, and it is withheld on turns private to the principal (`PRIVATE_TURN_WITHHELD_TOOLS`): those come from a contact's email, whose own attachments the poller has already read into the turn, and must not steer the Executive into company documents.\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.\n\n**Take the lead** (`orchestrator.take_the_lead`) is how the Executive acts on its own, behind one gate. It has two switches, both off until someone turns them on. **As the Executive** is the principal's alone (`PUT /take-the-lead`). With it on, the unattended passes (reflection, research, the scheduler's proactive trigger) keep the acting tools solo mode otherwise withholds from them: booking, starting workflows, and messaging teammates rather than only the principal. `schedule_tools.unattended_toolkit` and the chat loop's unattended path then wrap every acting tool (`ACTING_TOOLS`, plus any MCP tool whose name sends, creates, updates, deletes or shares) in `gated_handlers` / `gated_call_tool`. The principal-only tools (`UNATTENDED_WITHHELD_TOOLS`) stay withheld, and every guard inside a handler still applies, including department approval levels (a booking in a department on Proposes is still a proposal) and the contact-egress rule. New mail or chat (any turn with an `origin_channel`) wakes the existing reflection early (`take_the_lead.wake`): one run waiting at most, five minutes after the first message and no more than every 30 minutes, as a one-off `take_the_lead_wake` scheduled action. Pause holds it like any scheduled work. **As you** is the Handle it for me dial's top step (delegation section).\n\n**The gate** is plain code (`take_the_lead.check`). Six kinds of action wait for a yes first, each with an Ask first switch, all on to start. The switch is the decision ledger's own mode for the class `take_the_lead_action:<kind>` (`propose` asks first, the default; `auto_execute` doesn't). The kinds are money, contracts and legal, hiring and people decisions, deleting/cancelling/sharing, someone new (an address on neither the roster nor the contacts) and big sends (a broadcast or department message, or more than five people). On top of these, the company (set by the principal) and each person (for their own As you) add structured rules: a person or address, a domain, words, or an amount at or above a figure. Added rules always hold, and an error reading them holds the action. The one thing the gate lets straight through is a direct message (`message_person` or a Slack, Telegram or Discord DM) whose only recipient is the principal (`_only_to_principal`): they are who it would wait for, so a card would only ask them to approve a message to themselves. Anything that reaches or acts on anyone else is checked, and a roster that can't be read is not the principal. A held action becomes a `take_the_lead_action` decision instance with a companion `DECISION_ALERT_SOURCE` card on Today, routed to the first teammate holding one of its People approval ranges (`take_the_lead.approval_ranges`, plain code, closest fit first: money to `spend_lt_2k`, `spend_lt_10k` or `spend_gt_10k` by its largest amount, with a higher range able to approve a lower one and no amount read as large, or to `customer_credit` for credit and payment terms; vendor contracts to `vendor_onboarding` then `legal_sign`, other contracts to `legal_sign`; hiring to `hiring_signoff`; anything else about the board or investors to `board_comms`; in Personal as in team mode), or else the principal through the authority gate's fallback (`departments.authority._route_proposal`). Deletes and shares always go to the principal. Only the principal and that approver see or resolve it (`DecisionClassSpec.principal_and_approver`). Approving it claims the row and carries out the exact call once (`take_the_lead.carry_out`: the unwrapped handler, or the gateway's `call_tool`, on an unattended session, with contact egress only when the principal approves). Declining drops it. Everything done or held is a row in `take_the_lead_log`. What it did and what was approved show in Recent activity (`today._build_activity`, kind `took_the_lead`), named but never quoted, since that feed is the team's. The held card's own `decision_resolved` row is left out because its payload quotes the message. `GET /today/activity` also adds the caller's own Handle it sends (kind `sent_as_you`, actor `you`), which are never in the shared feed.\n\n**In training.** The As the Executive switch has three positions: Off, **In training** and On (`take_the_lead.training`). In training, an action the gate would let through still waits, as a `training` hold for the principal alone, unless the principal has allowed that action with that person or thing (`take_the_lead.allowance`: \"Message Priya Nair\" covers a message to her on any channel; \"Book meetings with Priya Nair and Sam Lee\" meetings with exactly them; a workflow by id; a connected tool by name and the file it names, never one that reaches people such as a mail send or a share). The card carries Approve, **Approve + allow**, **Edit** (the message, a meeting's title, times or description, a task and its due date: `take_the_lead.apply_edits`) and Decline. Allowing is the principal's alone and needs a request the API can tie to them, as turning it on does; the six kinds and the added rules hold whatever is allowed. An edit approved with \"Do it like this next time\" is kept as an example (only the edited text, the principal's own words), and `take_the_lead.learned_note` hands the examples and the fact it's in training to the reflection and research passes in their user turn. After `SUGGEST_AFTER` (3) unchanged approvals of the same action in 30 days, Settings suggests allowing it. What it's learned is one list keyed by feature (`take_the_lead_allowed.feature`), so other features that learn from approvals can join it; each keeps its own switch. Act as me is the second (`act_as_me`, per person, `delegation.training`), with a training switch per setting (Replies, Follow-ups, Suggested actions, Drafts): its rows carry the person's id and the setting in their key, are listed and removed by that person alone, count toward their own cap, and never reach `learned_note`.\n\n**AI disclosure.** Nothing the Executive sends to people outside the web chat goes without saying it is an AI: plain code adds the line in the MCP gateway (mail) and at each chat send (Slack, Telegram, Discord, Google Chat replies, its DMs and room posts), never the prompt, so the persona and the cached system blocks are unchanged and a reply the model writes can't drop it. Replies the inbox watcher writes as a person carry their own line by that person's switches. See Integrations → **AI disclosure** and Act as me → **AI line on replies**.\n",+ "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. That context is per call and never cached: `<company_stage>` (the stage from the company profile — specialists never see the profile itself), in solo mode `<principal_role>` (what kind of principal the advice is for, in plain words, with their title and remit — `router.principal_role_context`), `<department_memory>`, `<past_decisions>`, `<failure_cases>`, `<relevant_knowledge>` and `<conversation_context>`, outermost first. The specialist's own system prompt is a static domain constant under one `cache_control` block, so it stays byte-identical across companies and profile edits. A chat turn takes the stage from its session's profile (the one the Executive reasons over, and the one an eval scenario injects); workflow steps and the MCP server's `consult_specialist` read it fresh from the profile on disk. The role tag follows the turn's mode: a chat turn pins the role on its session with the mode (`pin_turn_principal_role`: the session's `principal_role` override, else the workspace settings) and sends it in solo and nothing in team, so the org block, every specialist in the turn and any workflow the turn starts see the same role; callers with no chat turn read it fresh (`load_principal_role`: the current session's mode and role, else the workspace's), and a failed read sends no tag rather than failing the consult. The CFO, CSO and sales prompts key their advice on it: for a bootstrapped, self-funded or solo company they drop venture fundraising benchmarks and work from cash, and raise only if the founder wants to.\n\nRouting uses one `consult_specialist` tool. Beside it the Executive carries two skill tools, `search_skills` and `load_skill` (skills are shown to users as **playbooks**, and every playbook belongs to a workflow: one that follows it, or its own Quick workflow). Chat finds and reads playbooks but never creates or changes one: work worth repeating is offered as a workflow through `draft_workflow`, with the method written into its steps, because workflows read playbooks at run time (approved scheduled ones included) and this loop also runs on inbound email and chat, so only a person can change what a workflow follows. A hidden built-in is invisible to search and load; each `search_skills` hit lists the `workflows` that follow it, Quick ones included, and the persona routes \"the finished deliverable\" to that workflow and quick or partial asks to the playbook inline; Tool calls made while proactive work is tagged (scheduler dispatch, reflection, research, alert review) feed the Attunement outcome ledger. Goals have three tools: `list_department_goals`, `update_department_goal` (progress the user reports) and `create_goal` (a new goal the principal states, filed under an area by slug or title and creating the area when none matches — see Org). `create_goal` runs only for the principal on a verified surface, and no unattended run is offered it: the tools in `schedule_tools.UNATTENDED_WITHHELD_TOOLS` are dropped from reflection's and research's toolkits by `unattended_toolkit`, and from the chat loop when its Session is marked `unattended` — the scheduler's PROACTIVE TRIGGER run, whose prompt quotes stored intent text; a call the model emits anyway gets an error tool_result. `record_decision_outcome` records how a past decision turned out — the weekly review lists decisions older than 30 days with no outcome as `[decision N]` — writing `decisions.outcome` (`episodic.update_decision`) and auditing the rationale; it has `create_goal`'s gate (the principal on a verified surface only; everyone else gets an audited refusal) and is in `UNATTENDED_WITHHELD_TOOLS` too. A missing or unknown id returns the decisions still waiting on an outcome, so the model can retry with the right one. Its schema is static; the solo persona has one line on it, and team mode learns it from the tool description, so the team persona is byte-identical. 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. `assign_open_loop` opens one on request (\"ask Ben to send me the Q3 numbers by Friday\") for the principal or a rostered teammate on a verified surface — never an email, a turn private to the principal or an unattended run, which are also withheld the tool — and only when `task` appears verbatim in what the speaker typed this turn, at most 5 per turn; that turn's extraction pass then opens no second loop for the same owner. The owner is told once on their own channel when someone else assigns it, and the result's `notified` says how that went, so the Executive reports it rather than messaging them as well. The roster write tools (`upsert_person`, `archive_person`, `set_department_head`) are the principal's alone, and only on a surface that verified the speaker — the web chat, the principal's own Slack or Discord, or a private Telegram chat when `TELEGRAM_WEBHOOK_SECRET` is set to a value Telegram can send (Telegram identifies the chat rather than the sender, and without that secret its webhook accepts anyone's update). A teammate, an email (even from the principal's address), Google Chat, the CLI, the MCP server and unattended runs get `status: refused` (audited, and no action chip), because a team member's People row is also the web sign-in and outbound-email allow-list. `upsert_person` takes `kind` (`team` / `contact`; a new person defaults to `contact` in solo mode, an update keeps the current kind) and `email_aliases` (other addresses the person writes from — the full list, replacing the current one; they match mail and may be emailed but never sign in, and one already on someone else is refused), and after every write any pending roster request whose sender now matches someone is closed and its held messages replayed. `resolve_roster_request` answers a **roster request** — someone not on the People list who wrote in and is waiting (see Org): `approve` (a new person; `kind` defaults to team for a company-domain sender, else contact, when the principal did not say), `link` (someone already listed, by `person_id`; `replace_channel_id` only when the principal said so) or `decline`. It has the roster tools' gate (the principal on a verified surface; audited refusal otherwise), is in `UNATTENDED_WITHHELD_TOOLS`, and answers only an id in `Session.trusted_roster_request_ids` — the ids the server printed that turn in a `<roster_requests>` block (`briefing.context.format_roster_requests_for_prompt`, up to 10 pending requests), which `render_and_trust` appends to the `<briefing>` digest on the principal's own verified turn only and records on the session in the same step, so an id the model invents or reads out of a message adds nobody. Each line is server-derived — id, channel, address or account id, the sender's name sanitised and marked unverified, a company-domain hint, the message count — and never what they wrote. The block rides in the **user turn**, like the digest, so the cached system blocks are unchanged; the tool definition is static, and the new tool only extends the sorted tool list. The web chat route resets the trusted set every turn, and a resolved id is removed from it. and `list_people` returns both kinds with `kind` — contacts only on the principal's own verified turn (they are private to the principal; anyone else gets the team as if no contact existed) — while `lookup_person` searches the team only. `ask_about_person` reads a person's peer memory fully only on their own verified turn; anyone else's answers only to a verified principal or teammate, and only when that person turned on \"Share my work style with the team\", framed to how they work and never their view of a colleague, and otherwise returns the same \"hasn't chosen to share\" result whether or not anything is known. A teammate's own mail with the Executive is theirs the same way: every mailbox call the model makes through the MCP gateway (Gmail or Outlook, by `call_tool`, from a script, or a workflow step run from chat) passes through `orchestrator.teammate_mail`. A search excludes every other teammate's address server-side and is filtered again entry by entry; any other call that names a message or thread (read, attachment, reply, forward, label) must use an id a filtered search returned to the same reader in this conversation (`Session.mail_ids_seen`) or the inbound email the turn answers; reads are filtered message by message, so a message naming another teammate is left out unless the reader is in its From / To / Cc; a reply that would quote such a thread, or an Outlook forward, reply or attachment read of such a message, is refused; and a conversation in which a teammate other than the principal was shown their own mail becomes theirs alone, as Act as me's do. Outside mail and the reader's own are untouched; an email turn reads as its sender only when Gmail authenticated it, and any other unverified reader sees no teammate's mail, a background run the model drives reads as the principal and a workflow step outside any session as nobody, an Outlook inbox rule that forwards or names another teammate is refused, and the poller and the brief, which read the mailbox themselves, are unaffected. Their own chats are theirs too: every audit row of a teammate's verified turn is theirs (`people_tools.teammate_turn_owner`, see Audit; the principal sees the actions, never the words), and a teammate's web chat or DM opens for them alone (`chat._session_access`), the principal included. The same verified-principal rule, as `people_tools.contacts_reachable_now()`, decides whether a turn may reach a **contact** at all: `message_person`, the raw DM tools, `create_calendar_event` / `create_instant_meeting` attendees and the MCP gateway's Gmail / Calendar / Drive / OneDrive gates treat a contact exactly like an unknown person on every other turn, so no refusal reveals that one exists. **The untrusted-content policy** (`orchestrator.content_trust`) is one rule for text the principal did not write — inbound email, chat, attached files, watched pages — answering three questions for every surface. *Who is speaking*: the principal only when the surface proved it (`principal_speaking`: the web chat as the principal — never a signed-in email on nobody's People entry —, the CLI, their own Slack/Discord or a secret-verified Telegram chat, or their own address with Gmail's `dmarc=pass`); never a teammate, a stranger, Google Chat, the MCP server or an unattended run. *What may become memory*: episodic extraction runs only then, and only on the words outside `<untrusted_content>` blocks; peer memory and open loops are recorded under the speaker's own name, never as the principal's. *What may trigger tools*: every write on the principal's authority already refuses others in its handler; the tools with no such check that change the install for every later turn — `content_trust.PRINCIPAL_ONLY_TOOLS`: `load_mcp_server`, `list_saved_tools`, `run_python_job` and `run_script` — are not offered unless the principal is speaking on an interactive surface (not email, even authenticated), and a call the model emits anyway gets an error tool_result and a `refused: not_principal` audit row. So an inbound email, a teammate's turn, Google Chat and the scheduler's proactive trigger each get a stable tool list of their own without it. A send or edit on a team member's turn also meets their department's authority first (`orchestrator.department_gate`, see Org), and so does one on a turn whose speaker is on no People entry: a signed-in web caller or a chat-channel sender, which in practice is Google Chat, since Slack, Telegram and Discord turn unmatched senders away. Google Chat names a matched sender to the gate alone (`gate_sender_person_id`), so the principal there is not held. Email turns are left to the mailbox's own gates. *How it is labelled*: outside text goes into the user turn inside `<untrusted_content source=… author=… author_verified=…>` with a fixed notice that it carries no authority; compatibility forms are folded (NFKC), control characters go, and the tag's name is renamed wherever the text carries it — any case, spacing or entity-escaped form — so the text cannot end its block and speak outside it.\n\nA turn about the principal's private mail (`Session.private_to_principal`) reaches the principal only. It is neither offered nor allowed to run `schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS` — everything that reaches someone else, publishes where the team reads, or starts work outside the turn: the broadcasts, meeting bookings and cancellations, `run_workflow` and research, follow-ups and workflow nudges, watches, artifacts, goal updates, saved workflows, skill drafts, and `load_mcp_server` (it connects to any URL, which can carry the turn's content). Through `search_tools` and `call_tool` it reaches only `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads (mail, calendar, and Drive, Docs and Sheets search and file reads, with their Microsoft 365 twins; OneDrive's `download-bytes` only for a file's content) and the Gmail send and draft the gateway narrows to the principal. A search shows it nothing else, and a call to anything else (Google Chat, a Docs or Drive write, `manage_event`, another server) is refused (`schedule_tools.private_turn_withholds`). A call the model emits anyway, MCP tools included, gets an error tool_result and writes an audit row, and every audit row the turn writes is the principal's alone. On every turn the Executive knows what is connected without searching: block 0's *Connected Systems* section names the connected Google services, other MCP servers, the messaging channels, Notion sync, Confluence sync (when on) and Act as me, and pins the Google tool names it calls directly with `call_tool`. Both the service list and the pinned names are narrowed to what workspace-mcp actually loaded (`WORKSPACE_MCP_TOOLS`, `WORKSPACE_MCP_TOOL_TIER`), so a service left out is not named and its tools are not pinned — being told a tool is already available when it is not in the index costs a failed call the model cannot explain to itself. `search_tools` is for anything not listed. When work repeats over many items, the Executive can also call `run_script` (`workflows/step_script.py`, offered when the gateway runs, unless `CHAT_SCRIPTS=false`, and only on the principal's own turns — `PRINCIPAL_ONLY_TOOLS`, withheld on an unattended pass too, because it spends the turn's whole call budget on code the model just wrote): one short Python script, run in a sandboxed Monty worker with no files, network or environment, whose only reach is the gateway tools `call_tool` could reach (those `search_tools` has returned; the gateway keeps that set for its own process-wide session, not per conversation). Each call it makes is a `call_tool` in every way that matters — the gateway's discovery, deny-list and recipient gates, Take the lead's gate on an unattended run (or the department gate on a team member's turn, see Org), and the same action chip and `tool_invocation` row (marked `via: run_script`, `ok: false` when it raised), as each call happens; the script itself gets a `kind: script` row with its source and result. Its wall clock is half the turn's deadline, so a long script ends with the list of calls it made rather than being cut off with the turn, and a stopped turn closes it and its worker. A turn private to the principal is not offered it, and the Act as me lockdown withholds it whole. Besides gateway tools, a chat script may call a fixed list of the Executive's own tools (`step_script.CHAT_OWN_TOOLS`: reads, alerts, open loops, goals, the watch list, follow-ups, `message_person`, `upsert_person` — nothing that broadcasts, books calendars, edits memory or skills, or starts workflows or research), each only when the turn is offered it and through the turn's own handler (Take the lead's gate included), with the same chip and a `kind: skill`, `via: run_script` audit row. A direct call needs a `tool_use` each, so a turn's scripts share a budget instead: `CHAT_SCRIPT_MAX_CALLS` (default 200) calls in all, and per-turn caps on own tools that could otherwise act in bulk (`CHAT_OWN_TOOL_CAPS`: `message_person` 10 — messaging the whole roster would be a broadcast — `upsert_person` 25, `create_alert` 50); a refused call tells the model to say what is left. A call stopped mid-flight by the script's clock or the turn still gets a `cancelled` audit row, since it may have run. Because every round re-reads the conversation, the loop also nudges at the moment of choice: after a round whose results include a list of five or more items (`step_script.lists_many`), with `run_script` on offer and not used that round, it adds the constant `FANOUT_HINT` as a text block in that round's user message (never a cached block), once a turn, pointing the per-item work at one built tool. For library work on files (PDFs, spreadsheets, charts, images) the chat also has `run_python_job` (see Workflows → Python jobs): Python with a fixed library set in a Deno-isolated WebAssembly sandbox, fed Knowledge files by name, the message's own attachments as sent, or text it already holds, and able to keep a job that worked as a Custom tool, with result files linked for the principal to download; it is offered only on the principal's own turns and only where the sandbox is installed (not offered otherwise, so the tool prefix stays fixed per process). Agent Activity shows each run as one \"Built tool\" card (debug event `script_run`: ok, the calls it made, how many, how long, and the kept or reused tool's name). The persona's tool-building section is present only when chat scripts can actually run (the setting and Monty installed). `TOOL_BUILDING_ADDENDUM` in the cached persona tells the Executive when to build a tool — a job that looks something up and then checks or acts on each result, paged results, more than about ten items, or an answer that needs three or more reads (find, open, read; the tool returns only what answers the question, not whole documents, and only what is about to be edited or quoted at length is read in full), while a handful of items already named go as direct calls in one turn — and never to say it has none, and to talk about it as building a tool or doing it in one go. On the principal's own verified, interactive turns, a script that works can be saved as a named tool (`save_as`; elsewhere the script runs but is not saved) and run again with `run_script(tool=…, inputs=…)`; `list_saved_tools` (a constant definition, in `PRINCIPAL_ONLY_TOOLS` with `load_mcp_server`, so offered only while the principal is speaking on a verified, interactive surface; `run_script(tool=…)` is refused on any other turn) lists them, and each call a saved tool makes is a gateway call like any other (see Workflows → Saved tools). The tool's definition is a constant, so the cached tool prefix does not move. 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 (3 built-in and 2 company chunks by default, see the RAG section) before the specialist sees the question. The fan-out is failure-isolated per call: a specialist that raises or returns no text becomes an `UNAVAILABLE` tool_result (`router.specialist_unavailable_result`) instead of failing the whole turn, and its area — \"finance\", \"legal\", never the specialist's name — is reported to the user under the web reply, or by the Executive in its reply on other channels, unless another call to it answered that turn. A failed specialist does not count as consulted, so it takes no committee seat. Cancellation (Stop) still propagates. The Executive then synthesizes the returned analyses into one reply.\n\n`remember_fact`, `forget_fact` and `update_company_profile` (`orchestrator/fact_tools.py`) make a correction stick: the first two keep or retire a standing fact in `memory.facts`, and the third changes one field of the company profile. They share `record_decision_outcome`'s gate (the principal on a verified surface, an audited refusal for everyone else) and are in `UNATTENDED_WITHHELD_TOOLS`. `remember_fact` alone also admits a rostered teammate on a verified surface (web signed in, their own Slack or Discord): the fact is stored attributed (`recorded_by_role=\"teammate\"`, rendered `(per <name>)`), and is held as a `proposed` row (`awaiting_approval`) until the principal approves it, unless the principal marked that teammate trusted (\"needs my approval\" off; on by default) — and even then when it would replace the principal's fact. All three are also in `PRIVATE_TURN_WITHHELD_TOOLS`, since what they write or retire is read on everyone's turns. On the principal's own authenticated email (primary address, with Gmail's own `Authentication-Results` reporting `dmarc=pass`, not forwarded) the three tools check the request as usual, then hold it as `awaiting_confirmation`. It applies only when the principal replies to a one-time token emailed to their own address (`integrations.fact_confirmation`); the split into a check step and an `apply_*` step lets chat and the confirmed reply share one apply path. Each write also needs a `source_quote` found in the speaker's own words this turn. The active facts reach every specialist as a `<standing_facts>` user-turn tag: `route_to_specialist` reads them (None → the store, \"\" → none) for chat consults and workflow steps alike, and `BaseAgent.analyze` places the tag next to `<past_decisions>`, never in the cached specialist system prompt.\n\nThe ten 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| `sales` | `SalesAgent` | sales |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5-5`; the deep-reasoning tier (CSO, CFO, GC, Board) runs on `DEEP_REASONING_MODEL`, `claude-sonnet-5-5` by default, with adaptive thinking; routing/fast classification uses `claude-haiku-5-5`. Requests are fitted to the model's generation on the way out (`feature_gate.fit_claude_generation`): 5-generation Claude models never receive `temperature` / `top_p` / `top_k`, and Haiku 5.5, which thinks unless told otherwise, gets thinking turned off when the caller asked for none. 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. A PDF `document` block is translated too: it becomes an OpenAI `file` part, and OpenRouter requests carrying one add the `file-parser` plugin (`native` for models whose catalog entry lists `file` input, else `PDF_OPENROUTER_ENGINE`, default `mistral-ocr`). `FeatureSpec.supports_pdf_input` gates it per model — off for a local server unless `LOCAL_PDF_INPUT` — and a gated-off PDF becomes a text note rather than vanishing. The Council picks a model in two steps: a **Provider** dropdown (Anthropic, OpenAI, Google, Meta, DeepSeek, xAI, Local, …), then a **Model** dropdown limited to that provider, with readable names (\"Claude Opus 5.5\") and the raw id and serving route shown underneath. The Anthropic group combines the direct Claude models (`claude-fable-5-1`, `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5-5`, `claude-sonnet-5`, `claude-haiku-5-5`, `claude-haiku-4-5`) with any Claude generation that exists only on OpenRouter, and never lists a model twice. With `OPENROUTER_ENABLED`, the 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. Every Council agent also takes **additional instructions** (`agent_overrides.instructions`): text appended after its prompt by `agents.overrides.append_instructions` inside an `<additional_instructions>` block. `BaseAgent.base_system_prompt()` is the built-in prompt or its full replacement (what the Council's editor shows); `effective_system_prompt()` is that plus the instructions (what every call sends), and the Executive gets the same text through `build_system_blocks(persona_instructions=…)`. Unlike a replaced prompt, instructions leave the agent on its built-in prompt, so prompt improvements keep reaching it. A **Quality** choice above the agents (`agents.presets`) sets every agent's model and deep reasoning at once: **Fast** puts every agent on a small model (`claude-haiku-5-5`, else `claude-haiku-4-5`) with deep reasoning off, **Balanced** returns each agent to its built-in defaults, and **Thorough** puts the Executive and the domain specialists on the largest allowed model (`claude-opus-5-5`, else `claude-opus-5`) with deep reasoning on where the model supports it, leaving triage and the helpers below on their defaults. Presets change quality only; they never cap spend. Each preset resolves against the install's model allowlist at request time and is offered only when one of its models is allowed. Applying one writes ordinary per-agent overrides (model and deep reasoning only), so history, rollback and later per-agent edits keep working; an agent changed on its own afterwards shows as **Custom**. Each Council agent has a **visibility**: `core` for the Executive and the domain specialists (`BaseAgent.visibility = \"core\"`, which a new specialist must declare) and `internal` (the default) for triage and the helper agents below. Thorough moves only core agents. The Council opens in a **simple view**: the Quality choice, the voice picker, and only the core agents, each with its additional instructions and a model badge. **Show all agents** lists the internal ones too, and **Advanced** opens the full page (the browser remembers the choice). Eight 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), `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments), `workflow_designer` (runs the conversational New workflow wizard on `/jobs/new`: searches the available tools, asks clarifying questions, then drafts a validated dynamic-workflow definition for the user to review), and `workflow_actor` (runs a workflow's `action` steps: a bounded tool-use loop limited to the tools the user approved for that step). `fixture_generator`, `engagement_intake` and `onboarding_interviewer` 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. When the workspace is in solo mode, `onboarding_interviewer`'s first user turn is prefixed with a short hint (`interview.solo_hint(role_kind)`, one static constant per role kind from the onboarding role step): the draft names only the principal, as principal, and no departments; an owner is asked about the offer, customers, pricing, cash and runway, an in-house executive about their organisation (drafted as the company — their employer), function, remit, manager, team size as context and what they are measured on, an independent about their practice, clients and pricing, and with no role given the role-neutral `SOLO_HINT` asks which they are. The hint rides in the user turn and the tool array is unchanged, so the cached system prompt and tool prefix are the same in both modes.\n\n**Voice.** The Executive answers in one voice persona, substituted into block 0 at `{VOICE_PERSONA}` (`personas/loader.get_active_body`) from the Executive override's `voice_persona_slug`. Three general voices ship in `personas/builtin/`: **Direct** (`default`, the slug used when none is set: answer first, brief and decisive), **Supportive** (a warm coach who explains the why and checks how the plan sits) and **Analytical** (numbers first, options and trade-offs, then one recommendation). They are offered by a shared picker in setup (`/onboard`, after the workspace choice) and in Settings → Executive, which saves through `PATCH /agents/executive`; a built-in voice's frontmatter carries the picker's one-line `description` and `sample` reply. The named-executive voices are marked `legacy: true`: the picker hides them, but they still load, so an install that picked one keeps it, and the Agent Council lists them under \"Legacy voices\". Voice files hold disposition only; the response-length ladder lives in `prompts/executive_persona.py`, and a test keeps numeric length rules out of every voice file. An eval scenario may set `voice_persona` to answer in a voice; it rides on `Session.voice_persona_slug`, which wins over the override for that session only.\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\n**Solo mode.** When the workspace (or the turn's session) is solo — one person using Open Executive for themselves — the Executive works for that one person, the principal, whatever their role: they may run their own business, lead a function inside a larger organisation, or work independently, and the persona reads which from the context instead of assuming it — the role lines under \"Your Principal\" in the org block, when the principal gave their role (workspace settings: kind, title, reports to, remit, measured on). Its persona swaps the team sections (\"You Are a Member of This Executive Team\", \"Choosing Who to Tell\", \"Departments & Org Coordination\") for \"You Work for One Person\", \"The People in Their World\", \"Who Hears From You\" and \"Goals and Areas\". Solo means only the principal uses Open Executive — not that they have no people: their manager, direct reports, peers, clients, investors and board are contacts. The Executive helps the principal work with them (a 1:1 or review prep, an update or budget case for their manager or board, a negotiation) but does not coordinate them, contacts them only when the principal asks and only if they are a contact, and never offers to loop the principal in. Every specialist stays relevant — HR for the principal's own reports, board and investor communications for reporting upward. Goals are grouped by *area* (the tools' `department_slug` is the area's slug). The chat loop withholds `send_department_message`, `send_company_broadcast` and `set_department_head` from its tool list, and a call to one of them anyway gets a JSON error tool_result instead of running. The mode is resolved once per turn and pinned on the session, so the persona, the org block, the tools and every tool handler agree — a switch made mid-turn applies from the next turn. Team mode is unchanged.\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\n`recall_history` (Always in the loop, `orchestrator.history_tools`) reads the speaker's own notes, on the same terms as `ghostwrite_email` below: its own registry, offered only on a verified turn in a conversation private to them with their switch on; its `due` flag lists only dated notes, soonest first (see Memory). The ghostwriter below also gets the writer's notes from mail every recipient was on, as a consistency check (`<writer_noted>`).\n\nThe morning reflection, which has no question to look up and no specialist to consult, gets one more read-only tool of its own: `search_knowledge` (`orchestrator.knowledge_tools`), the same knowledge lookup a chat turn makes, for what the company's documents say about a customer, contract, price or policy before it acts.\n\nA fifth, `remind_me` (`orchestrator.reminder_tools`), sets a plain-text reminder sent to the speaker alone when it is due; it opens no mailbox, so it never locks a turn. A sixth, `propose_actions` (`orchestrator.action_card_tools`), does nothing itself: it leaves the speaker a card of up to five actions (a meeting, a message, a new contact) that happen only when they tap Approve, so it stays on after a turn read mail; it is where what an email itself asks for goes, since that is never done on the email's say-so. Four read-only tools beside it read the speaker's own mailbox on the same terms — `search_my_email`, `read_my_email`, `read_my_email_attachment`, `my_email_awaiting_reply` (`orchestrator.mail_read_tools`) — capped per turn, other people's messages and attached files returned as untrusted blocks (see Act as me). One tool writes under someone else's name, and it is fenced in code rather than the prompt. `ghostwrite_email` (**Act as me**, `orchestrator.delegation_tools`) writes an email as the person the Executive is speaking with and saves it as a draft in their own mailbox, Gmail or Outlook (`delegation.gmail.gmail_for` picks the client by the person's credential); chat never sends it (the person sends it themselves, or taps Send on its card). It lives in its own registry, never `_ALL_SKILL_TOOLS`, so reflection, research and workflow toolkits can never carry it. The chat loop adds it only on a turn `delegation.settings.pin_turn_delegation` offered it to — the principal, or a team member once the owner lets them, with it on, verified, in a conversation private to them (the web chat, a Slack or Discord DM, a verified private Telegram chat), on an attended turn — and builds that turn's handler map from both registries, so on any other turn a call to it is an unknown tool. From the round that calls it until the turn ends, the dispatch guard refuses only what opens an outside address, runs a script or workflow, or posts to everyone (`delegation.lockdown`), without changing the offered list; messages and invites to the roster, follow-ups, facts in the person's own words and a contact they name still run, each fenced in its own path. A later turn in the conversation stays private to its owner but holds nothing: the person asking again, having read the reply, is their own request. A contact add the lockdown refuses becomes an approval card in the chat instead (`propose_actions`). Recipients are chosen in code, never by the model (a draft's new email may go to any address, named back to check when it is neither on the roster nor typed), and the text comes from the **ghostwriter** (`delegation.ghostwriter`), a tool-less call with a constant prompt plus the person's \"How I write\" profile. The ghostwriter is deliberately not a Council agent: the Council's edit routes have no principal check. See **Act as Me (Delegation)**. A second tool joins the same way: `recall_history` (`orchestrator.history_tools`, Always in the loop) reads the speaker's own notes of what they said, by email or in chat. It has its own registry and per-turn handler map too, and the loop adds it only when `history_tools.recall_person` finds the speaker verified, in a conversation private to them, on an interactive turn that isn't private to the principal, with their notes switch on. It doesn't need Act as me. After every chat turn the Executive also hands the speaker's own words to `history_chat.schedule_chat_notes`, which takes notes in the background when their switch is on and the surface verified them (see **Memory**).\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`). `run_workflow` runs the weekly review, and in solo mode the morning brief, only for the principal on a verified surface (`Workflow.principal_only_modes`, `create_goal`'s rule); anyone else gets an audited refusal that does not name the rule. A run whose `result` event reports `private_to_principal` (the morning brief on the principal's own verified turn, when it read their private rows) still returns its artifact into that turn, but the stored run keeps `persistence.PRIVATE_RUN_ARTIFACT` instead of the text, since run history is readable by everyone signed in. This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nDeliverables are first-class too. `orchestrator.artifact_tools` gives the Executive three tools: `draft_artifact` publishes a memo, web page (`html`), Word document (`docx`), spreadsheet (`xlsx`, from structured `sheets`) or a `link` to something it created in one of the principal's connected apps through the generic MCP gateway (`search_tools` → `call_tool`, any server — no vendor is named), and returns the artifact's id and link; `list_artifacts` and `get_artifact` let it find and reread its own past work (drafts and workflow outputs alike, through the same `artifact_records` read model the API uses). Every artifact belongs to someone: a draft to the person whose turn published it (`artifact_records.current_viewer`; with nobody speaking, the scheduler or the CLI, the principal), and a run someone started by hand to them, while scheduled runs are the team's. The tools, the recall, `message_person`'s link and mail attachments only ever reach the speaker's own (a link is refused when the recipient couldn't open it), not even the principal sees a teammate's, and a speaker who isn't on the People list publishes nothing. A workflow's own session inside someone's turn (the research synthesis) is pinned to that turn's viewer (`Session.documents_viewer`). Revising is `draft_artifact(supersedes=<id>)`, which archives the earlier version. When the principal asks for a deliverable the tool is always used; the \"quiet is the right default\" bar applies only to unprompted drafts. The format enum is a hard-coded sorted tuple so the cached tool schema stays byte-stable. Delivery: `message_person(person_id, text, artifact_id?)` appends the artifact's title and a `UI_BASE_URL/artifacts/<id>` link (through the same outbound guard as any DM; the link needs Open Executive access), and a Gmail send/draft can attach the file itself by `artifact_id` — see Integrations.\n\n**Extensions** (`orchestrator.extensions`). An install can add chat tools and kinds of document without changing this code. `OPENEXECUTIVE_EXTENSIONS` names Python modules. The first turn, or the first Documents read, imports each one and calls its `register()`. A module that fails is logged and skipped. `register_tool` takes an `ExtraTool`: a definition, an async handler, an optional `tool_groups` group (new or existing) and an optional chip. It refuses a name the loop already knows (`executive.builtin_tool_names`). An extension tool is never in `_ALL_SKILL_TOOLS`, so reflection, research and the synthesis never see it. The chat loop adds it per turn, like the Act as me tools, but never on an unattended run, a turn private to the principal or to a speaker who isn't on the People list (mail from a stranger), and only where its own `offered(session)` says. That predicate depends only on the kind of turn, so each kind of turn keeps one cached tool list. Act as me's lockdown refuses it once the turn has read the owner's mail, because it is unclassified and the lockdown fails closed. Its chip goes through `action_chips.summarize_action`, which applies the same no-chip rules for an error or refusal and keeps a link to a path inside the app. `register_collection` adds a kind of document: a drafted artifact tagged `collection:<name>` carries that collection on its record. The Documents page gives each collection its own filter. The collection's `on_change` hears about archive, restore and delete before they happen; if it raises, the change does not happen. `draft_artifact(supersedes=…)` refuses a collection's document. The alert pipeline strips `collection:` tags, so only the extension's own code files a document in its collection. A module that fails partway through `register()` leaves nothing registered. A tool registered with `workflow=True` is also offered to workflow action steps as `oe__<name>` (see Workflows); `read_only=True` marks one that only reads. A step runs with nobody in the turn, so `offered` isn't asked: `extensions.in_workflow_step(name)` is True for that tool, during its call only, and the handler decides what an unattended call may do.\n\nDocuments come in the other way through `read_document` (`orchestrator.document_tools`): it reads a PDF, Word, Excel, CSV, Markdown or text file by `path` — one another tool saved, such as a Gmail attachment (`get_gmail_attachment_content`) or a Drive file (`get_drive_file_download_url`) — or a company document by `filename`, with an optional PDF `pages` range. A scanned PDF is converted (`knowledge.pdf_reader`: local OCR by default; with `PDF_PROVIDER_READING=true`, the deployment's own model through its provider's PDF support, falling back to local OCR) rather than returned empty. Reads are confined to the tool download folders — the same resolve-then-contain check as `oe__read_file` — plus the company docs folder, and it is withheld on turns private to the principal (`PRIVATE_TURN_WITHHELD_TOOLS`): those come from a contact's email, whose own attachments the poller has already read into the turn, and must not steer the Executive into company documents.\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.\n\n**Take the lead** (`orchestrator.take_the_lead`) is how the Executive acts on its own, behind one gate. It has two switches, both off until someone turns them on. **As the Executive** is the principal's alone (`PUT /take-the-lead`). With it on, the unattended passes (reflection, research, the scheduler's proactive trigger) keep the acting tools solo mode otherwise withholds from them: booking, starting workflows, and messaging teammates rather than only the principal. `schedule_tools.unattended_toolkit` and the chat loop's unattended path then wrap every acting tool (`ACTING_TOOLS`, plus any MCP tool whose name sends, creates, updates, deletes or shares) in `gated_handlers` / `gated_call_tool`. The principal-only tools (`UNATTENDED_WITHHELD_TOOLS`) stay withheld, and every guard inside a handler still applies, including department approval levels (a booking in a department on Proposes is still a proposal) and the contact-egress rule. New mail or chat (any turn with an `origin_channel`) wakes the existing reflection early (`take_the_lead.wake`): one run waiting at most, five minutes after the first message and no more than every 30 minutes, as a one-off `take_the_lead_wake` scheduled action. Pause holds it like any scheduled work. **As you** is the Handle it for me dial's top step (delegation section).\n\n**The gate** is plain code (`take_the_lead.check`). Six kinds of action wait for a yes first, each with an Ask first switch, all on to start. The switch is the decision ledger's own mode for the class `take_the_lead_action:<kind>` (`propose` asks first, the default; `auto_execute` doesn't). The kinds are money, contracts and legal, hiring and people decisions, deleting/cancelling/sharing, someone new (an address on neither the roster nor the contacts) and big sends (a broadcast or department message, or more than five people). On top of these, the company (set by the principal) and each person (for their own As you) add structured rules: a person or address, a domain, words, or an amount at or above a figure. Added rules always hold, and an error reading them holds the action. The one thing the gate lets straight through is a direct message (`message_person` or a Slack, Telegram or Discord DM) whose only recipient is the principal (`_only_to_principal`): they are who it would wait for, so a card would only ask them to approve a message to themselves. Anything that reaches or acts on anyone else is checked, and a roster that can't be read is not the principal. A held action becomes a `take_the_lead_action` decision instance with a companion `DECISION_ALERT_SOURCE` card on Today, routed to the first teammate holding one of its People approval ranges (`take_the_lead.approval_ranges`, plain code, closest fit first: money to `spend_lt_2k`, `spend_lt_10k` or `spend_gt_10k` by its largest amount, with a higher range able to approve a lower one and no amount read as large, or to `customer_credit` for credit and payment terms; vendor contracts to `vendor_onboarding` then `legal_sign`, other contracts to `legal_sign`; hiring to `hiring_signoff`; anything else about the board or investors to `board_comms`; in Personal as in team mode), or else the principal through the authority gate's fallback (`departments.authority._route_proposal`). Deletes and shares always go to the principal. Only the principal and that approver see or resolve it (`DecisionClassSpec.principal_and_approver`). Approving it claims the row and carries out the exact call once (`take_the_lead.carry_out`: the unwrapped handler, or the gateway's `call_tool`, on an unattended session, with contact egress only when the principal approves). Declining drops it. Everything done or held is a row in `take_the_lead_log`. What it did and what was approved show in Recent activity (`today._build_activity`, kind `took_the_lead`), named but never quoted, since that feed is the team's. The held card's own `decision_resolved` row is left out because its payload quotes the message. `GET /today/activity` also adds the caller's own Handle it sends (kind `sent_as_you`, actor `you`), which are never in the shared feed.\n\n**In training.** The As the Executive switch has three positions: Off, **In training** and On (`take_the_lead.training`). In training, an action the gate would let through still waits, as a `training` hold for the principal alone, unless the principal has allowed that action with that person or thing (`take_the_lead.allowance`: \"Message Priya Nair\" covers a message to her on any channel; \"Book meetings with Priya Nair and Sam Lee\" meetings with exactly them; a workflow by id; a connected tool by name and the file it names, never one that reaches people such as a mail send or a share). The card carries Approve, **Approve + allow**, **Edit** (the message, a meeting's title, times or description, a task and its due date: `take_the_lead.apply_edits`) and Decline. Allowing is the principal's alone and needs a request the API can tie to them, as turning it on does; the six kinds and the added rules hold whatever is allowed. An edit approved with \"Do it like this next time\" is kept as an example (only the edited text, the principal's own words), and `take_the_lead.learned_note` hands the examples and the fact it's in training to the reflection and research passes in their user turn. After `SUGGEST_AFTER` (3) unchanged approvals of the same action in 30 days, Settings suggests allowing it. What it's learned is one list keyed by feature (`take_the_lead_allowed.feature`), so other features that learn from approvals can join it; each keeps its own switch. Act as me is the second (`act_as_me`, per person, `delegation.training`), with a training switch per setting (Replies, Follow-ups, Suggested actions, Drafts): its rows carry the person's id and the setting in their key, are listed and removed by that person alone, count toward their own cap, and never reach `learned_note`.\n\n**AI disclosure.** Nothing the Executive sends to people outside the web chat goes without saying it is an AI: plain code adds the line in the MCP gateway (mail) and at each chat send (Slack, Telegram, Discord, Google Chat replies, its DMs and room posts), never the prompt, so the persona and the cached system blocks are unchanged and a reply the model writes can't drop it. Replies the inbox watcher writes as a person carry their own line by that person's switches. See Integrations → **AI disclosure** and Act as me → **AI line on replies**.\n","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 / sales<br/>board_comms / triage\"]\n Mode{{\"Team or solo<br/>(persona + tools per turn)\"}} --> Exec\n Exec -->|\"ghostwrite_email (Act as me)\"| Gw[\"ghostwriter<br/>(tool-less, not a Council agent)\"]\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 Mode compute\n class Cso compute\n class Cfo compute\n class Gc compute\n class More compute\n class Claude external\n class Gw compute",- "generated_at": "2026-10-14T05:40:00Z"+ "generated_at": "2026-10-14T06:41:10Z"}diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.jsonindex b99f9149..d5fd7561 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). With local login (`OE_LOCAL_LOGIN=1`, which only `make dev` sets, and only while neither Google nor SSO sign-in is set up) a second middleware answers 403 to any request whose raw `Host` is not `localhost`, `127.0.0.1` or `[::1]` (except a webhook that verifies its caller: Google Chat and Slack always, Telegram only with a `TELEGRAM_WEBHOOK_SECRET` Telegram can send), and to any write whose `Sec-Fetch-Site` is present and not `same-origin`/`none`. The UI signs that owner in with no password and this API usually has no secret, so without it a web page in the owner's browser could drive the API as the principal — by DNS-rebinding its own hostname to 127.0.0.1, or by posting a plain form from another site or localhost port. CORS is restricted to the UI origins in `BACKEND_ALLOWED_ORIGINS`, plus the `make dev` UI on `localhost:3000` only when `OE_PUBLIC_DEPLOYMENT` is unset, so a public instance never answers a localhost page with credentials. 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\n**Who is calling** is read in one place, `api/caller.py`, which answers with a `Caller` kind and email; a test fails on any other read of an `x-caller-*` header. By default (`open`) it is the `x-caller-email` the UI proxy stamps from the sign-in, trusted because whoever holds the shared secret is trusted as the proxy, and a request with none runs as the principal. **Signed callers** remove that trust. With `CALLER_ASSERTION_PUBLIC_KEYS` set, the proxy signs every request with an Ed25519 key only the UI holds, and a third middleware checks the `x-caller-assertion` header:\n\n- **What it covers.** It is good for one method, the exact path and query, at most 120 seconds, and one use. The API keeps used ids in memory.\n- **What it names.** A `user`, by email, or the `operator`: local login, which runs as the principal.\n- **No caller header at all** is a `service`, for scripts or MCP clients holding only the secret. It is never the principal, not even on an install with no owner yet, so it can't save a first setup.\n- **Anything else is a 401.** That includes an `x-caller-email` without an assertion (`caller_assertion_required`), and a bad, expired, reused or mismatched assertion (`caller_assertion_invalid`).\n\nPublic keys that can't be read stop the boot, rather than fall back to trusting the header. `scripts/make-caller-keys.py` makes the pair, and `scripts/mint-caller-assertion.py` signs one request for curl. The API holds only public keys. Setup's API-protection check warns while a shared secret is set without them.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat`, `POST /chat/stop`, `POST /chat/add`, `POST /chat/background` | SSE stream of a live Executive turn, with a `: keepalive` comment every `CHAT_STREAM_KEEPALIVE_S` while the turn is quiet. `POST /chat/background` starts a new chat that the server answers to the end with nobody connected (a phone approving a card, then closing the app): it answers `202` with the new `session_id` once the same caller, access and quota checks as `/chat` pass, the turn saves itself as a `/chat` turn does, and one caller may have three running at once (`429` beyond that). `POST /chat/add` hands the running turn a message the person typed while it works; the turn takes it at its next step and the stream names it in a `message_added` event, and a second `POST /chat` on the same conversation waits for the first to finish. 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. A `session_id` in the body must be a chat the caller may use (the same ownership rule as `sessions`). If it isn't, the turn runs in a fresh chat instead, so nothing is written into someone else's session and the reply looks the same as for an unknown id. An unknown namespaced id (`slack:…`, `telegram:…` and so on) is ignored and a fresh chat is started, because those ids belong to the channel adapters and claiming one first would make the caller its owner. 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. An optional `memory_text` (1–2000 chars) is what peer memory records as the caller's words instead of `message` — the briefing handoffs send it because their seed quotes the Executive's own card; `POST /chat/upload` derives it from the typed text and filenames. Since it never reaches the transcript, the `chat_turn` audit row keeps it beside `message`. After the reply — a stopped or timed-out one too, before the `stopped` / `error` / `done` frames — a turn that looked at anything sends one `sources` event, `{type, session_id, sources: [{kind, title, url}], unavailable: [area]}`: `kind` is `company`, `knowledge`, `notion`, `research`, `document` or `web`, `url` is only ever an http(s) link or, for an earlier document, `/artifacts/<id>`, at most 12 sources (6 from the web, pages the reply cites first), and `unavailable` names parts of the analysis (\"finance\") whose specialist failed or said nothing every time it was asked. It is persisted with the reply as `chat_messages.sources`. A request that carries `x-caller-email` marks its turn signed in (`Session.web_caller_signed_in`), which Act as me needs on a deployment without local login. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller, and each chat carries `preview`: its last message as one plain line, Markdown marks stripped and cut at a word near 120 characters, with `You:` before the person's own words. With `?q=` it is a search: the caller's own chats whose title or message text contains the words (case-insensitive, `LIKE` with wildcards escaped), each with `match_count` (messages that contain them; 0 for a title-only match) and `snippet` (the newest matching message, around the match, prefixed `You:` or `Executive:`). Scoped exactly like the list, so nobody else's conversation can match. The Chats page searches this way and opens a result with `?find=`, so the chat starts on that message and steps through the others. A chat-app conversation started with /new is left off the list until its first turn (`memory.conversations`). Every per-session route checks ownership, because session ids are guessable (`slack:dm:<user id>`, `telegram:<chat id>`): only the session's owner or the principal gets through, and a legacy row with no owner is the principal's alone. A teammate's own chat (a web chat, a DM, a private Telegram chat; not a channel or group conversation, `chat._shared_space`) is theirs alone, the principal included, as their mail with the Executive is. Anyone else gets the same 404 as for an unknown id, so the routes can't be used to find out which chats exist. The one other way in is having started the chat in this process (matched by Person id or verified email, so it survives the caller being added to the roster), which is how a caller the roster can't resolve keeps using their own chat. That record is in memory, so after a restart such an ownerless chat is refused for reads. The principal can continue someone else's ownerless chat without becoming its owner. Deleting a session also drops its in-memory copy, so a later turn naming that id starts fresh. The feedback route records 👍/👎 (`{\"feedback\": \"up\"|\"down\"|null}`) on one assistant reply; only the session's own caller or the principal may rate it. The rater is stored (`feedback_by_person_id`), and a 👎 on a reply to the rater's own message triggers a working-style pass for them (paced; see attunement). The chat stream's `done` event carries `message_id` for the persisted reply. The followup route returns `{\"suggestion\": string|null}` — one suggested next user message, written by the utility-fast model from the last few turns, that the chat composer shows as its greyed placeholder (Tab / → or the inline chip fills it in without sending). It is null unless the session ends on a persisted assistant reply, and null (uncached) when the model fails. Same ownership check as feedback; successful suggestions are cached in-process per (session, reply id). Messages from `GET /sessions/{id}/messages` carry each assistant reply's saved `sources` (the same shape as the chat stream's `sources` event, without `type`), so a reloaded chat shows them again. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/top-three`, `GET /today/weekly-review` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). `GET /today` carries the viewer's cached \"What's going on\" `narrative` with `narrative_generated_at` (when it was written) and `narrative_stale` (a fresher one is being written — the page re-polls; see Today). A proposal backed by a roster request carries `roster_request` (the new sender's server-derived details and held-message previews; the principal's only) and is answered through the `people` routes below. `brief-delivery` returns the latest morning brief or end-of-day digest that didn't reach the owner, as `{brief, at, problem, fix, readable}` in plain language (`readable` is false when it couldn't be written, so there is nothing to read), or null — null while briefs go out, once the cause is fixed, while the scheduler is off, and for anyone but the owner (`chat._caller_is_principal_or_unclaimed`); it carries no address or channel id. `top-three` and `weekly-review` feed the solo Briefing's own cards and answer only in solo mode and only to the principal (`workflows._caller_is_the_principal`: a principal match or no caller header, never an unclaimed roster); anyone else, and team mode, get null. `top-three` returns `{items: [{key, kind, text, why, slot}]}` — the morning brief's top three from the same code (`build_top_three(principal_due_soon())`), `slot` a free block like `10:00–11:00`, `\"\"` when none is left, null when no calendar was read — and is kept off `GET /today` because its calendar read may take up to 4 s. `weekly-review` returns the latest completed `weekly_review` run as `{run_id, completed_at, period, top_three, excerpt}` (next week's top three as plain text; `excerpt` when that list is empty), or null when none has completed. |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive`, `GET /people/requests`, `GET /people/requests/{id}`, `POST /people/requests/{id}/approve`, `POST /people/requests/{id}/decline`, `GET\\|POST /people/{id}/open-loops`, `POST /open-loops/{loop_id}/close`, `GET /people/{id}/outreach`, `GET\\|PUT\\|DELETE /people/{id}/attunement` | Roster CRUD and scope lookups. Every `Person` carries `kind` (`team` / `contact`). `GET /people` lists team members only unless `?include_contacts=true` (the People page asks for both; the department-head and workflow pickers keep the default); `POST` / `PATCH` accept `kind`, and a principal contact is a 422 either way. They also take `email_aliases` (other addresses the person writes from, at most 10; on `PATCH` the full list replaces the current one, omitted leaves it): an alias matches their mail and may be emailed but never signs in; a malformed one is a 422, and an alias — or a new primary `email` — that is already someone else's address or alias is a 409. Every `POST` / `PATCH` then closes any pending roster request whose sender now matches someone and replays its held messages. Adding, editing and archiving (`POST`, `PATCH`, `/archive`) are the principal's only, or anyone's while no one is principal yet so a first setup can add its owner (`chat._caller_is_principal_or_unclaimed`, the check behind `PUT /workspace`; a request with no `x-caller-email`, such as the CLI or local login, counts as the principal). Anyone else, a person editing their own row included, gets 403 before the person lookup, so it can't probe which ids exist. Contacts are private to the principal (`caller_is_principal`: the signed-in email is the principal's, or no `x-caller-email`; stricter than the owner rule above, so while no one is principal nobody is): for anyone else `include_contacts` is ignored, a contact's id is a 404 on `GET /people/{id}` and open-loops (exactly as for a missing id; `PATCH` and archive are already a 403 for them), and creating a contact or turning someone into one is a 403, even on a first setup with no principal yet. `GET /people/me` returns `{person_id, is_principal}` so the UI offers contacts to the principal only. `GET /people/by-scope/{token}` never returns a contact. 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`). `POST /people/{id}/open-loops` `{task, due_date?}` assigns that person a task (201 with the loop; `due_date` is a local date, due 17:00 in the user's timezone, clamped to 60 days, default 2 days): any active team member may assign anyone on the team, 403 for anyone else; 409 for an archived person, a contact (as seen by the principal), a person at the open-loop cap, a duplicate or open loops turned off; 422 for an empty task. Nobody is messaged at assignment — the owner is chased once it is due. `/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. `/attunement` reads, replaces (`rules`: up to 4 strings, or omitted to only set `locked`) or resets the person's working-style rules — same access rule, 404 for an archived person; `PUT` rejects a rule that is not purely about style with 422. Archiving a person also drops their working style and frees their aliases. The **roster-request** routes (declared before `/people/{person_id}`) are the principal's alone (`caller_is_principal`; anyone else gets 404, as for a missing id): `GET /people/requests?status=pending|approved|linked|declined|expired|superseded|all` lists up to 100 (`id`, `channel`, `channel_ref`, sanitised `display_name`, `profile_email`, `on_company_domain`, `suggested_kind`, `suggested_person_id` / `_name`, `status`, `resolved_person_id` / `_kind`, `message_count`, timestamps, `ack_sent`, and `previews` of the held messages while pending — shown to the principal, never to a model); `approve` takes either `link_person_id` (+ `replace_channel_id`) or `full_name` + `kind` (no default: 422 without both) + optional `role`; `decline` takes no body. An answered request is a 409, a chat id or address already on someone else is a 409; the held messages are replayed (or dropped) in the background. |\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. A `cadences` spec that does not parse is rejected with a 422 (empty means no cadence, i.e. the check-in is off); a changed `check_in` cancels the pending check-in and queues the next one on the new schedule. `GET` and `PATCH /departments/{slug}` return the department state plus `next_check_in_at` (ISO UTC of the pending check-in, `null` when it is off, the workspace is solo or none is queued); the list route does not carry it. A new `head_person_id` must be a team member: an unknown id and one of the principal's contacts get the same name-free 422 (`person_id N is not on the team.`), so the route — open to any signed-in user — never reveals that a contact exists; an unchanged head is not re-checked. `POST .../goals` requires only `key_result`: a missing or blank `period_value` is filled with the current period for `period_type` in the user's zone (the same label `create_goal` uses), and `target` defaults to empty. `PATCH .../goals/{id}` rejects a blank `key_result` or `period_value` with a 422; `target` may be cleared. |\n| `agents` | `GET /agents`, `GET /agents/models`, `GET /agents/models/options`, `GET /agents/presets`, `POST /agents/presets/{id}`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. `/agents/models` is the flat model allowlist the PATCH validator uses; `/agents/models/options` returns the same ids in the same order, each tagged with `provider`, `provider_label`, `route` (`direct` / `openrouter` / `local`) and a display `label`, for the Council's Provider → Model picker. `AgentDetail` carries `instructions` (additional instructions, appended after `prompt`, which stays the built-in prompt or its replacement); `PATCH` and `/test` accept `instructions` (max 4,000 chars, blank clears it). `GET /agents/presets` lists the Fast, Balanced and Thorough quality presets (each with `available` and the resolved `model` for this install) plus `active` (null when the council is Custom), `base` and `custom_agents`; `POST /agents/presets/{id}` applies one by writing per-agent model and deep-reasoning overrides and returns the same shape (404 unknown preset, 409 when the install allows none of its models). Each `AgentMeta` carries `visibility` (`core` or `internal`) so the Council's simple view can list core agents first. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/approve`, `GET /alerts/approvals/{id}`, `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/snooze`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `approve` (body `{edited_body?}`, 202) carries a proposal card out on the server and records who approved it and when (`alerts.approvals`, see Today): it queues the scheduled action a department-gated card held, or runs one Executive turn as the approver in a new chat (`session_id`). 409 for a card already approved or closed, a decision-backed card (approved at `/decisions`), a roster request or a drafted artifact; 403 unless the caller is the card's routed person or the principal (an unrouted card is the principal's); 429 when the caller already has three background turns running. `GET /alerts/approvals/{id}` reads one back (`running`, then `done` / `failed` with `outcome`) for its approver, the card's person or the principal (404 for anyone else). `snooze` (`until`, an ISO time up to 30 days ahead; `null` clears it, the Undo) hides an `unread` card until then by setting `snoozed_until` (409 on a closed card or a roster request); the TTL then counts from the snooze, so a card snoozed past its TTL still comes back. `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`, `GET /artifacts/{id}`, `GET /artifacts/{id}/download?as=`, `POST /artifacts/{id}/archive`, `POST /artifacts/{id}/restore`, `DELETE /artifacts/{id}` | Browsable deliverables in any format — Markdown, HTML, Word, Excel, or a link into a connected app — with `format`, `downloads`, `external_url`, `supersedes_id` and, for an extension's kind of document, `collection` / `collection_label` on every summary (`orchestrator.extensions`; archive, restore and delete tell the collection first and answer 502 if it refuses). `download` renders the file (Word/Excel built at request time from the stored text; any Markdown artifact, workflow output included, can export `?as=docx`) and is always an attachment with `nosniff` and a sandbox CSP. Every route answers for the signed-in caller (`artifact_records.Viewer`): a drafted artifact is its owner's alone (`alerts.owner_person_id`, the person whose conversation published it; none = the principal's), a workflow output follows its run (`persistence.run_visible_to`), and anything the caller may not see is a 404 like a missing id, the principal included. `POST /alerts/{id}/ack` and `/reopen` answer 404 for someone else's drafted artifact the same way. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET`/`PUT /decisions/classes/meeting_scheduling`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). What approve/reject/cancel do is per class (`DECISION_CLASSES`, one `DecisionClassSpec` each; meeting booking books on approve and deletes on cancel; `delegation_reply`, an inbox reply card, is its approver's alone (`approver_only`) — hidden from everyone else, the principal included when it is a team member's — sends its Gmail draft on approve and, after a reject, deletes the draft unless it was edited; `department_action`, a team member's chat send or edit their department held (see Org), is the principal's and its approver's alone (`principal_and_approver`), makes that exact call on approve and audits `department_action_done` / `_failed` / `_declined`), and an instance of a class with no spec gets 409 instead of being carried out as another. Only the principal, or the person the decision went to for approval (`approver_person_id`), may approve, reject or cancel it. Anyone else gets 403, and a decision nobody was asked about, or one private to the principal, is the principal's alone. The resolver is recorded as `resolver_person_id`, and a reject that loses the race to another answer is a 409. `GET /audit/reliability` is the principal's alone (403 otherwise), because it counts private decisions too. A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. An approval whose caller resolves to the principal runs the booking inside `grant_contact_egress()`, so a meeting the principal proposed with a contact can be created. Such a booking's payload is marked `private`: it is proposed to the principal, left out of anyone else's `GET /decisions`, and a 404 for them on `GET /decisions/{id}` and every action route. Reviewed in the briefing — there is no separate proposals page. The class routes read and set how meetings are handled: both return `{decision_class: \"meeting_scheduling\", mode: \"propose\" \\| \"auto_execute\"}` (default `propose`); the `PUT` body is `{mode}`, principal-only (403 otherwise, open before a principal exists — but then only `propose` can be set: `auto_execute` is a 409 until a non-archived principal is on the roster), 422 on any other mode, and a change writes a `decision_class_mode_changed` audit row. In solo mode the class mode decides a booking, and `auto_execute` applies only to a turn the principal started on a verified surface — any other turn gets a proposal. |\n| `delegation` | `GET`/`PUT /delegation`, `GET`/`PUT`/`DELETE /delegation/voice`, `POST /delegation/voice/learn`, `POST /delegation/voice/describe`, `POST /delegation/voice/signature`, `PUT /delegation/inbox`, `POST /delegation/inbox/check`, `GET /delegation/replies`, `PUT /delegation/replies/{id}/text`, `GET /delegation/actions`, `PUT /delegation/handle-it`, `PUT /delegation/disclosure`, `PUT /delegation/training`, `DELETE /delegation/learned/{id}`, `GET /delegation/handled`, `PUT /delegation/team` | Act as me — the **caller's own** delegation only; nobody sets it for anyone else. It answers the principal, and a team member once the owner lets them; anyone else gets 403 `not_available_yet`. `GET /delegation` returns `{enabled, gmail: {status, message, email, connect_command, outlook_connect_command, provider}, inbox: {enabled, status, message, watch_since, last_poll_at, checking}, handle_it: {enabled, mode, available, sent_today, lead, lead_available}, training: {replies, follow_ups, actions, drafts, learned}, disclosure: {enabled, handle_it, approved_sends, line}, team}`, where `team` is the owner's switch for the principal while `DELEGATION_TEAM_MEMBERS` allows it — `{enabled, members: [{person_id, name, enabled, inbox, drafts_30d, sent_30d}]}`, counts only — and `null` otherwise. `PUT /delegation/handle-it` takes `{enabled?, mode?}` (`mode` is `careful`, `balanced` or `bold`; anything else is a 422 `bad_mode`) from a caller the API knows is that person — 403 `not_yours`, 409 `caller_signing_required` with only the shared secret — and turning it on needs Act as me and Draft replies to my inbox on (409 `act_as_me_off` / `inbox_off`); `GET /delegation/handled` returns `{replies: [{decision_id, sent_at, to_name, to_email, subject, body, open_questions, gmail_link, source}]}`, the caller's replies and follow-ups (`source` `follow_up`) sent on its own in the last 7 days; a card on `GET /delegation/replies` carries `source` the same way, `can_allow` while Replies (Follow-ups, on a follow-up) is in training, and `learns_style` while Drafts is. `PUT /delegation/disclosure` takes `{handle_it?, approved_sends?}` (any other field is a 422), the caller's own switches for the AI line on replies sent as them (`disclosure.enabled` is the install's `AI_DISCLOSURE`); turning one on needs no signed sign-in, turning one off does (409 `caller_signing_required`), and a change is audited as `delegation_disclosure_changed`. `PUT /delegation/training` takes `{replies?, follow_ups?, actions?, drafts?}` (any other field is a 422) and returns the `GET /delegation` shape; putting Replies or Follow-ups in, or Suggested actions out, needs no signed sign-in, anything else does (409 `caller_signing_required`), and putting Replies or Follow-ups in turns Take the lead as you off (`PUT /delegation/take-the-lead` on answers 409 `in_training` while they are). `training.learned` is `[{id, label, setting, example, uses, created_at}]`, what the caller allowed or kept in training (`setting` `replies`, `follow_ups`, `actions` or `drafts`; the kept example, or \"\"); `DELETE /delegation/learned/{id}` removes one of the caller's own (404 for anyone else's). `PUT /delegation/team` takes `{enabled}` from the principal alone (403 `principal_only`; 409 `not_available` when the install doesn't allow it). The Gmail `status` is `connected`, `not_configured`, `needs_reconnect`, `mismatch`, `no_email`, `shared_mailbox` or `error`, checked live with Google on each call. `PUT` takes `{enabled}` (any other field is a 422); turning it on needs the caller's own Gmail connected, otherwise a 409 whose code says why (`gmail_not_connected`, `gmail_needs_reconnect`, `gmail_mismatch`, `no_email`, `shared_mailbox`, `gmail_error`). The voice routes show, learn (from the caller's sent mail, one pass at a time — a 409 `in_progress`, `locked`, `too_soon`, `not_enough_mail`, `no_profile` or `changed` when it was locked or edited while learning, or a Gmail code), write it from the caller's own description (`POST /delegation/voice/describe` with `{description}`: one model call applies their words to the profile they have and returns it with a short `sample_reply`, saving nothing, so they review it and save it with `PUT`; a 409 `empty`, `too_long`, `in_progress`, `too_many` past 10 an hour or `no_profile`; no mailbox needed), edit and lock, and reset \"How I write\": a typed field that fails validation is a 422 `invalid_voice` listing each `rejected` field, and `clear_exemplars` / `clear_signature` drop those. `POST /delegation/voice/signature` reads the signature from the caller's Gmail settings again and changes nothing else (a locked profile stays locked), with the same Gmail codes as learning: a 409 when their mailbox isn't connected, it refuses the sign-in or the check itself fails (`gmail_error`), and a 502 `gmail_error` when reading the signature fails. On an Outlook mailbox it is a 409 `signature_unavailable`, since Outlook gives apps no signature to read, and the stored one is left alone. A caller `can_delegate` refuses — anyone but the principal, for now — gets 403 `not_available_yet`, which hides the Settings card. A request with no `x-caller-email` is a 403 `sign_in_required` unless the API runs under local login — a header-less call is not a sign-in (the caller is read through `api/caller.py`, as on every principal-only route). `PUT /delegation/inbox` takes `{enabled}` and turns **Draft replies to my inbox** on or off, returning the same shape as `GET /delegation`: on needs Act as me on (409 `act_as_me_off`) and the mailbox connected (the Gmail codes above, which keep their names for an Outlook mailbox too), and turning Act as me off turns it off too. `POST /delegation/inbox/check` starts a scan now in the background and answers 202 with the `inbox` state (409 `inbox_off` or `in_progress`). `GET /delegation/replies` returns `{cards: [...]}`, the caller's open reply cards from the database alone (no Gmail call): the decision id, the sender's name, address, relation and whether it was verified, the subject, when it arrived, what they wrote, the draft's recipients, subject and body, `open_questions`, `flags` and a Gmail link built from a fixed prefix. **Send** is `POST /decisions/{id}/approve`: it sends the card's draft exactly as it is in Gmail, after checking again that the caller is its owner — which on a server needs signed callers (409 `caller_signing_required` otherwise) — that both switches are on (`inbox_off`), no client slot is active (`client_slot`), the Gmail is connected (the Gmail codes), the draft is still there and unanswered (`draft_gone`, `you_replied`) and its recipients are allowed (`no_recipients`, `too_many_recipients`, `executive_recipient`, `not_from_you`). Recipients that changed, or a newer message in the thread, answer 409 `{code: \"confirm\", message, reasons, recipients}`; approving again with `edits: {recipients: <the list shown>, thread_moved_on: true}` is the second yes. **Send + allow** adds `edits.allow: true`: 422 `cant_allow` unless Replies (Follow-ups, on a follow-up card) is in training, 409 `learned_full` when their list is full, both before anything is sent; `edits.example: true` keeps a draft edited in the mailbox as how they write to that person while Drafts is in training. A draft edited in Gmail between those checks and the send is not sent (`draft_changed`). A double tap sends once (`already_handled`); Gmail refusing answers 429 `rate_limited` or 502 `gmail_error` with nothing sent, and a send Gmail didn't confirm answers 502 `send_unconfirmed` and is settled by the next inbox scan. Dismiss is `POST /decisions/{id}/reject`. `GET /delegation/actions` returns `{cards: [...]}`, the caller's own approval cards (`delegation_actions`): the decision id, when it was made, a one-line `why`, and each action's `index`, `kind` (`invite`, `message`, `add_contact`), `summary` and `text` (a message as it will be sent, or a meeting's description). **Approve** is `POST /decisions/{id}/approve` with `edits: {only: [indexes]}` (and `allow: true` for Approve + allow while Suggested actions is in training: 422 `cant_allow` otherwise or when nothing on it can be allowed, 409 `learned_full`; a card carries `can_allow`); it needs the card's own person signed in (403 `not_yours`, 409 `caller_signing_required`), Act as me on (409 `act_as_me_off`) and a card under a week old (409 `expired`), runs once (409 `already_handled`), and returns the decision with `final_payload_json.results`: per action `done`, `waiting` (sent to whoever approves meetings), `failed` with why, or `skipped`. Every change writes a private audit row. |\n| `history` | `GET /memories/history` (`?q=`), `PUT /memories/history/settings`, `PATCH`/`DELETE /memories/history/{id}`, `POST /memories/history/{id}/forget-conversation` | Always in the loop: the **caller's own** notes and switches only, resolved as for Act as me (a signed-in person on the roster, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{notes, reply_notes, retention_days, effective_retention_days, company_retention_days, retention_choices, can_keep_notes, can_note_replies, can_set_company_retention, share_work_style, can_share_work_style}` (`can_keep_notes`: a team member on the People list may turn notes on; `can_note_replies`: they can use Act as me, so email replies are noted too; `share_work_style`: their own \"Share my work style with the team\" switch, `can_share_work_style`: a team member in a team workspace). `PUT` turns notes on only for someone who may keep them, and `share_work_style` on only for someone who may share it (403 `not_available` for either; turning either off always works), takes a person's retention only when shorter than the company's (422 `invalid_setting`), and the company retention only from the principal (403 `principal_only`). `PATCH` pins or corrects a note; `DELETE` forgets it; `forget-conversation` is \"Don't remember this\". A note that isn't the caller's is 404. Every change is audited privately to its person. |\n| `notifications` | `GET /notifications/settings`, `PUT /notifications/settings` | Settings → Notifications: the **caller's own** settings only, resolved as for the notes (a signed-in person on the People list, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{quiet_hours: {enabled, start, end, days}, delivery, urgent_through, timezone, effective_timezone, held_count, gets_briefs, updated_at}` — `days` is `every_day` or `weekdays`, `delivery` `instant` or `digest`, `timezone` the zone they chose (`\"\"` for the workspace's), `held_count` how many messages wait for their quiet hours or brief (counted, never listed), `gets_briefs` whether they are the principal. `PUT` takes `{quiet_hours, delivery, urgent_through, timezone}` and replaces them (extra fields, equal start and end, a bad time or an unknown zone → 422); switching `digest` → `instant` makes what waited for the brief go now. Audited as `notification_settings_changed`. See Org. |\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), plus `scripts`: how many `run_script` scripts ran (and worked, and in workflows), the tool calls they made, their time, and `turns_avoided` — an upper bound on the model turns those calls would otherwise have needed (each call past a script's first) — and `python_jobs`: how many Python jobs ran (and worked, ran a kept Custom tool, took a chat attachment), their time, CPU, largest peak memory and bytes in and out, and the tokens and charge of the turns that ran one. The Token usage page shows it as a Scripts section. Rows private to the principal (`private_to_principal`: a turn about their private mail, or a row naming one of their contacts on their own turn) are theirs alone: for any other caller, resolved as for `/alerts`, the usage totals leave them out. Once a principal is on the roster, anyone else reads only their own rows (a teammate's own turns, their Act as me work) in the list, by id and in a session, and the principal reads those as actions only — what was done, when and in whose conversation, with the text, details and `full` left out, and no text search over them; any other row's id is a 404, and a session shows only the rows the caller reads. |\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. Only `/health` is unauthenticated; `/health/honcho` sits behind the gate like everything else, because the exemption is an exact-path set. `/health` also carries `google_tools_missing`, the pinned Google tools startup priming could not find: `[]` once it has checked and they are all there, a list of names when a workspace-mcp rename or the configured services and tool tier left one out, and `null` for no answer — Google Workspace is not configured, or the probe has not finished or it failed. Only `[]` asserts they are present. It also carries `gateway`, the MCP gateway's state from its supervisor (`orchestrator.gateway_boot`): `state` is `off` (MCP not enabled), `no_servers` (enabled, the config names none), `starting` (an attempt is running), `up` or `down` (every attempt so far failed; `next_retry_at` is the next one), with `attempts`, `up_since` and `email_poller` (whether the poller that rides on the gateway runs); the failure's own text stays out, since the route is open to anyone, and goes to the log and the owner's notice on Home. A hosted instance whose gateway never came up used to answer `ok` here with no email going out or in. Only `[]` asserts the tools are present, so a probe that died cannot read as healthy; Setup status says which of the three `null` means. |\n| `version` | `GET /version` | The running version, the latest release on GitHub and `update_available`, for Settings → About. The GitHub answer is cached 6h, only a semver `tag_name` is used and the release link is built from it; `UPDATE_CHECK_ENABLED=false` skips the call and still returns the running version. No in-app updater: upgrading is host-side (`docs/deployment.md#upgrading`). |\n| `setup_status` | `GET /setup/status` | Settings → Setup status: one light per part of the install — AI model, company setup, owner, the Executive's address, API protection, Gmail, your own mailbox (Act as me), Slack, Discord, Telegram, Google Chat, the scheduler, the daily brief (when and where it goes) and Honcho — as `{checked_at, checks: [{id, label, state, summary, fix, link, last_activity}]}`, where `state` is `ok`, `warn`, `error` or `off` (optional and not set up), `fix` says what to do in plain language, `link` is an in-app page that helps (`/people`, `/onboard`) and `last_activity` is the channel's latest `integration_inbound` audit time. It tests live, with at most one free read-only call per service, each bounded to 5 s: Anthropic `models.list` (so an organisation key missing `ANTHROPIC_WORKSPACE_ID` shows up), Slack `auth.test`, Telegram `getMe` and `getWebhookInfo`, Discord `users/@me` only while the bot is still connecting, and — once the owner's own Gmail credential exists — Google's token refresh and Gmail `users/me/profile`. It also reads the listeners the lifespan leaves on `app.state` (Slack's socket, the Discord bot and its task, the MCP gateway), the scheduler heartbeat and the pause switch. When `google_workspace` is configured, the lifespan also starts `MCPGateway.prime_pinned_tools()` in the background (held on `app.state.mcp_prime_task`, cancelled at shutdown), so the pinned Google tools named in the prompt are callable without a search. With `DRIVE_SYNC_ENABLED` the lifespan also bootstraps the `drive_sync_scan` heartbeat beside Notion's (see Scheduler); the Drive folder sync has no HTTP route, only the `openexecutive sync-drive` / `purge-drive` CLI. With `CONFLUENCE_SYNC_ENABLED` it bootstraps the `confluence_sync_scan` heartbeat the same way; that sync is run by hand with `openexecutive sync-confluence` / `purge-confluence`. Sample values copied from `.env.example` are named as such without being sent anywhere. No token reaches a response or a log line: probes report a status code, a service's short error code or an exception's class name. Requests within 5 s of a run get that run's answer and concurrent requests share one run (kept per app on `app.state`), so the button can't become a stream of calls to those services. Gated like every other route; the UI adds a sign-in light of its own, from its own settings. |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}`, `GET /documents/sources`, `POST /documents/sources/{drive\\|onedrive\\|notion}/sync`, `GET /documents/{drive\\|onedrive\\|notion}`, `GET /documents/{drive\\|onedrive\\|notion}/{id}` | Upload, list, view extracted text, and delete indexed company docs. `GET /documents` rows carry `source: \"upload\"` and the `domain` the upload was indexed under. The connected-source routes back the knowledge page's single Company documents list: `/documents/sources` gives each source's `{id, label, enabled, syncing, last_run, last_error, interval_minutes, file_count}`; `/documents/drive`, `/documents/onedrive` and `/documents/notion` list synced files from the sync state (`{enabled, last_run, last_error, files: [{id, name, url, modified_at, synced_at, indexed}]}`; a Drive row also carries `unreadable_reason`, why a file with `indexed: false` has no text — e.g. a scan OCR could not read — or null); `/documents/{drive\\|onedrive\\|notion}/{id}` returns the stored text (a OneDrive id is `<drive id>:<item id>`) for an id on record (the path comes from the state, never the caller). They are read-only — a synced file is removed where it lives. `POST …/sync` starts one tick of the same sync the scheduler runs as a background task (202); 409 when the source is not connected or a tick is already running (every sync holds a per-process run lock, so a manual run never overlaps the heartbeat; the route also keeps its own started task per source and re-checks just before starting one, so two simultaneous requests start one tick, not two), 429 with `Retry-After` within 60 s of the last successful run or of the end of the last tick in this process, failed ones included, so a failing or slow source can't be re-run back-to-back. The page's text view never loads images from synced content (a remote image would be a read beacon for whoever edits the shared folder). 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 nine specialist domains (including `sales`) or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. A scanned PDF is converted (`knowledge.pdf_reader`) before it is indexed and in the text view, as are scanned PDFs in `POST /chat/upload` and the client / onboarding intake uploads. The upload is streamed to disk 1 MB at a time and refused with a 413 once it passes 50 MB, and the file is parsed in a short-lived child process (see the RAG section), so a large document does not stay in the API process's memory. A Word or Excel file that cannot be parsed, or whose parse runs out of time, is a 422 with a readable reason. When every parser is busy, the response is a 503 with `Retry-After`. |\n| `executive` | `GET /executive/status`, `POST /executive/pause`, `POST /executive/resume` | Operator pause switch for all autonomous work (scheduler, Gmail poller, workflow resumer); inbound chat and DMs stay live. Status returns `{paused, paused_at, paused_by, reason, held_actions, can_resume}` — `held_actions` counts due `pending` rows that fire on resume. `pause` takes an optional `reason` (≤200 chars) and is idempotent (re-pausing keeps the original start and reason); `paused_by` is the UI proxy's `x-caller-email`, else `api`. Behind the shared-secret middleware — not `SCHEDULED_ADMIN_TOKEN`, which the UI cannot send. Any caller may pause; `resume` is principal-only (`is_principal_or_self`, 403 otherwise; open while no principal is rostered; a header-less caller resolves to the principal as in `chat`), and status carries `can_resume` for the viewer so the UI hides Resume from everyone else. |\n| `workspace` | `GET /workspace`, `PUT /workspace` | Solo/team mode, the user's time zone and the principal's role (`memory.workspace_settings`). Both return `{mode, timezone, effective_timezone, role_kind, role_title, reports_to, remit, measured_on, company_domains, company_domains_custom}` — `timezone` is what the user set (null when unset), `effective_timezone` the zone in effect (`timezone`, else `USER_TIMEZONE`, else UTC), and each role field is null until set. `PUT` is a partial update: only the fields sent change; `mode` is `solo` or `team` (not null), `timezone` an IANA zone, or null/blank to clear it; `role_kind` is `owner`, `in_house`, `independent` or `other`, and `role_title` / `reports_to` / `remit` / `measured_on` are free text (trimmed, at most 120 / 120 / 500 / 300 characters), each null or blank to clear it; an unknown zone, a bad mode or role kind, an over-long role field or an unknown field is a 422 and changes nothing. Switching to solo cancels every pending department check-in, switching to team re-schedules them, and a new zone re-times the pending briefs and reflection; a role change has no side effects (the next turn reads it). `company_domains` is the company's own email domains (a teammate matches by local part on them — see Org): `GET` returns the ones in effect (the stored list, or the domain of the principal's primary address, with `company_domains_custom` false) only to the same caller the role is shown to, `[]` for anyone else; `PUT` takes a list (at most 10 plain domain names, never a free-mail provider's — 422 otherwise, the value never quoted) or null / `[]` to go back to deriving them, and a change is audited with the new list. Each change writes a `workspace_settings_changed` audit row (a role change adds `details.role_fields_changed`, the names of the fields that changed — never their text). The role is the principal's: `GET` returns it only to a caller `PUT` would accept and reads it as nulls for anyone else. `PUT` is the principal's alone (`is_principal_or_self`, 403 otherwise; a header-less caller resolves to the principal as in `chat`) and open while no principal is rostered, so first-run setup can pick a mode. Both work before onboarding — unlike `company-profile`, nothing here needs a profile. |\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). `DELETE /scheduled/{id}` cancels a `pending` row (409 otherwise). Like pause it only stops work, so any signed-in user may — the UI proxy's `x-caller-email` is trusted when the request also carries the `BACKEND_SHARED_SECRET` `x-api-key` — as may a matching `X-Admin-Token` (`SCHEDULED_ADMIN_TOKEN`) or a loopback caller with no token set; otherwise 401 (token set) or 503. Audited as `scheduled_action_cancelled`. |\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`, `GET\\|DELETE /workflows/custom/{name}/targets`, `POST /workflows/runs/{run_id}/decision`, `POST /workflows/runs/{run_id}/rerun`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. `rerun` queues a failed scheduled run (a department check-in, a saved workflow on a cadence) once more, due now (see Scheduler); the principal may, and for a saved workflow the person it delivers to; 409 for a run that did not fail, one started from `/jobs` (\"Start this one again from its page\") or one already queued again. Custom definitions come back with a server-managed `owner_person_id` (the creator — the web caller on `POST`, set on insert only; a client-sent value is ignored), who is asked to approve a workflow's first write to a new target. `GET /workflows/custom/{name}/targets` lists the targets its tool steps may write to without asking and `DELETE …/targets?value=` forgets one. `POST /workflows/{name}/runs` is a 403 (\"Only the principal can run this workflow.\"), audited, before any run row exists, when the workflow is one only the principal may start in the workspace's mode (`weekly_review` always, `morning_brief` in solo) and the caller is not the principal. A request with no `x-caller-email` counts as the principal; with no principal on the roster, no signed-in caller does. This governs starting a run only. A run started by hand (this endpoint, or `run_workflow` / research in chat) records its starter as `owner_person_id` and is theirs alone: `GET /workflows/runs` lists the team's (scheduled, no owner) runs plus the caller's own and the ones waiting on them, and `GET` / `DELETE /workflows/runs/{run_id}` and `POST /workflows/runs/{run_id}/decision` are a 404 for anyone else's, the principal included. A signed-in email that is on nobody's People entry cannot start one (403), and a run whose starter can't be read is refused (503); its steps read and draft documents as the starter only. `POST /workflows/runs/{run_id}/decision` with `{decision: \"approve\"|\"reject\"}` answers a run awaiting a yes/no sign-off from the web app — 403 unless the caller is the person it waits on or the principal, 409 if it isn't awaiting or needs a written reply — through the same `apply_resolution` a chat reply uses. Custom create/update also rejects (422) any action-step tool that does not resolve, and so does `POST /workflows/custom/{name}/activate` when turning a workflow **on** — that click is the approval for a tool workflow chat saved switched off (turning off is never checked). Turning on a workflow with action steps requires the body `{is_active: true, definition}` carrying the definition the user reviewed; if the stored one differs (ignoring `is_active` and timestamps) it returns 409, and the switch itself is a compare-and-set on the validated revision (`dynamic_store.activate_if_unchanged`, keyed on `updated_at`), so a save that lands while the tool check awaits the gateway — even from another process — is a 409 too, so only what was shown gets switched on. `GET /workflows/custom` lists inactive definitions too; `GET /workflows/{name}` 404s for them. The two `tools` endpoints return `{tools: [{name, description, read_only, source}]}` for the advanced editor's tool picker and the review card; `read_only` is true only when the name says it reads (a label, not a control). The run stream adds a `progress` event (`step_id`, `summary`) while an action step uses tools. Each catalog entry (`WorkflowMeta`) carries `is_custom`, `background` (true for the system-run built-ins the UI files under “System”) and `quick` (true for a Quick workflow, one per playbook nothing else follows, named `quick_<playbook>`). 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`, `/skills/{name}/restore` | Skill registry (the UI's **Playbooks**) CRUD and search. `PUT` on a built-in saves a company customization that shadows it; `DELETE` returns `{name, outcome}` — `deleted`, `reverted` (customization removed, built-in back) or `hidden` (built-in hidden for this company); `restore` un-hides; `GET /skills?include_hidden=true` lists hidden built-ins. List and detail carry `used_by` — `[{name, title, is_custom}]` of the workflows that follow the playbook (switched-off custom ones included) (`WorkflowMeta.playbooks` is the other direction). |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. `POST /evals/runs` is a 403 when a workflow scenario names a workflow that only the principal may start in the mode it runs in (the weekly review; the morning brief in solo) and the caller is not the principal — the Jobs page's rule for starting a run; stored results are read under the existing `/evals/runs` rules. |\n| `memories` | `/memories/{decisions,initiatives,advice}`, `GET /memories/facts`, `POST /memories/facts/{fact_id}/{retire,approve,decline}`, `GET /memories/facts/approval`, `PUT /memories/facts/approval/{person_id}`, `GET /memories/people`, `GET /memories/people/{person_id}/conclusions` | Episodic-memory record management; the standing facts the Pulse Corrections tab reads (`{facts: [...], can_retire, retirable_ids, can_review}`; each fact carries `recorded_by_role` / `recorded_by_name`; `?include_inactive=` default true, honoured for the principal only; anyone else gets the active rows plus their own `proposed` ones, with the provenance (`session_id`, `turn_id`, `recorded_by_person_id`, `retired_reason`, and `source_quote` except on their own facts) blanked, never retired, replaced or declined text; `?limit=` 1–500) and their retire (the principal any fact, a teammate only one they recorded that the principal has not approved — else 403; the audit row names the teammate; 404 for an unknown or `profile` row, 409 when no longer active; writes a private `fact_retired` audit row); approve / decline a teammate's `proposed` fact (principal only, else 403; 409 when it is not proposed; private `fact_reviewed` row); and the per-teammate \"needs my approval\" switch (on by default; `GET` lists `[{person_id, full_name, needs_approval}]` for every active team member but the principal, `true` for anyone not yet set; `PUT` takes `{needs_approval}`, 404 for anyone else; both principal only; private `fact_approval_changed` row); plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5) and one person's full conclusion list, paged newest first (`{status, person_id, items, page, size, total, has_more}`; `?page=` ≥1, `?size=` 1–100, default 50; 404 when the person has no peer). Peer memory is each person's own: the overview holds only the caller's entry (none for a caller off the roster; `conclusion_total` counts only theirs), the principal included, and `/conclusions` for anyone but the caller is a 404. |\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/understand`, `/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). `commit` answers 403 when the draft would make a different person the owner and the caller is not the current owner (setup demotes the old principal, and any signed-in user can open it). It also takes an optional `owner_email` — the principal's sign-in email, which the review screen pre-fills from the signed-in user — checked before anything is written (422 if it is malformed, already another person's, or would replace the principal's existing email — setup only fills in a missing one; 403 if the caller is not the owner and it is not the address they signed in with, since the roster is the sign-in allow-list) and saved on the principal's People row, so the owner's chats resolve to them from the first turn. |\n| `workflow_designer` | `POST /workflows/designer/start`, `POST /workflows/designer/edit`, `POST /workflows/designer/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard, and editing a saved workflow by conversation. `/edit` (`{name}`) opens a session on a saved custom workflow with no model call: the stored definition is the starting draft, and every response then carries `editing` (its name) and `original` (the stored definition as the session opened on it); drafts keep that name and its on/off state whatever the model writes (404 for an unknown workflow). The UI saves one with `POST /workflows/custom/{name}/save-edit` (`{session_id, definition}`): the server saves the session's own draft, never a client-sent body, and only when it equals the `definition` the user reviewed (a later message is a 409, so the click saves only what was shown); it re-validates it, keeps the stored on/off state, and writes only if the stored workflow is still the version the conversation opened on — otherwise 409, as it is for a session about another workflow or one with nothing drafted yet. It sits under `/workflows/custom` so anything that limits writes to custom workflows covers it too. The `workflow_designer` agent asks clarifying questions (`phase: \"question\"`, with `hint` and up to four suggested `options`), then returns `phase: \"draft\"` with `draft.definition` (exactly the body `POST /workflows/custom` takes), `summary`, and `assumptions`; every response carries the `transcript`. **Nothing is persisted here** — sessions are in memory, and the UI saves through `POST /workflows/custom`. Errors are fixed strings (422 over the 8,000-char message cap or the transcript cap, 404 for an expired session, 409 while another turn on the same session is still running, 502/504 for model failure or timeout). Mounted ahead of the `workflows` router. |\n| `python_jobs` | `GET /python-jobs/{job_id}/{name}` | A result file a Python job (`run_python_job`) wrote, the principal's alone (403 otherwise), served as a download (`Content-Disposition: attachment`, `Content-Security-Policy: sandbox`, `nosniff`, `Cache-Control: no-store`); 404 for a bad id or name or a file past its 7 days. |\n| `saved_tools` | `GET /saved-tools`, `GET\\|PUT /saved-tools/{name}`, `POST /saved-tools/{name}/rollback` | The scripts the Executive saved as tools (Settings → Advanced → Saved tools), the owner's alone (403 otherwise). The list gives each tool's name, description, on/off, current version, `kind` (`script` or `python`, a kept Python job) and the tools it calls, plus whether `SAVED_TOOLS_ENABLED` is on; the detail adds the script, every version and the last 20 runs. `PUT {enabled?, workflows?, version?}` turns one on or off (off also turns it off for workflows, so turning it back on never re-arms unattended runs), and turns the named `version` — the one the owner looked at, never whatever is current by then — on for workflows (or workflows off); a Python tool never turns on for workflows (409) — turning workflows on lets more run unattended, so it needs a request tied to the owner (signed sign-ins or local login, as Take the lead's switches do; 409 otherwise); `rollback {version}` makes that version the one that runs. Both are audited as `saved_tool_changed`. The Executive saves tools itself through `run_script`; there is no create route. |\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. Its final answer saves the profile and adds people with their emails and a principal, so once there is an owner only they can send it (403, and the session rolls back so the owner can still finish it). `/onboard/start` reads the workspace mode once for the session: solo skips the Team Size, Team Members and Fractional Executives steps. Each status response's `current_step` / `total_steps` count only the steps that session asks, and `optional` says whether the current step can be skipped. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `alerts` (private cards) | `POST /alerts/{id}/ack`, `/reopen`, `/alerts/bulk-ack` | An alert tagged `private:principal` (see Today) is a 404 on ack and reopen for anyone but the principal, and their bulk sweep skips it. A roster-request card (source `roster_request`) is a 409 on `ack` even for the principal — it is answered at `/people/requests/{id}`, since acking would leave the sender waiting with nothing to show it — and, as an exempt source, `bulk-ack` and `reopen` skip it. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived **team members** with an email, offered to the UI's sign-in gate — a contact is never on it, so adding a client to reach them by email no longer lets them sign in. 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. With local login (`make dev` with Google sign-in not set up — the UI then listens on 127.0.0.1 only) the UI signs in without an email, sends no `x-caller-email`, and the backend resolves the caller to the principal, as it does for the CLI. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. `POST /fixtures/reset` leaves no departments, like a new install (`departments_seeded` is always 0). |\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`, `POST /webhook/slack` | Inbound integration callbacks (self-verified). `/webhook/slack` answers 503 unless `SLACK_SIGNING_SECRET` is set. |\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. |\n\n**Take the lead** (`api/routes/take_the_lead.py`): `GET /take-the-lead` returns the As the Executive switch, its six Ask first switches (`{kind, label, hint, on}`, the hint a plain line on what each one catches), the company's rules, whether this server can tie a change to the owner (`available`), and whether the Executive is paused. `PUT /take-the-lead` takes `{enabled?, ask_first?}`, and `POST /take-the-lead/rules` / `DELETE /take-the-lead/rules/{id}` add or remove a company rule (`{kind: person|domain|words|amount, value}`, 422 on a bad one). All four are the principal's alone (403). Anything that lets more happen on its own (turning it on, turning an Ask first off, removing a rule) needs a caller the API can tie to them (`delegation.verified.caller_refusal`, else 409). `GET /today/activity` adds `took_the_lead` rows (what Take the lead did, named, not quoted) and, for the caller alone, `sent_as_you` rows for what Handle it for me sent as them. Under `/delegation`: `PUT /delegation/take-the-lead {enabled}` is Take the lead as you (the owner's only for now; turning it on turns Handle it for me on), and `GET|POST /delegation/take-the-lead/rules` and `DELETE …/rules/{id}` manage the caller's own rules. `HandleItOut` gains `lead` and `lead_available`. A `take_the_lead_action` decision is approved or rejected through the existing `/decisions/{id}/approve|reject`. Training: the response also carries `training` (In training: everything waits unless allowed), `learned` (`{id, label, feature, example, uses, created_at}`: what it was allowed, the edit kept as an example by field) and `suggested` (`{key, label, approvals}`); `PUT` takes `training?` too, and leaving training while on needs the same provable owner as turning it on. `POST /take-the-lead/learned {key}` allows a current suggestion (404 for anything else; provable owner), `DELETE /take-the-lead/learned/{id}` makes it ask first again. `learned` also lists the owner's own Act as me senders (`feature` `act_as_me`), never anyone else's, and Remove works on those too. On a `take_the_lead_action` card, `POST /decisions/{id}/approve` takes `edits.input` (the card's editable fields, 422 for any other; the principal's alone, 403 for an area approver) and `edits.allow: true` (a training card only, 422 otherwise; the principal from a provable request, 403 otherwise), finishing `approved_with_edit` when a field changed.",+ "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). With local login (`OE_LOCAL_LOGIN=1`, which only `make dev` sets, and only while neither Google nor SSO sign-in is set up) a second middleware answers 403 to any request whose raw `Host` is not `localhost`, `127.0.0.1` or `[::1]` (except a webhook that verifies its caller: Google Chat and Slack always, Telegram only with a `TELEGRAM_WEBHOOK_SECRET` Telegram can send), and to any write whose `Sec-Fetch-Site` is present and not `same-origin`/`none`. The UI signs that owner in with no password and this API usually has no secret, so without it a web page in the owner's browser could drive the API as the principal — by DNS-rebinding its own hostname to 127.0.0.1, or by posting a plain form from another site or localhost port. CORS is restricted to the UI origins in `BACKEND_ALLOWED_ORIGINS`, plus the `make dev` UI on `localhost:3000` only when `OE_PUBLIC_DEPLOYMENT` is unset, so a public instance never answers a localhost page with credentials. 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\n**Who is calling** is read in one place, `api/caller.py`, which answers with a `Caller` kind and email; a test fails on any other read of an `x-caller-*` header. By default (`open`) it is the `x-caller-email` the UI proxy stamps from the sign-in, trusted because whoever holds the shared secret is trusted as the proxy, and a request with none runs as the principal. **Signed callers** remove that trust. With `CALLER_ASSERTION_PUBLIC_KEYS` set, the proxy signs every request with an Ed25519 key only the UI holds, and a third middleware checks the `x-caller-assertion` header:\n\n- **What it covers.** It is good for one method, the exact path and query, at most 120 seconds, and one use. The API keeps used ids in memory.\n- **What it names.** A `user`, by email, or the `operator`: local login, which runs as the principal.\n- **No caller header at all** is a `service`, for scripts or MCP clients holding only the secret. It is never the principal, not even on an install with no owner yet, so it can't save a first setup.\n- **Anything else is a 401.** That includes an `x-caller-email` without an assertion (`caller_assertion_required`), and a bad, expired, reused or mismatched assertion (`caller_assertion_invalid`).\n\nPublic keys that can't be read stop the boot, rather than fall back to trusting the header. `scripts/make-caller-keys.py` makes the pair, and `scripts/mint-caller-assertion.py` signs one request for curl. The API holds only public keys. Setup's API-protection check warns while a shared secret is set without them.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat`, `POST /chat/stop`, `POST /chat/add`, `POST /chat/background` | SSE stream of a live Executive turn, with a `: keepalive` comment every `CHAT_STREAM_KEEPALIVE_S` while the turn is quiet. `POST /chat/background` starts a new chat that the server answers to the end with nobody connected (a phone approving a card, then closing the app): it answers `202` with the new `session_id` once the same caller, access and quota checks as `/chat` pass, the turn saves itself as a `/chat` turn does, and one caller may have three running at once (`429` beyond that). `POST /chat/add` hands the running turn a message the person typed while it works; the turn takes it at its next step and the stream names it in a `message_added` event, and a second `POST /chat` on the same conversation waits for the first to finish. 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. A `session_id` in the body must be a chat the caller may use (the same ownership rule as `sessions`). If it isn't, the turn runs in a fresh chat instead, so nothing is written into someone else's session and the reply looks the same as for an unknown id. An unknown namespaced id (`slack:…`, `telegram:…` and so on) is ignored and a fresh chat is started, because those ids belong to the channel adapters and claiming one first would make the caller its owner. 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. An optional `memory_text` (1–2000 chars) is what peer memory records as the caller's words instead of `message` — the briefing handoffs send it because their seed quotes the Executive's own card; `POST /chat/upload` derives it from the typed text and filenames. Since it never reaches the transcript, the `chat_turn` audit row keeps it beside `message`. After the reply — a stopped or timed-out one too, before the `stopped` / `error` / `done` frames — a turn that looked at anything sends one `sources` event, `{type, session_id, sources: [{kind, title, url}], unavailable: [area]}`: `kind` is `company`, `knowledge`, `notion`, `research`, `document` or `web`, `url` is only ever an http(s) link or, for an earlier document, `/artifacts/<id>`, at most 12 sources (6 from the web, pages the reply cites first), and `unavailable` names parts of the analysis (\"finance\") whose specialist failed or said nothing every time it was asked. It is persisted with the reply as `chat_messages.sources`. A request that carries `x-caller-email` marks its turn signed in (`Session.web_caller_signed_in`), which Act as me needs on a deployment without local login. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller, and each chat carries `preview`: its last message as one plain line, Markdown marks stripped and cut at a word near 120 characters, with `You:` before the person's own words. With `?q=` it is a search: the caller's own chats whose title or message text contains the words (case-insensitive, `LIKE` with wildcards escaped), each with `match_count` (messages that contain them; 0 for a title-only match) and `snippet` (the newest matching message, around the match, prefixed `You:` or `Executive:`). Scoped exactly like the list, so nobody else's conversation can match. The Chats page searches this way and opens a result with `?find=`, so the chat starts on that message and steps through the others. A chat-app conversation started with /new is left off the list until its first turn (`memory.conversations`). Every per-session route checks ownership, because session ids are guessable (`slack:dm:<user id>`, `telegram:<chat id>`): only the session's owner or the principal gets through, and a legacy row with no owner is the principal's alone. A teammate's own chat (a web chat, a DM, a private Telegram chat; not a channel or group conversation, `chat._shared_space`) is theirs alone, the principal included, as their mail with the Executive is. Anyone else gets the same 404 as for an unknown id, so the routes can't be used to find out which chats exist. The one other way in is having started the chat in this process (matched by Person id or verified email, so it survives the caller being added to the roster), which is how a caller the roster can't resolve keeps using their own chat. That record is in memory, so after a restart such an ownerless chat is refused for reads. The principal can continue someone else's ownerless chat without becoming its owner. Deleting a session also drops its in-memory copy, so a later turn naming that id starts fresh. The feedback route records 👍/👎 (`{\"feedback\": \"up\"|\"down\"|null}`) on one assistant reply; only the session's own caller or the principal may rate it. The rater is stored (`feedback_by_person_id`), and a 👎 on a reply to the rater's own message triggers a working-style pass for them (paced; see attunement). The chat stream's `done` event carries `message_id` for the persisted reply. The followup route returns `{\"suggestion\": string|null}` — one suggested next user message, written by the utility-fast model from the last few turns, that the chat composer shows as its greyed placeholder (Tab / → or the inline chip fills it in without sending). It is null unless the session ends on a persisted assistant reply, and null (uncached) when the model fails. Same ownership check as feedback; successful suggestions are cached in-process per (session, reply id). Messages from `GET /sessions/{id}/messages` carry each assistant reply's saved `sources` (the same shape as the chat stream's `sources` event, without `type`), so a reloaded chat shows them again. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/value`, `GET /today/top-three`, `GET /today/weekly-review` | Morning-brief aggregation, recent-action rail, Pulse heartbeat heatmap (per-day activity counts), and the owner's Your month tally (`GET /today/value?period=month|week&offset=N`: counted lines beside the period before plus the finished reports, owner only, 403 otherwise; see Today). `GET /today` carries the viewer's cached \"What's going on\" `narrative` with `narrative_generated_at` (when it was written) and `narrative_stale` (a fresher one is being written — the page re-polls; see Today). A proposal backed by a roster request carries `roster_request` (the new sender's server-derived details and held-message previews; the principal's only) and is answered through the `people` routes below. `brief-delivery` returns the latest morning brief or end-of-day digest that didn't reach the owner, as `{brief, at, problem, fix, readable}` in plain language (`readable` is false when it couldn't be written, so there is nothing to read), or null — null while briefs go out, once the cause is fixed, while the scheduler is off, and for anyone but the owner (`chat._caller_is_principal_or_unclaimed`); it carries no address or channel id. `top-three` and `weekly-review` feed the solo Briefing's own cards and answer only in solo mode and only to the principal (`workflows._caller_is_the_principal`: a principal match or no caller header, never an unclaimed roster); anyone else, and team mode, get null. `top-three` returns `{items: [{key, kind, text, why, slot}]}` — the morning brief's top three from the same code (`build_top_three(principal_due_soon())`), `slot` a free block like `10:00–11:00`, `\"\"` when none is left, null when no calendar was read — and is kept off `GET /today` because its calendar read may take up to 4 s. `weekly-review` returns the latest completed `weekly_review` run as `{run_id, completed_at, period, top_three, excerpt}` (next week's top three as plain text; `excerpt` when that list is empty), or null when none has completed. |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive`, `GET /people/requests`, `GET /people/requests/{id}`, `POST /people/requests/{id}/approve`, `POST /people/requests/{id}/decline`, `GET\\|POST /people/{id}/open-loops` (a `POST` tells the owner once and returns `notified`: `sent` with the channel, `held`, `not_reached` or `skipped`; see Attunement), `POST /open-loops/{loop_id}/close`, `GET /people/{id}/outreach`, `GET\\|PUT\\|DELETE /people/{id}/attunement` | Roster CRUD and scope lookups. Every `Person` carries `kind` (`team` / `contact`). `GET /people` lists team members only unless `?include_contacts=true` (the People page asks for both; the department-head and workflow pickers keep the default); `POST` / `PATCH` accept `kind`, and a principal contact is a 422 either way. They also take `email_aliases` (other addresses the person writes from, at most 10; on `PATCH` the full list replaces the current one, omitted leaves it): an alias matches their mail and may be emailed but never signs in; a malformed one is a 422, and an alias — or a new primary `email` — that is already someone else's address or alias is a 409. Every `POST` / `PATCH` then closes any pending roster request whose sender now matches someone and replays its held messages. Adding, editing and archiving (`POST`, `PATCH`, `/archive`) are the principal's only, or anyone's while no one is principal yet so a first setup can add its owner (`chat._caller_is_principal_or_unclaimed`, the check behind `PUT /workspace`; a request with no `x-caller-email`, such as the CLI or local login, counts as the principal). Anyone else, a person editing their own row included, gets 403 before the person lookup, so it can't probe which ids exist. Contacts are private to the principal (`caller_is_principal`: the signed-in email is the principal's, or no `x-caller-email`; stricter than the owner rule above, so while no one is principal nobody is): for anyone else `include_contacts` is ignored, a contact's id is a 404 on `GET /people/{id}` and open-loops (exactly as for a missing id; `PATCH` and archive are already a 403 for them), and creating a contact or turning someone into one is a 403, even on a first setup with no principal yet. `GET /people/me` returns `{person_id, is_principal}` so the UI offers contacts to the principal only. `GET /people/by-scope/{token}` never returns a contact. 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`). `POST /people/{id}/open-loops` `{task, due_date?}` assigns that person a task (201 with the loop; `due_date` is a local date, due 17:00 in the user's timezone, clamped to 60 days, default 2 days): any active team member may assign anyone on the team, 403 for anyone else; 409 for an archived person, a contact (as seen by the principal), a person at the open-loop cap, a duplicate or open loops turned off; 422 for an empty task. Nobody is messaged at assignment — the owner is chased once it is due. `/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. `/attunement` reads, replaces (`rules`: up to 4 strings, or omitted to only set `locked`) or resets the person's working-style rules — same access rule, 404 for an archived person; `PUT` rejects a rule that is not purely about style with 422. Archiving a person also drops their working style and frees their aliases. The **roster-request** routes (declared before `/people/{person_id}`) are the principal's alone (`caller_is_principal`; anyone else gets 404, as for a missing id): `GET /people/requests?status=pending|approved|linked|declined|expired|superseded|all` lists up to 100 (`id`, `channel`, `channel_ref`, sanitised `display_name`, `profile_email`, `on_company_domain`, `suggested_kind`, `suggested_person_id` / `_name`, `status`, `resolved_person_id` / `_kind`, `message_count`, timestamps, `ack_sent`, and `previews` of the held messages while pending — shown to the principal, never to a model); `approve` takes either `link_person_id` (+ `replace_channel_id`) or `full_name` + `kind` (no default: 422 without both) + optional `role`; `decline` takes no body. An answered request is a 409, a chat id or address already on someone else is a 409; the held messages are replayed (or dropped) in the background. |\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. A `cadences` spec that does not parse is rejected with a 422 (empty means no cadence, i.e. the check-in is off); a changed `check_in` cancels the pending check-in and queues the next one on the new schedule. `GET` and `PATCH /departments/{slug}` return the department state plus `next_check_in_at` (ISO UTC of the pending check-in, `null` when it is off, the workspace is solo or none is queued); the list route does not carry it. A new `head_person_id` must be a team member: an unknown id and one of the principal's contacts get the same name-free 422 (`person_id N is not on the team.`), so the route — open to any signed-in user — never reveals that a contact exists; an unchanged head is not re-checked. `POST .../goals` requires only `key_result`: a missing or blank `period_value` is filled with the current period for `period_type` in the user's zone (the same label `create_goal` uses), and `target` defaults to empty. `PATCH .../goals/{id}` rejects a blank `key_result` or `period_value` with a 422; `target` may be cleared. |\n| `agents` | `GET /agents`, `GET /agents/models`, `GET /agents/models/options`, `GET /agents/presets`, `POST /agents/presets/{id}`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. `/agents/models` is the flat model allowlist the PATCH validator uses; `/agents/models/options` returns the same ids in the same order, each tagged with `provider`, `provider_label`, `route` (`direct` / `openrouter` / `local`) and a display `label`, for the Council's Provider → Model picker. `AgentDetail` carries `instructions` (additional instructions, appended after `prompt`, which stays the built-in prompt or its replacement); `PATCH` and `/test` accept `instructions` (max 4,000 chars, blank clears it). `GET /agents/presets` lists the Fast, Balanced and Thorough quality presets (each with `available` and the resolved `model` for this install) plus `active` (null when the council is Custom), `base` and `custom_agents`; `POST /agents/presets/{id}` applies one by writing per-agent model and deep-reasoning overrides and returns the same shape (404 unknown preset, 409 when the install allows none of its models). Each `AgentMeta` carries `visibility` (`core` or `internal`) so the Council's simple view can list core agents first. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/approve`, `GET /alerts/approvals/{id}`, `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/snooze`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `approve` (body `{edited_body?}`, 202) carries a proposal card out on the server and records who approved it and when (`alerts.approvals`, see Today): it queues the scheduled action a department-gated card held, or runs one Executive turn as the approver in a new chat (`session_id`). 409 for a card already approved or closed, a decision-backed card (approved at `/decisions`), a roster request or a drafted artifact; 403 unless the caller is the card's routed person or the principal (an unrouted card is the principal's); 429 when the caller already has three background turns running. `GET /alerts/approvals/{id}` reads one back (`running`, then `done` / `failed` with `outcome`) for its approver, the card's person or the principal (404 for anyone else). `snooze` (`until`, an ISO time up to 30 days ahead; `null` clears it, the Undo) hides an `unread` card until then by setting `snoozed_until` (409 on a closed card or a roster request); the TTL then counts from the snooze, so a card snoozed past its TTL still comes back. `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`, `GET /artifacts/{id}`, `GET /artifacts/{id}/download?as=`, `POST /artifacts/{id}/archive`, `POST /artifacts/{id}/restore`, `DELETE /artifacts/{id}` | Browsable deliverables in any format — Markdown, HTML, Word, Excel, or a link into a connected app — with `format`, `downloads`, `external_url`, `supersedes_id` and, for an extension's kind of document, `collection` / `collection_label` on every summary (`orchestrator.extensions`; archive, restore and delete tell the collection first and answer 502 if it refuses). `download` renders the file (Word/Excel built at request time from the stored text; any Markdown artifact, workflow output included, can export `?as=docx`) and is always an attachment with `nosniff` and a sandbox CSP. Every route answers for the signed-in caller (`artifact_records.Viewer`): a drafted artifact is its owner's alone (`alerts.owner_person_id`, the person whose conversation published it; none = the principal's), a workflow output follows its run (`persistence.run_visible_to`), and anything the caller may not see is a 404 like a missing id, the principal included. `POST /alerts/{id}/ack` and `/reopen` answer 404 for someone else's drafted artifact the same way. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET`/`PUT /decisions/classes/meeting_scheduling`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). What approve/reject/cancel do is per class (`DECISION_CLASSES`, one `DecisionClassSpec` each; meeting booking books on approve and deletes on cancel; `delegation_reply`, an inbox reply card, is its approver's alone (`approver_only`) — hidden from everyone else, the principal included when it is a team member's — sends its Gmail draft on approve and, after a reject, deletes the draft unless it was edited; `department_action`, a team member's chat send or edit their department held (see Org), is the principal's and its approver's alone (`principal_and_approver`), makes that exact call on approve and audits `department_action_done` / `_failed` / `_declined`), and an instance of a class with no spec gets 409 instead of being carried out as another. Only the principal, or the person the decision went to for approval (`approver_person_id`), may approve, reject or cancel it. Anyone else gets 403, and a decision nobody was asked about, or one private to the principal, is the principal's alone. The resolver is recorded as `resolver_person_id`, and a reject that loses the race to another answer is a 409. `GET /audit/reliability` is the principal's alone (403 otherwise), because it counts private decisions too. A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. An approval whose caller resolves to the principal runs the booking inside `grant_contact_egress()`, so a meeting the principal proposed with a contact can be created. Such a booking's payload is marked `private`: it is proposed to the principal, left out of anyone else's `GET /decisions`, and a 404 for them on `GET /decisions/{id}` and every action route. Reviewed in the briefing — there is no separate proposals page. The class routes read and set how meetings are handled: both return `{decision_class: \"meeting_scheduling\", mode: \"propose\" \\| \"auto_execute\"}` (default `propose`); the `PUT` body is `{mode}`, principal-only (403 otherwise, open before a principal exists — but then only `propose` can be set: `auto_execute` is a 409 until a non-archived principal is on the roster), 422 on any other mode, and a change writes a `decision_class_mode_changed` audit row. In solo mode the class mode decides a booking, and `auto_execute` applies only to a turn the principal started on a verified surface — any other turn gets a proposal. |\n| `delegation` | `GET`/`PUT /delegation`, `GET`/`PUT`/`DELETE /delegation/voice`, `POST /delegation/voice/learn`, `POST /delegation/voice/describe`, `POST /delegation/voice/signature`, `PUT /delegation/inbox`, `POST /delegation/inbox/check`, `GET /delegation/replies`, `PUT /delegation/replies/{id}/text`, `GET /delegation/actions`, `PUT /delegation/handle-it`, `PUT /delegation/disclosure`, `PUT /delegation/training`, `DELETE /delegation/learned/{id}`, `GET /delegation/handled`, `PUT /delegation/team` | Act as me — the **caller's own** delegation only; nobody sets it for anyone else. It answers the principal, and a team member once the owner lets them; anyone else gets 403 `not_available_yet`. `GET /delegation` returns `{enabled, gmail: {status, message, email, connect_command, outlook_connect_command, provider}, inbox: {enabled, status, message, watch_since, last_poll_at, checking}, handle_it: {enabled, mode, available, sent_today, lead, lead_available}, training: {replies, follow_ups, actions, drafts, learned}, disclosure: {enabled, handle_it, approved_sends, line}, team}`, where `team` is the owner's switch for the principal while `DELEGATION_TEAM_MEMBERS` allows it — `{enabled, members: [{person_id, name, enabled, inbox, drafts_30d, sent_30d}]}`, counts only — and `null` otherwise. `PUT /delegation/handle-it` takes `{enabled?, mode?}` (`mode` is `careful`, `balanced` or `bold`; anything else is a 422 `bad_mode`) from a caller the API knows is that person — 403 `not_yours`, 409 `caller_signing_required` with only the shared secret — and turning it on needs Act as me and Draft replies to my inbox on (409 `act_as_me_off` / `inbox_off`); `GET /delegation/handled` returns `{replies: [{decision_id, sent_at, to_name, to_email, subject, body, open_questions, gmail_link, source}]}`, the caller's replies and follow-ups (`source` `follow_up`) sent on its own in the last 7 days; a card on `GET /delegation/replies` carries `source` the same way, `can_allow` while Replies (Follow-ups, on a follow-up) is in training, and `learns_style` while Drafts is. `PUT /delegation/disclosure` takes `{handle_it?, approved_sends?}` (any other field is a 422), the caller's own switches for the AI line on replies sent as them (`disclosure.enabled` is the install's `AI_DISCLOSURE`); turning one on needs no signed sign-in, turning one off does (409 `caller_signing_required`), and a change is audited as `delegation_disclosure_changed`. `PUT /delegation/training` takes `{replies?, follow_ups?, actions?, drafts?}` (any other field is a 422) and returns the `GET /delegation` shape; putting Replies or Follow-ups in, or Suggested actions out, needs no signed sign-in, anything else does (409 `caller_signing_required`), and putting Replies or Follow-ups in turns Take the lead as you off (`PUT /delegation/take-the-lead` on answers 409 `in_training` while they are). `training.learned` is `[{id, label, setting, example, uses, created_at}]`, what the caller allowed or kept in training (`setting` `replies`, `follow_ups`, `actions` or `drafts`; the kept example, or \"\"); `DELETE /delegation/learned/{id}` removes one of the caller's own (404 for anyone else's). `PUT /delegation/team` takes `{enabled}` from the principal alone (403 `principal_only`; 409 `not_available` when the install doesn't allow it). The Gmail `status` is `connected`, `not_configured`, `needs_reconnect`, `mismatch`, `no_email`, `shared_mailbox` or `error`, checked live with Google on each call. `PUT` takes `{enabled}` (any other field is a 422); turning it on needs the caller's own Gmail connected, otherwise a 409 whose code says why (`gmail_not_connected`, `gmail_needs_reconnect`, `gmail_mismatch`, `no_email`, `shared_mailbox`, `gmail_error`). The voice routes show, learn (from the caller's sent mail, one pass at a time — a 409 `in_progress`, `locked`, `too_soon`, `not_enough_mail`, `no_profile` or `changed` when it was locked or edited while learning, or a Gmail code), write it from the caller's own description (`POST /delegation/voice/describe` with `{description}`: one model call applies their words to the profile they have and returns it with a short `sample_reply`, saving nothing, so they review it and save it with `PUT`; a 409 `empty`, `too_long`, `in_progress`, `too_many` past 10 an hour or `no_profile`; no mailbox needed), edit and lock, and reset \"How I write\": a typed field that fails validation is a 422 `invalid_voice` listing each `rejected` field, and `clear_exemplars` / `clear_signature` drop those. `POST /delegation/voice/signature` reads the signature from the caller's Gmail settings again and changes nothing else (a locked profile stays locked), with the same Gmail codes as learning: a 409 when their mailbox isn't connected, it refuses the sign-in or the check itself fails (`gmail_error`), and a 502 `gmail_error` when reading the signature fails. On an Outlook mailbox it is a 409 `signature_unavailable`, since Outlook gives apps no signature to read, and the stored one is left alone. A caller `can_delegate` refuses — anyone but the principal, for now — gets 403 `not_available_yet`, which hides the Settings card. A request with no `x-caller-email` is a 403 `sign_in_required` unless the API runs under local login — a header-less call is not a sign-in (the caller is read through `api/caller.py`, as on every principal-only route). `PUT /delegation/inbox` takes `{enabled}` and turns **Draft replies to my inbox** on or off, returning the same shape as `GET /delegation`: on needs Act as me on (409 `act_as_me_off`) and the mailbox connected (the Gmail codes above, which keep their names for an Outlook mailbox too), and turning Act as me off turns it off too. `POST /delegation/inbox/check` starts a scan now in the background and answers 202 with the `inbox` state (409 `inbox_off` or `in_progress`). `GET /delegation/replies` returns `{cards: [...]}`, the caller's open reply cards from the database alone (no Gmail call): the decision id, the sender's name, address, relation and whether it was verified, the subject, when it arrived, what they wrote, the draft's recipients, subject and body, `open_questions`, `flags` and a Gmail link built from a fixed prefix. **Send** is `POST /decisions/{id}/approve`: it sends the card's draft exactly as it is in Gmail, after checking again that the caller is its owner — which on a server needs signed callers (409 `caller_signing_required` otherwise) — that both switches are on (`inbox_off`), no client slot is active (`client_slot`), the Gmail is connected (the Gmail codes), the draft is still there and unanswered (`draft_gone`, `you_replied`) and its recipients are allowed (`no_recipients`, `too_many_recipients`, `executive_recipient`, `not_from_you`). Recipients that changed, or a newer message in the thread, answer 409 `{code: \"confirm\", message, reasons, recipients}`; approving again with `edits: {recipients: <the list shown>, thread_moved_on: true}` is the second yes. **Send + allow** adds `edits.allow: true`: 422 `cant_allow` unless Replies (Follow-ups, on a follow-up card) is in training, 409 `learned_full` when their list is full, both before anything is sent; `edits.example: true` keeps a draft edited in the mailbox as how they write to that person while Drafts is in training. A draft edited in Gmail between those checks and the send is not sent (`draft_changed`). A double tap sends once (`already_handled`); Gmail refusing answers 429 `rate_limited` or 502 `gmail_error` with nothing sent, and a send Gmail didn't confirm answers 502 `send_unconfirmed` and is settled by the next inbox scan. Dismiss is `POST /decisions/{id}/reject`. `GET /delegation/actions` returns `{cards: [...]}`, the caller's own approval cards (`delegation_actions`): the decision id, when it was made, a one-line `why`, and each action's `index`, `kind` (`invite`, `message`, `add_contact`), `summary` and `text` (a message as it will be sent, or a meeting's description). **Approve** is `POST /decisions/{id}/approve` with `edits: {only: [indexes]}` (and `allow: true` for Approve + allow while Suggested actions is in training: 422 `cant_allow` otherwise or when nothing on it can be allowed, 409 `learned_full`; a card carries `can_allow`); it needs the card's own person signed in (403 `not_yours`, 409 `caller_signing_required`), Act as me on (409 `act_as_me_off`) and a card under a week old (409 `expired`), runs once (409 `already_handled`), and returns the decision with `final_payload_json.results`: per action `done`, `waiting` (sent to whoever approves meetings), `failed` with why, or `skipped`. Every change writes a private audit row. |\n| `history` | `GET /memories/history` (`?q=`), `PUT /memories/history/settings`, `PATCH`/`DELETE /memories/history/{id}`, `POST /memories/history/{id}/forget-conversation` | Always in the loop: the **caller's own** notes and switches only, resolved as for Act as me (a signed-in person on the roster, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{notes, reply_notes, retention_days, effective_retention_days, company_retention_days, retention_choices, can_keep_notes, can_note_replies, can_set_company_retention, share_work_style, can_share_work_style}` (`can_keep_notes`: a team member on the People list may turn notes on; `can_note_replies`: they can use Act as me, so email replies are noted too; `share_work_style`: their own \"Share my work style with the team\" switch, `can_share_work_style`: a team member in a team workspace). `PUT` turns notes on only for someone who may keep them, and `share_work_style` on only for someone who may share it (403 `not_available` for either; turning either off always works), takes a person's retention only when shorter than the company's (422 `invalid_setting`), and the company retention only from the principal (403 `principal_only`). `PATCH` pins or corrects a note; `DELETE` forgets it; `forget-conversation` is \"Don't remember this\". A note that isn't the caller's is 404. Every change is audited privately to its person. |\n| `notifications` | `GET /notifications/settings`, `PUT /notifications/settings` | Settings → Notifications: the **caller's own** settings only, resolved as for the notes (a signed-in person on the People list, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{quiet_hours: {enabled, start, end, days}, delivery, urgent_through, timezone, effective_timezone, held_count, gets_briefs, updated_at}` — `days` is `every_day` or `weekdays`, `delivery` `instant` or `digest`, `timezone` the zone they chose (`\"\"` for the workspace's), `held_count` how many messages wait for their quiet hours or brief (counted, never listed), `gets_briefs` whether they are the principal. `PUT` takes `{quiet_hours, delivery, urgent_through, timezone}` and replaces them (extra fields, equal start and end, a bad time or an unknown zone → 422); switching `digest` → `instant` makes what waited for the brief go now. Audited as `notification_settings_changed`. See Org. |\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), plus `scripts`: how many `run_script` scripts ran (and worked, and in workflows), the tool calls they made, their time, and `turns_avoided` — an upper bound on the model turns those calls would otherwise have needed (each call past a script's first) — and `python_jobs`: how many Python jobs ran (and worked, ran a kept Custom tool, took a chat attachment), their time, CPU, largest peak memory and bytes in and out, and the tokens and charge of the turns that ran one. The Token usage page shows it as a Scripts section. Rows private to the principal (`private_to_principal`: a turn about their private mail, or a row naming one of their contacts on their own turn) are theirs alone: for any other caller, resolved as for `/alerts`, the usage totals leave them out. Once a principal is on the roster, anyone else reads only their own rows (a teammate's own turns, their Act as me work) in the list, by id and in a session, and the principal reads those as actions only — what was done, when and in whose conversation, with the text, details and `full` left out, and no text search over them; any other row's id is a 404, and a session shows only the rows the caller reads. |\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. Only `/health` is unauthenticated; `/health/honcho` sits behind the gate like everything else, because the exemption is an exact-path set. `/health` also carries `google_tools_missing`, the pinned Google tools startup priming could not find: `[]` once it has checked and they are all there, a list of names when a workspace-mcp rename or the configured services and tool tier left one out, and `null` for no answer — Google Workspace is not configured, or the probe has not finished or it failed. Only `[]` asserts they are present. It also carries `gateway`, the MCP gateway's state from its supervisor (`orchestrator.gateway_boot`): `state` is `off` (MCP not enabled), `no_servers` (enabled, the config names none), `starting` (an attempt is running), `up` or `down` (every attempt so far failed; `next_retry_at` is the next one), with `attempts`, `up_since` and `email_poller` (whether the poller that rides on the gateway runs); the failure's own text stays out, since the route is open to anyone, and goes to the log and the owner's notice on Home. A hosted instance whose gateway never came up used to answer `ok` here with no email going out or in. Only `[]` asserts the tools are present, so a probe that died cannot read as healthy; Setup status says which of the three `null` means. |\n| `version` | `GET /version` | The running version, the latest release on GitHub and `update_available`, for Settings → About. The GitHub answer is cached 6h, only a semver `tag_name` is used and the release link is built from it; `UPDATE_CHECK_ENABLED=false` skips the call and still returns the running version. No in-app updater: upgrading is host-side (`docs/deployment.md#upgrading`). |\n| `setup_status` | `GET /setup/status` | Settings → Setup status: one light per part of the install — AI model, company setup, owner, the Executive's address, API protection, Gmail, your own mailbox (Act as me), Slack, Discord, Telegram, Google Chat, the scheduler, the daily brief (when and where it goes) and Honcho — as `{checked_at, checks: [{id, label, state, summary, fix, link, last_activity}]}`, where `state` is `ok`, `warn`, `error` or `off` (optional and not set up), `fix` says what to do in plain language, `link` is an in-app page that helps (`/people`, `/onboard`) and `last_activity` is the channel's latest `integration_inbound` audit time. It tests live, with at most one free read-only call per service, each bounded to 5 s: Anthropic `models.list` (so an organisation key missing `ANTHROPIC_WORKSPACE_ID` shows up), Slack `auth.test`, Telegram `getMe` and `getWebhookInfo`, Discord `users/@me` only while the bot is still connecting, and — once the owner's own Gmail credential exists — Google's token refresh and Gmail `users/me/profile`. It also reads the listeners the lifespan leaves on `app.state` (Slack's socket, the Discord bot and its task, the MCP gateway), the scheduler heartbeat and the pause switch. When `google_workspace` is configured, the lifespan also starts `MCPGateway.prime_pinned_tools()` in the background (held on `app.state.mcp_prime_task`, cancelled at shutdown), so the pinned Google tools named in the prompt are callable without a search. With `DRIVE_SYNC_ENABLED` the lifespan also bootstraps the `drive_sync_scan` heartbeat beside Notion's (see Scheduler); the Drive folder sync has no HTTP route, only the `openexecutive sync-drive` / `purge-drive` CLI. With `CONFLUENCE_SYNC_ENABLED` it bootstraps the `confluence_sync_scan` heartbeat the same way; that sync is run by hand with `openexecutive sync-confluence` / `purge-confluence`. Sample values copied from `.env.example` are named as such without being sent anywhere. No token reaches a response or a log line: probes report a status code, a service's short error code or an exception's class name. Requests within 5 s of a run get that run's answer and concurrent requests share one run (kept per app on `app.state`), so the button can't become a stream of calls to those services. Gated like every other route; the UI adds a sign-in light of its own, from its own settings. |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}`, `GET /documents/sources`, `POST /documents/sources/{drive\\|onedrive\\|notion}/sync`, `GET /documents/{drive\\|onedrive\\|notion}`, `GET /documents/{drive\\|onedrive\\|notion}/{id}` | Upload, list, view extracted text, and delete indexed company docs. `GET /documents` rows carry `source: \"upload\"` and the `domain` the upload was indexed under. The connected-source routes back the knowledge page's single Company documents list: `/documents/sources` gives each source's `{id, label, enabled, syncing, last_run, last_error, interval_minutes, file_count}`; `/documents/drive`, `/documents/onedrive` and `/documents/notion` list synced files from the sync state (`{enabled, last_run, last_error, files: [{id, name, url, modified_at, synced_at, indexed}]}`; a Drive row also carries `unreadable_reason`, why a file with `indexed: false` has no text — e.g. a scan OCR could not read — or null); `/documents/{drive\\|onedrive\\|notion}/{id}` returns the stored text (a OneDrive id is `<drive id>:<item id>`) for an id on record (the path comes from the state, never the caller). They are read-only — a synced file is removed where it lives. `POST …/sync` starts one tick of the same sync the scheduler runs as a background task (202); 409 when the source is not connected or a tick is already running (every sync holds a per-process run lock, so a manual run never overlaps the heartbeat; the route also keeps its own started task per source and re-checks just before starting one, so two simultaneous requests start one tick, not two), 429 with `Retry-After` within 60 s of the last successful run or of the end of the last tick in this process, failed ones included, so a failing or slow source can't be re-run back-to-back. The page's text view never loads images from synced content (a remote image would be a read beacon for whoever edits the shared folder). 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 nine specialist domains (including `sales`) or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. A scanned PDF is converted (`knowledge.pdf_reader`) before it is indexed and in the text view, as are scanned PDFs in `POST /chat/upload` and the client / onboarding intake uploads. The upload is streamed to disk 1 MB at a time and refused with a 413 once it passes 50 MB, and the file is parsed in a short-lived child process (see the RAG section), so a large document does not stay in the API process's memory. A Word or Excel file that cannot be parsed, or whose parse runs out of time, is a 422 with a readable reason. When every parser is busy, the response is a 503 with `Retry-After`. |\n| `executive` | `GET /executive/status`, `POST /executive/pause`, `POST /executive/resume` | Operator pause switch for all autonomous work (scheduler, Gmail poller, workflow resumer); inbound chat and DMs stay live. Status returns `{paused, paused_at, paused_by, reason, held_actions, can_resume}` — `held_actions` counts due `pending` rows that fire on resume. `pause` takes an optional `reason` (≤200 chars) and is idempotent (re-pausing keeps the original start and reason); `paused_by` is the UI proxy's `x-caller-email`, else `api`. Behind the shared-secret middleware — not `SCHEDULED_ADMIN_TOKEN`, which the UI cannot send. Any caller may pause; `resume` is principal-only (`is_principal_or_self`, 403 otherwise; open while no principal is rostered; a header-less caller resolves to the principal as in `chat`), and status carries `can_resume` for the viewer so the UI hides Resume from everyone else. |\n| `workspace` | `GET /workspace`, `PUT /workspace` | Solo/team mode, the user's time zone and the principal's role (`memory.workspace_settings`). Both return `{mode, timezone, effective_timezone, role_kind, role_title, reports_to, remit, measured_on, company_domains, company_domains_custom}` — `timezone` is what the user set (null when unset), `effective_timezone` the zone in effect (`timezone`, else `USER_TIMEZONE`, else UTC), and each role field is null until set. `PUT` is a partial update: only the fields sent change; `mode` is `solo` or `team` (not null), `timezone` an IANA zone, or null/blank to clear it; `role_kind` is `owner`, `in_house`, `independent` or `other`, and `role_title` / `reports_to` / `remit` / `measured_on` are free text (trimmed, at most 120 / 120 / 500 / 300 characters), each null or blank to clear it; an unknown zone, a bad mode or role kind, an over-long role field or an unknown field is a 422 and changes nothing. Switching to solo cancels every pending department check-in, switching to team re-schedules them, and a new zone re-times the pending briefs and reflection; a role change has no side effects (the next turn reads it). `company_domains` is the company's own email domains (a teammate matches by local part on them — see Org): `GET` returns the ones in effect (the stored list, or the domain of the principal's primary address, with `company_domains_custom` false) only to the same caller the role is shown to, `[]` for anyone else; `PUT` takes a list (at most 10 plain domain names, never a free-mail provider's — 422 otherwise, the value never quoted) or null / `[]` to go back to deriving them, and a change is audited with the new list. Each change writes a `workspace_settings_changed` audit row (a role change adds `details.role_fields_changed`, the names of the fields that changed — never their text). The role is the principal's: `GET` returns it only to a caller `PUT` would accept and reads it as nulls for anyone else. `PUT` is the principal's alone (`is_principal_or_self`, 403 otherwise; a header-less caller resolves to the principal as in `chat`) and open while no principal is rostered, so first-run setup can pick a mode. Both work before onboarding — unlike `company-profile`, nothing here needs a profile. |\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). `DELETE /scheduled/{id}` cancels a `pending` row (409 otherwise). Like pause it only stops work, so any signed-in user may — the UI proxy's `x-caller-email` is trusted when the request also carries the `BACKEND_SHARED_SECRET` `x-api-key` — as may a matching `X-Admin-Token` (`SCHEDULED_ADMIN_TOKEN`) or a loopback caller with no token set; otherwise 401 (token set) or 503. Audited as `scheduled_action_cancelled`. |\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`, `GET\\|DELETE /workflows/custom/{name}/targets`, `POST /workflows/runs/{run_id}/decision`, `POST /workflows/runs/{run_id}/rerun`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. `rerun` queues a failed scheduled run (a department check-in, a saved workflow on a cadence) once more, due now (see Scheduler); the principal may, and for a saved workflow the person it delivers to; 409 for a run that did not fail, one started from `/jobs` (\"Start this one again from its page\") or one already queued again. Custom definitions come back with a server-managed `owner_person_id` (the creator — the web caller on `POST`, set on insert only; a client-sent value is ignored), who is asked to approve a workflow's first write to a new target. `GET /workflows/custom/{name}/targets` lists the targets its tool steps may write to without asking and `DELETE …/targets?value=` forgets one. `POST /workflows/{name}/runs` is a 403 (\"Only the principal can run this workflow.\"), audited, before any run row exists, when the workflow is one only the principal may start in the workspace's mode (`weekly_review` always, `morning_brief` in solo) and the caller is not the principal. A request with no `x-caller-email` counts as the principal; with no principal on the roster, no signed-in caller does. This governs starting a run only. A run started by hand (this endpoint, or `run_workflow` / research in chat) records its starter as `owner_person_id` and is theirs alone: `GET /workflows/runs` lists the team's (scheduled, no owner) runs plus the caller's own and the ones waiting on them, and `GET` / `DELETE /workflows/runs/{run_id}` and `POST /workflows/runs/{run_id}/decision` are a 404 for anyone else's, the principal included. A signed-in email that is on nobody's People entry cannot start one (403), and a run whose starter can't be read is refused (503); its steps read and draft documents as the starter only. `POST /workflows/runs/{run_id}/decision` with `{decision: \"approve\"|\"reject\"}` answers a run awaiting a yes/no sign-off from the web app — 403 unless the caller is the person it waits on or the principal, 409 if it isn't awaiting or needs a written reply — through the same `apply_resolution` a chat reply uses. Custom create/update also rejects (422) any action-step tool that does not resolve, and so does `POST /workflows/custom/{name}/activate` when turning a workflow **on** — that click is the approval for a tool workflow chat saved switched off (turning off is never checked). Turning on a workflow with action steps requires the body `{is_active: true, definition}` carrying the definition the user reviewed; if the stored one differs (ignoring `is_active` and timestamps) it returns 409, and the switch itself is a compare-and-set on the validated revision (`dynamic_store.activate_if_unchanged`, keyed on `updated_at`), so a save that lands while the tool check awaits the gateway — even from another process — is a 409 too, so only what was shown gets switched on. `GET /workflows/custom` lists inactive definitions too; `GET /workflows/{name}` 404s for them. The two `tools` endpoints return `{tools: [{name, description, read_only, source}]}` for the advanced editor's tool picker and the review card; `read_only` is true only when the name says it reads (a label, not a control). The run stream adds a `progress` event (`step_id`, `summary`) while an action step uses tools. Each catalog entry (`WorkflowMeta`) carries `is_custom`, `background` (true for the system-run built-ins the UI files under “System”) and `quick` (true for a Quick workflow, one per playbook nothing else follows, named `quick_<playbook>`). 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`, `/skills/{name}/restore` | Skill registry (the UI's **Playbooks**) CRUD and search. `PUT` on a built-in saves a company customization that shadows it; `DELETE` returns `{name, outcome}` — `deleted`, `reverted` (customization removed, built-in back) or `hidden` (built-in hidden for this company); `restore` un-hides; `GET /skills?include_hidden=true` lists hidden built-ins. List and detail carry `used_by` — `[{name, title, is_custom}]` of the workflows that follow the playbook (switched-off custom ones included) (`WorkflowMeta.playbooks` is the other direction). |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. `POST /evals/runs` is a 403 when a workflow scenario names a workflow that only the principal may start in the mode it runs in (the weekly review; the morning brief in solo) and the caller is not the principal — the Jobs page's rule for starting a run; stored results are read under the existing `/evals/runs` rules. |\n| `memories` | `/memories/{decisions,initiatives,advice}`, `GET /memories/facts`, `POST /memories/facts/{fact_id}/{retire,approve,decline}`, `GET /memories/facts/approval`, `PUT /memories/facts/approval/{person_id}`, `GET /memories/people`, `GET /memories/people/{person_id}/conclusions` | Episodic-memory record management; the standing facts the Pulse Corrections tab reads (`{facts: [...], can_retire, retirable_ids, can_review}`; each fact carries `recorded_by_role` / `recorded_by_name`; `?include_inactive=` default true, honoured for the principal only; anyone else gets the active rows plus their own `proposed` ones, with the provenance (`session_id`, `turn_id`, `recorded_by_person_id`, `retired_reason`, and `source_quote` except on their own facts) blanked, never retired, replaced or declined text; `?limit=` 1–500) and their retire (the principal any fact, a teammate only one they recorded that the principal has not approved — else 403; the audit row names the teammate; 404 for an unknown or `profile` row, 409 when no longer active; writes a private `fact_retired` audit row); approve / decline a teammate's `proposed` fact (principal only, else 403; 409 when it is not proposed; private `fact_reviewed` row); and the per-teammate \"needs my approval\" switch (on by default; `GET` lists `[{person_id, full_name, needs_approval}]` for every active team member but the principal, `true` for anyone not yet set; `PUT` takes `{needs_approval}`, 404 for anyone else; both principal only; private `fact_approval_changed` row); plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5) and one person's full conclusion list, paged newest first (`{status, person_id, items, page, size, total, has_more}`; `?page=` ≥1, `?size=` 1–100, default 50; 404 when the person has no peer). Peer memory is each person's own: the overview holds only the caller's entry (none for a caller off the roster; `conclusion_total` counts only theirs), the principal included, and `/conclusions` for anyone but the caller is a 404. |\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/understand`, `/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). `commit` answers 403 when the draft would make a different person the owner and the caller is not the current owner (setup demotes the old principal, and any signed-in user can open it). It also takes an optional `owner_email` — the principal's sign-in email, which the review screen pre-fills from the signed-in user — checked before anything is written (422 if it is malformed, already another person's, or would replace the principal's existing email — setup only fills in a missing one; 403 if the caller is not the owner and it is not the address they signed in with, since the roster is the sign-in allow-list) and saved on the principal's People row, so the owner's chats resolve to them from the first turn. |\n| `workflow_designer` | `POST /workflows/designer/start`, `POST /workflows/designer/edit`, `POST /workflows/designer/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard, and editing a saved workflow by conversation. `/edit` (`{name}`) opens a session on a saved custom workflow with no model call: the stored definition is the starting draft, and every response then carries `editing` (its name) and `original` (the stored definition as the session opened on it); drafts keep that name and its on/off state whatever the model writes (404 for an unknown workflow). The UI saves one with `POST /workflows/custom/{name}/save-edit` (`{session_id, definition}`): the server saves the session's own draft, never a client-sent body, and only when it equals the `definition` the user reviewed (a later message is a 409, so the click saves only what was shown); it re-validates it, keeps the stored on/off state, and writes only if the stored workflow is still the version the conversation opened on — otherwise 409, as it is for a session about another workflow or one with nothing drafted yet. It sits under `/workflows/custom` so anything that limits writes to custom workflows covers it too. The `workflow_designer` agent asks clarifying questions (`phase: \"question\"`, with `hint` and up to four suggested `options`), then returns `phase: \"draft\"` with `draft.definition` (exactly the body `POST /workflows/custom` takes), `summary`, and `assumptions`; every response carries the `transcript`. **Nothing is persisted here** — sessions are in memory, and the UI saves through `POST /workflows/custom`. Errors are fixed strings (422 over the 8,000-char message cap or the transcript cap, 404 for an expired session, 409 while another turn on the same session is still running, 502/504 for model failure or timeout). Mounted ahead of the `workflows` router. |\n| `python_jobs` | `GET /python-jobs/{job_id}/{name}` | A result file a Python job (`run_python_job`) wrote, the principal's alone (403 otherwise), served as a download (`Content-Disposition: attachment`, `Content-Security-Policy: sandbox`, `nosniff`, `Cache-Control: no-store`); 404 for a bad id or name or a file past its 7 days. |\n| `saved_tools` | `GET /saved-tools`, `GET\\|PUT /saved-tools/{name}`, `POST /saved-tools/{name}/rollback` | The scripts the Executive saved as tools (Settings → Advanced → Saved tools), the owner's alone (403 otherwise). The list gives each tool's name, description, on/off, current version, `kind` (`script` or `python`, a kept Python job) and the tools it calls, plus whether `SAVED_TOOLS_ENABLED` is on; the detail adds the script, every version and the last 20 runs. `PUT {enabled?, workflows?, version?}` turns one on or off (off also turns it off for workflows, so turning it back on never re-arms unattended runs), and turns the named `version` — the one the owner looked at, never whatever is current by then — on for workflows (or workflows off); a Python tool never turns on for workflows (409) — turning workflows on lets more run unattended, so it needs a request tied to the owner (signed sign-ins or local login, as Take the lead's switches do; 409 otherwise); `rollback {version}` makes that version the one that runs. Both are audited as `saved_tool_changed`. The Executive saves tools itself through `run_script`; there is no create route. |\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. Its final answer saves the profile and adds people with their emails and a principal, so once there is an owner only they can send it (403, and the session rolls back so the owner can still finish it). `/onboard/start` reads the workspace mode once for the session: solo skips the Team Size, Team Members and Fractional Executives steps. Each status response's `current_step` / `total_steps` count only the steps that session asks, and `optional` says whether the current step can be skipped. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `alerts` (private cards) | `POST /alerts/{id}/ack`, `/reopen`, `/alerts/bulk-ack` | An alert tagged `private:principal` (see Today) is a 404 on ack and reopen for anyone but the principal, and their bulk sweep skips it. A roster-request card (source `roster_request`) is a 409 on `ack` even for the principal — it is answered at `/people/requests/{id}`, since acking would leave the sender waiting with nothing to show it — and, as an exempt source, `bulk-ack` and `reopen` skip it. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived **team members** with an email, offered to the UI's sign-in gate — a contact is never on it, so adding a client to reach them by email no longer lets them sign in. 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. With local login (`make dev` with Google sign-in not set up — the UI then listens on 127.0.0.1 only) the UI signs in without an email, sends no `x-caller-email`, and the backend resolves the caller to the principal, as it does for the CLI. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. `POST /fixtures/reset` leaves no departments, like a new install (`departments_seeded` is always 0). |\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`, `POST /webhook/slack` | Inbound integration callbacks (self-verified). `/webhook/slack` answers 503 unless `SLACK_SIGNING_SECRET` is set. |\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. |\n\n**Take the lead** (`api/routes/take_the_lead.py`): `GET /take-the-lead` returns the As the Executive switch, its six Ask first switches (`{kind, label, hint, on}`, the hint a plain line on what each one catches), the company's rules, whether this server can tie a change to the owner (`available`), and whether the Executive is paused. `PUT /take-the-lead` takes `{enabled?, ask_first?}`, and `POST /take-the-lead/rules` / `DELETE /take-the-lead/rules/{id}` add or remove a company rule (`{kind: person|domain|words|amount, value}`, 422 on a bad one). All four are the principal's alone (403). Anything that lets more happen on its own (turning it on, turning an Ask first off, removing a rule) needs a caller the API can tie to them (`delegation.verified.caller_refusal`, else 409). `GET /today/activity` adds `took_the_lead` rows (what Take the lead did, named, not quoted) and, for the caller alone, `sent_as_you` rows for what Handle it for me sent as them. Under `/delegation`: `PUT /delegation/take-the-lead {enabled}` is Take the lead as you (the owner's only for now; turning it on turns Handle it for me on), and `GET|POST /delegation/take-the-lead/rules` and `DELETE …/rules/{id}` manage the caller's own rules. `HandleItOut` gains `lead` and `lead_available`. A `take_the_lead_action` decision is approved or rejected through the existing `/decisions/{id}/approve|reject`. Training: the response also carries `training` (In training: everything waits unless allowed), `learned` (`{id, label, feature, example, uses, created_at}`: what it was allowed, the edit kept as an example by field) and `suggested` (`{key, label, approvals}`); `PUT` takes `training?` too, and leaving training while on needs the same provable owner as turning it on. `POST /take-the-lead/learned {key}` allows a current suggestion (404 for anything else; provable owner), `DELETE /take-the-lead/learned/{id}` makes it ask first again. `learned` also lists the owner's own Act as me senders (`feature` `act_as_me`), never anyone else's, and Remove works on those too. On a `take_the_lead_action` card, `POST /decisions/{id}/approve` takes `edits.input` (the card's editable fields, 422 for any other; the principal's alone, 403 for an area approver) and `edits.allow: true` (a training card only, 422 otherwise; the principal from a provable request, 403 otherwise), finishing `approved_with_edit` when a field changed.","mermaid": null,- "generated_at": "2026-10-14T06:00:00Z"+ "generated_at": "2026-10-14T06:43:22Z"}diff --git a/packages/core/openexecutive/architecture/prebuilt/attunement.json b/packages/core/openexecutive/architecture/prebuilt/attunement.jsonindex 4e69ae45..55b76ce6 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. The short filename note an email or upload leaves in the speaker text is written `(Attached files: …)` precisely so it does not trip this skip — that turn carries no document text.\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 — the turn's speaker text (`memory_text` when given: an email's new text without its quoted chain, a briefing handoff's short line), never the framed prompt (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 (in solo mode only the undated ones — see below); 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### Assigning a task\n\nThe pass only sees what its English keyword prefilter and its model catch. Assigning is the deterministic path beside it: \"Ask Ben to send me the Q3 numbers by Friday\" in chat, or **Assign a task** on a person's page. Both call `open_loops.assign_open_loop`, which opens an ordinary loop, so everything below — chasing, `/today`, reflection, the Due soon card, closing — treats it exactly like an extracted one.\n\n- **Who.** The principal or any active team member may assign a task to anyone on the team, themselves included. A contact is never an owner (contacts are never chased), nor is an archived person. The stored text has the pass's shape: \"Sara Kim asked Ben Ortiz for: …\", or \"Ben Ortiz committed to: …\" when it is their own.\n- **Chat tool — `assign_open_loop`** (`person_id`, `task`, optional `due_date`). Allowed only for the principal on a verified surface (web chat, their own Slack or Discord), or a rostered teammate on one (`people_tools.teammate_on_verified_surface`, shared with teammate facts). Never allowed for an email (even from the principal's own address), a turn private to the principal, or an unattended run; it is also in `UNATTENDED_WITHHELD_TOOLS` and `PRIVATE_TURN_WITHHELD_TOOLS`. `task` must appear **verbatim in what the speaker typed this turn**, because it is re-injected into the nudge intent, the same rule the pass applies. Adapter tag blocks don't count as their words, and a turn carrying an attachment is refused. The check is language-neutral, so a task stated in French is assigned though the prefilter would miss it. At most 5 per turn. To a teammate, a contact's id reads exactly like an id no one has.\n- **One ask, one loop.** The turn's assigned owners are remembered under its audit session and turn ids. That turn's extraction pass drops a new loop for those owners (`assigned_this_turn`) but still applies closes.\n- **Route.** `POST /people/{id}/open-loops` `{task, due_date?}` returns 201 with the loop. The caller must be an active team member (403 otherwise), and a contact's page reads as 404 to anyone but the principal. Refusals are 404/409 (archived, contact, at the per-person cap, duplicate, feature off) or 422 (empty task). Listing is unchanged: a teammate who assigns Ben a task does not see Ben's other loops.\n- **Due date.** A local date becomes 17:00 in the user's timezone, clamped to 60 days, defaulting to `ATTUNEMENT_LOOP_DEFAULT_DUE_DAYS`. Nobody is messaged at assignment; the owner is chased once it is due, like any loop. Each assignment is audited (`loop_assigned`). Loop text on either path has `<`, `>` and `\"` swapped for look-alikes when stored, so it cannot close the quote in the nudge intent or the runner's `<scheduled_intent>` block.\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- in solo mode, the morning brief and the `/today` header get a **DUE THIS WEEK** block of the principal's own loops that are overdue or due within 7 days (`open_loops.principal_due_soon`), and the Briefing shows them in a **Due soon** card.\n\n### Solo mode: the principal's dated commitments\n\nIn a team install the principal's own commitments are dropped (`principal_commitment`). In solo mode — one person using Open Executive for themselves — nobody else will chase what they promise, so the pass keeps the ones that say when they are due — when the principal said them on a surface that verified it is them (`people_tools.is_principal_on_verified_surface`, computed by the Executive and passed as `principal_verified`; an email's sender is its From header, so a spoofed promise is dropped as `principal_commitment_unverified`). The turn's pinned mode travels with the pass (`schedule_open_loop_pass(..., workspace_mode=…)`, read from the workspace when absent). Solo swaps the extraction prompt for `_SYSTEM_SOLO` (a separate constant; the team `_SYSTEM` is byte-identical and pinned by a test), which allows a dated commitment of the principal's own and requires its quote to carry the date words. In code, a principal commitment is opened only when the model's `due_date` parses as a real `YYYY-MM-DD` (`_stated_due_date` — never `_resolve_due`'s 2-day default) **and** the quote matches `_STATED_DUE_HINT`, which favours precision: unambiguous words count on their own (a full weekday, \"tomorrow\", \"next week\", \"end of Q4\", \"in 3 days\"), as do explicit dates (\"Oct 3\", \"3 October\", \"2026-10-03\", \"10/03\"), while a short or ambiguous token (\"may\", \"sat\", \"wed\", \"q1\", \"the 14th\", \"10/3\") counts only after a due word (by / on / before / until / due) — so \"I may send it\", \"the 1st draft\" and \"a 50/50 call\" never read as dates; anything else is dropped as `principal_commitment_undated` — an undated \"I'll look into pricing\" is an initiative, not a loop. The loop is owned by the principal, so the nudge engine chases it through their channel once overdue; when no channel reaches them, the brief's DUE THIS WEEK block and the Briefing's **Due soon** card still show it. Asks and contacts' commitments behave exactly as in team mode.\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\nAssigning (above) is open to anyone on the team; seeing and closing are not. `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 rostered `to` address gets a row, its cc's and any other recipients 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, or saying someone else's is done, credits nobody); the approval a stalled-run nudge chased is resolved (`resumer.apply_resolution`), credited to the person who resolved it; the initiative a check-in was about gets a real change (a new status or summary, not a re-mention), credited only to the person who made it — an edit through `PATCH /memories/initiatives/{id}`, which carries no caller identity, credits nobody; 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, found stale or expires unread: 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. A later `acted` or `void` overrides an earlier `ignored` — the thing can get done days after the sweep, and that verdict is the truer one; a late reply does not. 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 (by send time) 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### Working style — how each person likes replies\n\n`attunement.style` keeps at most four short style rules per person (\"lead with the recommendation, then the numbers\") and pins them into **that person's own turns** as a `<working_style>` block in the user turn — right after `<current_speaker>`, never a cached system block, and only for a resolved, rostered, non-archived speaker. The block says the current request always wins and that the rules never authorize an action.\n\n- **Evidence.** A background pass (one forced `record_working_style` call) reads the person's last 40 attributed messages, each paired with the reply that answered it and the reaction **they** gave it: 👍/👎 they left themselves (`chat_messages.feedback_by_person_id`, so the principal rating someone's session is not that person's reaction), any note, and replies stopped mid-stream. A conversation that read the person's own mail (Act as me marks it `sessions.mail_private`) is left out: its replies quote other people's mail. Every rule must cite that evidence — basis `feedback` needs a cited reply carrying a reaction; basis `stated` needs the person's request quoted verbatim from a cited message. Honcho is not read or written, so this works the same with `HONCHO_ENABLED=false`.\n- **Style only.** Rules are validated in code before they are stored or shown: one line of Latin-script text (so look-alike letters cannot hide a denied word), 8–160 characters; a deny-list that rejects action words (send, approve, pay, schedule…), nudges to act without checking (confirm, check, verify, pause, proceed, go ahead, judgment, instinct, trust, decide…), talk about instructions or tools, URLs, handles, amounts, markup, snake_case identifiers and roster names; and an allowlist — the rule must name some aspect of how a reply reads (length, format, tone, detail, what to lead with…). Edits typed on the person page go through the same checks, and every stored rule is checked again each time the block is rendered and when the lock is toggled, so a rule saved under an older, weaker check never reaches a turn. The block is scrubbed with the shared `utils.prompt_blocks.scrub_block_line`, which also backs `<peer_memory>`.\n- **Pacing.** The Executive schedules the pass after each attributed turn; it runs once `ATTUNEMENT_STYLE_TRIGGER_TURNS` (10) new messages have arrived since the last pass, or right after the person leaves a 👎 on a reply to their own message (`POST /sessions/{sid}/messages/{mid}/feedback`; someone else's rating triggers nothing), with at least 5 messages of history. At most once per `ATTUNEMENT_STYLE_MIN_INTERVAL_HOURS` (2) and `ATTUNEMENT_STYLE_MAX_PER_DAY` (4) times a day per person, and from the shared `ATTUNEMENT_MAX_CALLS_PER_DAY` budget. The slot is claimed with one conditional UPDATE (never under a one-minute interval, and `MAX_PER_DAY=0` means no passes), so concurrent triggers run one pass. The model returns the learned rules in full: a deliberate empty list drops them (newer reactions contradict them), while a malformed call or a list whose every rule fails validation changes nothing.\n- **People stay in charge.** `GET/PUT/DELETE /people/{id}/attunement` (the principal or that person) back a \"How I work with them\" card with edit, lock and reset. Rules typed there are always kept — a pass only fills the remaining slots — and toggling the lock alone (`PUT` without `rules`) keeps the learned rules and their provenance. A locked profile is never rewritten by a pass, a pass never overwrites an edit made while it ran, and an archived person's routes return 404. Every change is kept in `attunement_profile_history`; archiving a person drops both.\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`, `ATTUNEMENT_STYLE_ENABLED`, `ATTUNEMENT_STYLE_TRIGGER_TURNS`, `ATTUNEMENT_STYLE_MIN_INTERVAL_HOURS`, `ATTUNEMENT_STYLE_MAX_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`, `proactive_outcomes`, `attunement_profiles` and `attunement_profile_history` 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.",+ "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. The short filename note an email or upload leaves in the speaker text is written `(Attached files: …)` precisely so it does not trip this skip — that turn carries no document text.\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 — the turn's speaker text (`memory_text` when given: an email's new text without its quoted chain, a briefing handoff's short line), never the framed prompt (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 (in solo mode only the undated ones — see below); 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### Assigning a task\n\nThe pass only sees what its English keyword prefilter and its model catch. Assigning is the deterministic path beside it: \"Ask Ben to send me the Q3 numbers by Friday\" in chat, or **Assign a task** on a person's page. Both call `open_loops.assign_open_loop`, which opens an ordinary loop, so everything below — chasing, `/today`, reflection, the Due soon card, closing — treats it exactly like an extracted one.\n\n- **Who.** The principal or any active team member may assign a task to anyone on the team, themselves included. A contact is never an owner (contacts are never chased), nor is an archived person. The stored text has the pass's shape: \"Sara Kim asked Ben Ortiz for: …\", or \"Ben Ortiz committed to: …\" when it is their own.\n- **Chat tool — `assign_open_loop`** (`person_id`, `task`, optional `due_date`). Allowed only for the principal on a verified surface (web chat, their own Slack or Discord), or a rostered teammate on one (`people_tools.teammate_on_verified_surface`, shared with teammate facts). Never allowed for an email (even from the principal's own address), a turn private to the principal, or an unattended run; it is also in `UNATTENDED_WITHHELD_TOOLS` and `PRIVATE_TURN_WITHHELD_TOOLS`. `task` must appear **verbatim in what the speaker typed this turn**, because it is re-injected into the nudge intent, the same rule the pass applies. Adapter tag blocks don't count as their words, and a turn carrying an attachment is refused. The check is language-neutral, so a task stated in French is assigned though the prefilter would miss it. At most 5 per turn. To a teammate, a contact's id reads exactly like an id no one has.\n- **One ask, one loop.** The turn's assigned owners are remembered under its audit session and turn ids. That turn's extraction pass drops a new loop for those owners (`assigned_this_turn`) but still applies closes.\n- **Route.** `POST /people/{id}/open-loops` `{task, due_date?}` returns 201 with the loop. The caller must be an active team member (403 otherwise), and a contact's page reads as 404 to anyone but the principal. Refusals are 404/409 (archived, contact, at the per-person cap, duplicate, feature off) or 422 (empty task). Listing is unchanged: a teammate who assigns Ben a task does not see Ben's other loops.\n- **The owner is told.** When someone assigns a task to somebody else, the owner gets one notice (`attunement.assignment_notice.notify_assignee`): fixed text, never a model's — \"Pat asked you to take this on: \\\"send the vendor quote\\\". It's due Friday 16 October. Reply here when it's done, or if you can't do it.\" It goes the way the reminders do (`scheduler.runner.deliver_to_person`: their own Slack or Discord DM, private Telegram chat, or email), tagged as proactive source `task_assigned` with the loop's `nudge:commitment:<id>` ref, so their notification settings apply on every channel (`people.notifications.hold_for`: quiet hours or \"In my briefs\" store it in `held_messages` for later) and their own \"done\" credits it in the outcome ledger. A self-assigned task sends nothing. The chat tool's result and the route's response carry `notified` (`sent` with the channel, `held`, `not_reached`, `skipped`), so the Executive and the People form say whether it reached them. The task is quoted inert: the stored loop's defang (`\"` `<` `>`) and a code span, since a teammate typed it and no model sits between, so it can't read as the Executive's own words or render as a link on any channel. A teammate who assigns it sees no channel, and `later` in place of `held` (why it waits is the owner's own setting); only the principal sees both. Audited as `task_assignment_notice`, private to the owner. Off with `ATTUNEMENT_ASSIGN_NOTIFY_ENABLED=false`. Chasing stays the nudge engine's: one notice per loop, never repeated.\n- **Due date.** A local date becomes 17:00 in the user's timezone, clamped to 60 days, defaulting to `ATTUNEMENT_LOOP_DEFAULT_DUE_DAYS`. Beyond that one notice, the owner is chased once the loop is due, like any loop. Each assignment is audited (`loop_assigned`). Loop text on either path has `<`, `>` and `\"` swapped for look-alikes when stored, so it cannot close the quote in the nudge intent or the runner's `<scheduled_intent>` block.\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- in solo mode, the morning brief and the `/today` header get a **DUE THIS WEEK** block of the principal's own loops that are overdue or due within 7 days (`open_loops.principal_due_soon`), and the Briefing shows them in a **Due soon** card.\n\n### Solo mode: the principal's dated commitments\n\nIn a team install the principal's own commitments are dropped (`principal_commitment`). In solo mode — one person using Open Executive for themselves — nobody else will chase what they promise, so the pass keeps the ones that say when they are due — when the principal said them on a surface that verified it is them (`people_tools.is_principal_on_verified_surface`, computed by the Executive and passed as `principal_verified`; an email's sender is its From header, so a spoofed promise is dropped as `principal_commitment_unverified`). The turn's pinned mode travels with the pass (`schedule_open_loop_pass(..., workspace_mode=…)`, read from the workspace when absent). Solo swaps the extraction prompt for `_SYSTEM_SOLO` (a separate constant; the team `_SYSTEM` is byte-identical and pinned by a test), which allows a dated commitment of the principal's own and requires its quote to carry the date words. In code, a principal commitment is opened only when the model's `due_date` parses as a real `YYYY-MM-DD` (`_stated_due_date` — never `_resolve_due`'s 2-day default) **and** the quote matches `_STATED_DUE_HINT`, which favours precision: unambiguous words count on their own (a full weekday, \"tomorrow\", \"next week\", \"end of Q4\", \"in 3 days\"), as do explicit dates (\"Oct 3\", \"3 October\", \"2026-10-03\", \"10/03\"), while a short or ambiguous token (\"may\", \"sat\", \"wed\", \"q1\", \"the 14th\", \"10/3\") counts only after a due word (by / on / before / until / due) — so \"I may send it\", \"the 1st draft\" and \"a 50/50 call\" never read as dates; anything else is dropped as `principal_commitment_undated` — an undated \"I'll look into pricing\" is an initiative, not a loop. The loop is owned by the principal, so the nudge engine chases it through their channel once overdue; when no channel reaches them, the brief's DUE THIS WEEK block and the Briefing's **Due soon** card still show it. Asks and contacts' commitments behave exactly as in team mode.\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\nAssigning (above) is open to anyone on the team; seeing and closing are not. `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 rostered `to` address gets a row, its cc's and any other recipients 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, or saying someone else's is done, credits nobody); the approval a stalled-run nudge chased is resolved (`resumer.apply_resolution`), credited to the person who resolved it; the initiative a check-in was about gets a real change (a new status or summary, not a re-mention), credited only to the person who made it — an edit through `PATCH /memories/initiatives/{id}`, which carries no caller identity, credits nobody; 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, found stale or expires unread: 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. A later `acted` or `void` overrides an earlier `ignored` — the thing can get done days after the sweep, and that verdict is the truer one; a late reply does not. 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 (by send time) 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### Working style — how each person likes replies\n\n`attunement.style` keeps at most four short style rules per person (\"lead with the recommendation, then the numbers\") and pins them into **that person's own turns** as a `<working_style>` block in the user turn — right after `<current_speaker>`, never a cached system block, and only for a resolved, rostered, non-archived speaker. The block says the current request always wins and that the rules never authorize an action.\n\n- **Evidence.** A background pass (one forced `record_working_style` call) reads the person's last 40 attributed messages, each paired with the reply that answered it and the reaction **they** gave it: 👍/👎 they left themselves (`chat_messages.feedback_by_person_id`, so the principal rating someone's session is not that person's reaction), any note, and replies stopped mid-stream. A conversation that read the person's own mail (Act as me marks it `sessions.mail_private`) is left out: its replies quote other people's mail. Every rule must cite that evidence — basis `feedback` needs a cited reply carrying a reaction; basis `stated` needs the person's request quoted verbatim from a cited message. Honcho is not read or written, so this works the same with `HONCHO_ENABLED=false`.\n- **Style only.** Rules are validated in code before they are stored or shown: one line of Latin-script text (so look-alike letters cannot hide a denied word), 8–160 characters; a deny-list that rejects action words (send, approve, pay, schedule…), nudges to act without checking (confirm, check, verify, pause, proceed, go ahead, judgment, instinct, trust, decide…), talk about instructions or tools, URLs, handles, amounts, markup, snake_case identifiers and roster names; and an allowlist — the rule must name some aspect of how a reply reads (length, format, tone, detail, what to lead with…). Edits typed on the person page go through the same checks, and every stored rule is checked again each time the block is rendered and when the lock is toggled, so a rule saved under an older, weaker check never reaches a turn. The block is scrubbed with the shared `utils.prompt_blocks.scrub_block_line`, which also backs `<peer_memory>`.\n- **Pacing.** The Executive schedules the pass after each attributed turn; it runs once `ATTUNEMENT_STYLE_TRIGGER_TURNS` (10) new messages have arrived since the last pass, or right after the person leaves a 👎 on a reply to their own message (`POST /sessions/{sid}/messages/{mid}/feedback`; someone else's rating triggers nothing), with at least 5 messages of history. At most once per `ATTUNEMENT_STYLE_MIN_INTERVAL_HOURS` (2) and `ATTUNEMENT_STYLE_MAX_PER_DAY` (4) times a day per person, and from the shared `ATTUNEMENT_MAX_CALLS_PER_DAY` budget. The slot is claimed with one conditional UPDATE (never under a one-minute interval, and `MAX_PER_DAY=0` means no passes), so concurrent triggers run one pass. The model returns the learned rules in full: a deliberate empty list drops them (newer reactions contradict them), while a malformed call or a list whose every rule fails validation changes nothing.\n- **People stay in charge.** `GET/PUT/DELETE /people/{id}/attunement` (the principal or that person) back a \"How I work with them\" card with edit, lock and reset. Rules typed there are always kept — a pass only fills the remaining slots — and toggling the lock alone (`PUT` without `rules`) keeps the learned rules and their provenance. A locked profile is never rewritten by a pass, a pass never overwrites an edit made while it ran, and an archived person's routes return 404. Every change is kept in `attunement_profile_history`; archiving a person drops both.\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`, `ATTUNEMENT_STYLE_ENABLED`, `ATTUNEMENT_STYLE_TRIGGER_TURNS`, `ATTUNEMENT_STYLE_MIN_INTERVAL_HOURS`, `ATTUNEMENT_STYLE_MAX_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`, `proactive_outcomes`, `attunement_profiles` and `attunement_profile_history` 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 Due[\"Solo: brief DUE THIS WEEK<br/>+ Briefing Due soon\"]\n Close[\"close_open_loop · Mark done<br/>archive · TTL expiry\"]\n Assign[\"assign_open_loop · Assign a task<br/>(verified team speaker, verbatim task)\"]\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 Loops -- \"principal's, due ≤7d\" --> Due\n Close --> Loops\n Resolve --> Assign\n Assign -- \"open\" --> 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 Due compute\n class Close compute\n class Assign compute",- "generated_at": "2026-10-01T21:00:00Z"+ "generated_at": "2026-10-14T05:32:14Z"}diff --git a/packages/core/openexecutive/architecture/prebuilt/scheduler.json b/packages/core/openexecutive/architecture/prebuilt/scheduler.jsonindex dddd1886..71de6fc3 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. Each due row runs in its own task, started with no audit scope (`audit.context.unscoped_audit_rows`): a scheduled action is unattended and never part of the turn that scheduled it, so its audit rows follow the ordinary rule. Polls are gated on an active company profile via `_company_profile_active()`; before onboarding, due rows stay `pending`.\n\n### Operator pause\n\nA global pause switch (`openexecutive.scheduler.pause`, one row in the `executive_control` table) stops everything the Executive starts on its own. It is the first check of every scheduler tick: while paused the tick does nothing — no alert/watchlist sweep, no claim — so due rows stay `pending` and fire on the first tick after resume. Actions already claimed when the pause lands run to completion; pausing holds work, it never cancels it. The same check gates the Gmail poller (the inbox is left unread) and the workflow resumer (no `wait_for_human` timeouts or resumes, and `apply_resolution` records a reply without kicking the run). Inbound conversations — web chat, Slack, Discord, Telegram, Google Chat — are deliberately not gated. The switch is set from the sidebar, the paused banner or Settings in the UI, or via `POST /executive/pause` / `POST /executive/resume`; each flip writes an `executive_paused` / `executive_resumed` audit row. Any signed-in caller may pause (it only holds work); resuming releases every held action at once, so it is the principal's alone (open only while no principal is on the roster). The state persists across restarts (boot logs a warning while paused) and across client-slot switches. `is_paused()` is read-only: a DB file or table that does not exist yet reads as \"running\", but a read error on an existing DB reads as \"paused\" — the brake fails closed, so a storage fault holds work rather than silently releasing it while the UI still shows \"paused\" (the UI shows \"status unknown\" when it cannot read the state).\n\n### Liveness heartbeat\n\nEvery tick ends by recording when it finished and what it did — `ran`, `paused`, `waiting_for_company`, `rotating`, or `failed` when the tick raised — and `run_scheduler` notes when it started. `scheduler_heartbeat()` returns both; they live in process memory, not the database. Settings → Setup status (`GET /setup/status`) reads them: no start means the task isn't running; no tick five minutes after starting, or none for three poll intervals (at least 90 s), means the loop has stopped; `failed` and `waiting_for_company` get their own light. Liveness is judged before the pause switch, because a paused scheduler still ticks: one that has stopped shows as stopped, where the Resume button wouldn't help. A restart clears the previous run's last tick. Due actions run as their own tasks, so a slow brief never ages the heartbeat.\n\n### Cadence DSL\n\n`openexecutive.departments.cadence` supports, all in UTC for department and workflow cadences:\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\n`PATCH /departments/{slug}` rejects a spec that does not parse (bad format, unknown DOW, out-of-range time) with a 422 naming the valid formats, so a typo is caught at save time instead of silently never firing. An empty spec means no cadence (the department page's **Off**). A new department starts weekly, `weekly@mon@09:00`. Changing a department's `check_in` through that route re-times it at once: `cadence.reschedule_check_in()` cancels its pending `dept_cadence` row and queues the next occurrence of the new spec (nothing when it is off or in solo); a check-in already running finishes, and its chain adds nothing because the new row is pending.\n\nWhen a department cadence is due, the runner invokes the `department_check_in` workflow and chains the following occurrence via `cadence.enqueue_next()`. The fire is not passed through the authority gate: the check-in sends nothing (it grades Goals, writes one audit row and a Honcho note), and every action it proposes carries its own `gate_action` verdict in the report. Before creating a run the runner applies a skip rule (`department_check_in.needs_check_in`): the check-in is skipped when the department has no specialist agent, has no Goals, or nothing is new since its Goals were last reviewed — no decision or audit row tagged to the department (the check-in's own review row aside) since the oldest Goal's `last_reviewed_at`, and no Goal edited after it was graded. A Goal never reviewed always runs it. A skip leaves no run in the activity rail, is recorded as `cancelled` with its reason (`skipped: …` in `last_error`) rather than `done` — a done cadence row means \"the check-in ran\" to the nudge engine — and still chains the next occurrence; so does a check-in that fails once its retries are spent, so one broken department does not fall out of its cycle. That final failure also files one Home card, \"*Finance* check-in didn't finish\" (`workflows.failure_alerts`, source `workflow_failed`, tagged `failed_run:<run id>`; repeats of the same check-in coalesce into it), because nobody watches a scheduled run; a scheduled saved workflow (`dynamic_workflow`) that fails files the same card, routed to the person it delivers to. The card's **Run again** (`POST /workflows/runs/{run_id}/rerun`) queues the same action, due now, with `scope_key` `rerun:<run id>`: it skips the skip rule and does not chain another occurrence, and re-timing the check-in leaves it queued (the dept chain is idempotent anyway; a saved workflow's `schedule_dynamic_workflow_cadence` is skipped). Chaining is idempotent: while a next occurrence for the department is already pending nothing is added, so a row that chained and then failed to record its outcome never leaves two. Seeded departments start with no Goals, so their weekly check-ins cost nothing until someone adds one. Deleting a department cancels its pending `dept_cadence` rows, and `cancel_orphaned_cadences()` sweeps orphans on boot.\n\nIn **solo mode** (one person using Open Executive just for themselves; see Org) there are no department check-ins: `bootstrap_cadences()` is a no-op, switching to solo cancels every pending `dept_cadence` row, a row that was already pending is marked `cancelled` by the runner without running and without chaining — ahead of the authority gate, so a `propose_only` department cannot turn it into an approval card, and cancelled rather than done because the nudge engine reads a done check-in as a recent department pulse — and a check-in already running across the switch finishes without `enqueue_next` scheduling another. Switching back to team re-bootstraps them. Solo has one kind of its own, the **weekly review** (`principal_weekly_review`, below): switching to solo seeds it (`seed_weekly_review`), switching to team cancels its pending row (`cancel_weekly_reviews`), and one that fires while the stored mode is team is marked `cancelled` without running or chaining. That check reads the mode strictly (`workspace_settings.read_stored_mode`) and fails open: a mode that can't be read (a locked database) is not taken for team, so one bad read neither retires the review nor breaks its chain — the next run checks again.\n\nThe parser also takes a zone: `_parse_cadence_spec(spec, after, tz=UTC)` builds the wall-clock time in `tz` and only then converts to UTC, so a local schedule stays at the same local time across daylight-saving changes (a time the spring-forward gap skips fires once, just after the jump; a time the fall-back repeats fires at its first occurrence).\n\n### The principal's rhythm\n\nThe morning brief (`principal_brief_morning`, 08:00), end-of-day digest (`principal_brief_eod`, 18:00) and reflection (`executive_reflection`, 07:30) are seeded once per database by `seed_principal_briefs()` and each chains its next occurrence when it fires. In a solo workspace it also seeds the **weekly review** (`principal_weekly_review`, Friday 16:00 local by default), which runs the `weekly_review` workflow and is delivered like the briefs; its `PRINCIPAL_WEEKLY_REVIEW_TIME` takes a whole weekly spec (`weekly@fri@16:00`), read as UTC when valid, like the pinned times below, and it chains only while the workspace is still solo — and never when a weekly row is already pending, so a switch to solo while a review finishes cannot leave two. Their default times are local to the user's zone — `memory.workspace_settings.get_user_timezone()`: the zone set through `PUT /workspace`, else `USER_TIMEZONE`, else UTC — computed with the cadence parser above. An operator who pinned a valid `HH:MM` in `PRINCIPAL_BRIEF_MORNING_TIME` / `PRINCIPAL_BRIEF_EOD_TIME` / `PRINCIPAL_REFLECTION_TIME` keeps that time read as UTC, as before zones existed, so a pinned time never moves; a malformed value is logged and treated as unset. An install that set `USER_TIMEZONE` but pinned nothing does move to that zone, from each kind's first fire after the upgrade (a row seeded before it keeps its old UTC time once). When the zone in effect changes, `reschedule_principal_rhythm()` re-times each kind's pending, not-yet-due row **in place** — it only updates `run_at` (guarded on the row being unchanged since it was read), never inserts or cancels, so it cannot race a chain into a duplicate. The new time is the next occurrence in the new zone after `max(now, last fired run + 12h)`, so a kind never runs twice within 12 hours; and if that is more than 12 hours later than the row's current time — moving would skip a day, as when someone switches to Europe/London at 07:59 UTC with the 08:00 UTC brief a minute away — the row keeps its time once. A kind with no such row is left alone: a row that is running, one between being marked done and its chain insert, or a due row held by a pause or a missing company profile. Its chain times the next one in the new zone, and the chain itself starts from `max(now, fired run + 12h)`, so a zone change while a brief runs cannot put a second brief a few hours after it. The weekly review follows the same rules with a 3.5-day gap (`_min_gap`) in place of 12 hours, so a zone change can neither run it twice in a week nor skip one.\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 — with one exception, the **held-writes** pause: when an action step holds a write to a new target, the runner checkpoints the run (`checkpoint_gate`, the owner is DMed), still marks the row done and re-chains the cadence, and stamps `deliver_to_person_id` on the resume payload so the resumer DMs the artifact to the cadence recipient once the owner answers (or the 48 h timeout skips the held writes). Any other gate is still refused at execution: 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### Department authority & cancelling\n\nA department-scoped row passes the authority gate (`departments.authority.gate_action`, see Org) before it is dispatched: `auto_execute` dispatches; `propose_only` raises an approval card and marks the row done without dispatching (deferred to the approver's next availability window when they are outside it); `escalate` raises an urgent `[ESCALATION]` card (severity high) straight away — never deferred — and likewise does not dispatch, because approving the card is what sends it. As that card is the action's only trace it always lands: unrouted when there is no approver and no principal, and deduped on the whole action (kind, channel, recipient and intent) rather than the summary's first 60 characters, so another escalation sharing an opening — or the same text for someone else — cannot swallow it. An identical escalation folds into a still-open card and gets a fresh one once that card was handled, and a card that cannot be written retries the row with backoff and, once the retries are spent, marks it `failed` — never `done`. (It used to raise the card *and* dispatch.) The runner records which action each card holds (`alert_held_actions`, server-side only, never a tag a model could write): approving one (`POST /alerts/{id}/approve`) queues a copy of that exact action with no department, so it goes out on the next tick without meeting the gate again. A `dept_cadence` row is not gated at all — gating it turned every check-in on a propose-only department (all eight seeded ones) into a one-shot card, and the row never chained its next occurrence. Nudge-engine rows carry no department and bypass the gate.\n\nA `pending` row can be cancelled with `DELETE /scheduled/{id}` — the Pulse page's Cancel; the update only moves a row that is still `pending`, so one the scheduler has just claimed is never overwritten. Cancelling only stops work, so, like pause, any signed-in user may: the route accepts a signed-in caller through the UI proxy (its `x-caller-email`, trusted only alongside the `BACKEND_SHARED_SECRET` `x-api-key`), a matching `X-Admin-Token` (`SCHEDULED_ADMIN_TOKEN`, for scripts), or a loopback caller when no token is set — otherwise 401 (token set) or 503. Each cancel is audited as `scheduled_action_cancelled` with who did it.\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\nAn idle initiative is chased with its department's head; with no head to resolve — no department (what the episodic extractor stores), an unknown department, or no head set — the principal owns it. That source used to skip every initiative without a head, so in practice it never fired. The principal gets self-addressed wording (\"<title>\" has not moved since <date> — still active, done, or dropped?). If channel routing cannot reach the principal (no channel configured, or unreachable beyond `NUDGE_MAX_DEFER_DAYS`), the nudge becomes an unrouted Briefing card instead, keyed on the initiative and the ISO week: at most one card per initiative per week, and while one is still unread the scan leaves it alone rather than refreshing it every 15 minutes. The emitted nudge still carries no department, and the usual caps and cooldowns apply. A department-tagged initiative is still skipped while its department's check-in actually ran inside the idle window; a skipped check-in does not count.\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`. The same throttled call also deletes Always in the loop notes past their expiry (`memory.history.sweep_expired`; reads already skip them, and it never raises). Each tick also calls `_maybe_remind_notes` → `memory.history_reminders.maybe_remind` (its own 15-minute throttle, 09:00–18:00 local, one task at a time): a person whose notes say something they promised by email is due today gets one message saying how many, through `deliver_to_person` — the brief's own channel order for any Person, never a shared channel (`delivery_order` now skips a Telegram group id, for the briefs too), with the senders' audit rows private to that person. A hook rather than a `scheduled_actions` row, which `/scheduled` would show to everyone (see Memory).\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\nThe /today **\"What's going on\" header** is kept current from the tick too, so it is fresh before anyone opens the page. `_maybe_refresh_narrative` is a throttled call inside the loop, like the alert sweep — no `scheduled_actions` row. It runs after the pause, company-profile and rotation gates, every `BRIEFING_NARRATIVE_REFRESH_MINUTES` (10; 0 turns it off) and only between `BRIEFING_NARRATIVE_REFRESH_START_HOUR` and `_END_HOUR` (06–22) in the user's zone. It starts `today.refresh_principal_narrative` as its own task, so a slow model call never holds the tick, and never starts a second while one runs. That refreshes the cached calendar read (`live_signals.refresh_calendar`, at most once per 15 minutes) and rewrites the principal's header only when its key moved — new mail, a held reply, a proposal, the hour — with the route's own per-scope lock, so a page view and the tick never write the same header twice (see Today).\n\nAct as me's **reminders** are loop-level too: `_maybe_send_reminders` starts `delegation.reminders.maybe_send` at most once a minute, which claims each due `delegation_reminders` row once (due times are stored in UTC, so they compare in order) (compare-and-set on `claimed_at`) and sends its stored text, prefixed \"Reminder you set on <date>:\", to the person who set it alone through `deliver_to_person`. No model and no tool run; a reminder missed by more than two days is dropped rather than sent late, and one due in the person's quiet hours or leave waits, unclaimed, until they end; audit rows are private to the person. They are not `scheduled_actions` rows for the same reason as the scan below: that list is everyone's, and its rows run an Executive turn when they fire.\n\n**Held messages** are loop-level as well: `_maybe_release_held` starts `people.held_messages.maybe_release` at most once a minute, which sends each person whatever is due to them — messages held for their quiet hours once those end, and brief-held messages made due when the briefs run — as one *While you were away* message through `deliver_to_person`, claims each row first so a brief can't send it too, marks them sent only once that went, postpones a person back in quiet hours, on leave or outside their windows to when that ends, backs off 2, 4, 8 … minutes (at most an hour) after any other failure, and audits every drop (too old, over the cap) privately as a count, and writes audit rows private to the person. The principal-brief handler appends the principal's brief-held messages to the morning brief or end-of-day digest it delivers (`_with_held_messages`; the stored run artifact is unchanged), claims them, marks them sent only when the brief went (otherwise frees the claim), then makes everyone else's due (`_release_others_digests`). The `proactive_nudge` re-check calls `prefer_channel_for` / `next_available_window` with `quiet_hours=True` (urgent for a `nudge:stalled:` scope key), so a nudge due in the person's quiet hours is deferred to their end like one outside an availability window. A dispatch whose message was held is audited `held`, not `delivered`. See Org for the notification settings.\n\nAct as me's **inbox watcher** is loop-level the same way: `_maybe_scan_inbox`, after the same gates, starts the due scans (`delegation.inbox.maybe_scan`) as one task and never a second while one runs. A person is due every `DELEGATION_INBOX_POLL_MINUTES` (default 5) once their **Draft replies to my inbox** switch is on, unless a Gmail failure set a back-off; nobody is scanned while a client slot is active. It is deliberately not a `scheduled_actions` row: those are listed on `/scheduled` for everyone and anyone may cancel them, and a scan reads the owner's own mail. Every row a scan writes is private to the principal (see Act as Me).\n\n### Principal briefs\n\nThe `principal_brief_morning` / `principal_brief_eod` / `principal_weekly_review` rows (and the client-rotation digest) are delivered by `_deliver_to_principal`, not through a row channel. The principal's `preferred_channel` (`slack` / `discord` / `telegram` / `email` / `any`) is tried first, then the other chat channels they have an id for (Slack → Discord → Telegram). Email goes through the active MCP gateway: first when the preference is `email`, and otherwise last, as the backup after every chat channel. Before planning, the delivery asks the gateway supervisor for a start if the gateway is down (`runner.ensure_email_ready` → `mcp_gateway.ensure_active_gateway`, the lazy re-check), and a row action resolves the gateway at execution time rather than from what boot had, so a gateway that failed at boot and came up on a retry carries the brief. The outcome names what happened: `gateway_down` when email is set up but the gateway is not running (the Executive's fault, with the start failure, never `no_channel`, which blamed the owner's setup), and a `send_failed` detail that quotes each channel's own error (`email: invalid_grant …`, `slack_dm: channel_not_found`), stored with the outcome (`brief_state.record_delivery_outcome(detail=…)`) and shown on the Briefing notice and the Setup page's *Daily brief* light, whose fix says to reconnect when the detail shows a dead grant. Delivery stops at the first channel that sends, so an owner linked by email at setup keeps their Slack delivery without extra email, and gets the brief by email only when Slack is missing or fails. The email is formatted HTML (`utils.markdown_email`: raw HTML and images off, unsafe link schemes dropped) with a subject dated in the user's zone (\"Morning Brief — Fri 25 Sep\"). Email counts as ready only when the MCP gateway runs the Google Workspace server. Every run's outcome — delivered, no owner, nowhere to send it, every send failed, or the brief couldn't be written at all (the workflow failed or produced nothing) — is recorded with the channel's name (never an address) under `brief_state`, for the Briefing's notice and the Setup status \"Daily brief\" light (the weekly review's outcome too — `brief_state.DELIVERY_KINDS` — so a weekly review that wasn't sent is reported the same way). The light also turns amber when a brief got through only on a backup channel, naming the one that failed. `_run_principal_brief` sets `morning_brief.PRINCIPAL_DELIVERY` for the run, because it goes to the principal alone: only then (or on the principal's own verified chat turn) does the morning brief read what is private to them. When the workflow reports `private_to_principal` on its `result` event — it did read such a row — the run history keeps `persistence.PRIVATE_RUN_ARTIFACT` in place of the text (`stored_artifact`), since `/workflows/runs` is readable by everyone signed in; the principal gets the full text where it is delivered. When no channel can deliver at all (a web-only principal, or email with no gateway), the brief is still generated and stored as a run with its artifact — a web-only principal reads it on the Artifacts page — it is just not delivered, and the next occurrence is chained; see Workflows.\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. An optional `drive_sync_scan` heartbeat (`DRIVE_SYNC_ENABLED`, off by default, bootstrapped in the lifespan beside it) does the same for the configured Google Drive folders, into the isolated `drive_docs` collection (see RAG). An optional `onedrive_sync_scan` heartbeat (`ONEDRIVE_SYNC_ENABLED`, off by default) does the same for the configured OneDrive folders, into `onedrive_docs`. An optional `confluence_sync_scan` heartbeat (`CONFLUENCE_SYNC_ENABLED`, off by default, bootstrapped in the lifespan the same way) re-indexes the changed pages of the configured Confluence spaces into the isolated `confluence_wiki` collection, leaving out restricted pages, and purges pages that were deleted, moved out or restricted.\n\n**Take the lead wakes.** With Take the lead as the Executive on, a turn from a channel (mail, Slack, Discord, Telegram, Google Chat) calls `take_the_lead.wake`, which inserts one `take_the_lead_wake` `__internal__` action five minutes out. It does nothing while one is pending or running, and nothing within 30 minutes of the last wake. The runner's `_run_take_the_lead_wake` runs the same reflection as the daily rhythm (`_reflect`, shared with `_run_executive_reflection`), only if the switch is still on, and never chains. The pause holds it like every claim.",+ "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. Each due row runs in its own task, started with no audit scope (`audit.context.unscoped_audit_rows`): a scheduled action is unattended and never part of the turn that scheduled it, so its audit rows follow the ordinary rule. Polls are gated on an active company profile via `_company_profile_active()`; before onboarding, due rows stay `pending`.\n\n### Operator pause\n\nA global pause switch (`openexecutive.scheduler.pause`, one row in the `executive_control` table) stops everything the Executive starts on its own. It is the first check of every scheduler tick: while paused the tick does nothing — no alert/watchlist sweep, no claim — so due rows stay `pending` and fire on the first tick after resume. Actions already claimed when the pause lands run to completion; pausing holds work, it never cancels it. The same check gates the Gmail poller (the inbox is left unread) and the workflow resumer (no `wait_for_human` timeouts or resumes, and `apply_resolution` records a reply without kicking the run). Inbound conversations — web chat, Slack, Discord, Telegram, Google Chat — are deliberately not gated. The switch is set from the sidebar, the paused banner or Settings in the UI, or via `POST /executive/pause` / `POST /executive/resume`; each flip writes an `executive_paused` / `executive_resumed` audit row. Any signed-in caller may pause (it only holds work); resuming releases every held action at once, so it is the principal's alone (open only while no principal is on the roster). The state persists across restarts (boot logs a warning while paused) and across client-slot switches. `is_paused()` is read-only: a DB file or table that does not exist yet reads as \"running\", but a read error on an existing DB reads as \"paused\" — the brake fails closed, so a storage fault holds work rather than silently releasing it while the UI still shows \"paused\" (the UI shows \"status unknown\" when it cannot read the state).\n\n### Liveness heartbeat\n\nEvery tick ends by recording when it finished and what it did — `ran`, `paused`, `waiting_for_company`, `rotating`, or `failed` when the tick raised — and `run_scheduler` notes when it started. `scheduler_heartbeat()` returns both; they live in process memory, not the database. Settings → Setup status (`GET /setup/status`) reads them: no start means the task isn't running; no tick five minutes after starting, or none for three poll intervals (at least 90 s), means the loop has stopped; `failed` and `waiting_for_company` get their own light. Liveness is judged before the pause switch, because a paused scheduler still ticks: one that has stopped shows as stopped, where the Resume button wouldn't help. A restart clears the previous run's last tick. Due actions run as their own tasks, so a slow brief never ages the heartbeat.\n\n### Cadence DSL\n\n`openexecutive.departments.cadence` supports, all in UTC for department and workflow cadences:\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\n`PATCH /departments/{slug}` rejects a spec that does not parse (bad format, unknown DOW, out-of-range time) with a 422 naming the valid formats, so a typo is caught at save time instead of silently never firing. An empty spec means no cadence (the department page's **Off**). A new department starts weekly, `weekly@mon@09:00`. Changing a department's `check_in` through that route re-times it at once: `cadence.reschedule_check_in()` cancels its pending `dept_cadence` row and queues the next occurrence of the new spec (nothing when it is off or in solo); a check-in already running finishes, and its chain adds nothing because the new row is pending.\n\nWhen a department cadence is due, the runner invokes the `department_check_in` workflow and chains the following occurrence via `cadence.enqueue_next()`. The fire is not passed through the authority gate: the check-in sends nothing (it grades Goals, writes one audit row and a Honcho note), and every action it proposes carries its own `gate_action` verdict in the report. Before creating a run the runner applies a skip rule (`department_check_in.needs_check_in`): the check-in is skipped when the department has no specialist agent, has no Goals, or nothing is new since its Goals were last reviewed — no decision or audit row tagged to the department (the check-in's own review row aside) since the oldest Goal's `last_reviewed_at`, and no Goal edited after it was graded. A Goal never reviewed always runs it. A skip leaves no run in the activity rail, is recorded as `cancelled` with its reason (`skipped: …` in `last_error`) rather than `done` — a done cadence row means \"the check-in ran\" to the nudge engine — and still chains the next occurrence; so does a check-in that fails once its retries are spent, so one broken department does not fall out of its cycle. That final failure also files one Home card, \"*Finance* check-in didn't finish\" (`workflows.failure_alerts`, source `workflow_failed`, tagged `failed_run:<run id>`; repeats of the same check-in coalesce into it), because nobody watches a scheduled run; a scheduled saved workflow (`dynamic_workflow`) that fails files the same card, routed to the person it delivers to. The card's **Run again** (`POST /workflows/runs/{run_id}/rerun`) queues the same action, due now, with `scope_key` `rerun:<run id>`: it skips the skip rule and does not chain another occurrence, and re-timing the check-in leaves it queued (the dept chain is idempotent anyway; a saved workflow's `schedule_dynamic_workflow_cadence` is skipped). Chaining is idempotent: while a next occurrence for the department is already pending nothing is added, so a row that chained and then failed to record its outcome never leaves two. Seeded departments start with no Goals, so their weekly check-ins cost nothing until someone adds one. Deleting a department cancels its pending `dept_cadence` rows, and `cancel_orphaned_cadences()` sweeps orphans on boot.\n\nIn **solo mode** (one person using Open Executive just for themselves; see Org) there are no department check-ins: `bootstrap_cadences()` is a no-op, switching to solo cancels every pending `dept_cadence` row, a row that was already pending is marked `cancelled` by the runner without running and without chaining — ahead of the authority gate, so a `propose_only` department cannot turn it into an approval card, and cancelled rather than done because the nudge engine reads a done check-in as a recent department pulse — and a check-in already running across the switch finishes without `enqueue_next` scheduling another. Switching back to team re-bootstraps them. Solo has one kind of its own, the **weekly review** (`principal_weekly_review`, below): switching to solo seeds it (`seed_weekly_review`), switching to team cancels its pending row (`cancel_weekly_reviews`), and one that fires while the stored mode is team is marked `cancelled` without running or chaining. That check reads the mode strictly (`workspace_settings.read_stored_mode`) and fails open: a mode that can't be read (a locked database) is not taken for team, so one bad read neither retires the review nor breaks its chain — the next run checks again.\n\nThe parser also takes a zone: `_parse_cadence_spec(spec, after, tz=UTC)` builds the wall-clock time in `tz` and only then converts to UTC, so a local schedule stays at the same local time across daylight-saving changes (a time the spring-forward gap skips fires once, just after the jump; a time the fall-back repeats fires at its first occurrence).\n\n### The principal's rhythm\n\nThe morning brief (`principal_brief_morning`, 08:00), end-of-day digest (`principal_brief_eod`, 18:00) and reflection (`executive_reflection`, 07:30) are seeded once per database by `seed_principal_briefs()` and each chains its next occurrence when it fires. In a solo workspace it also seeds the **weekly review** (`principal_weekly_review`, Friday 16:00 local by default), which runs the `weekly_review` workflow and is delivered like the briefs; its `PRINCIPAL_WEEKLY_REVIEW_TIME` takes a whole weekly spec (`weekly@fri@16:00`), read as UTC when valid, like the pinned times below, and it chains only while the workspace is still solo — and never when a weekly row is already pending, so a switch to solo while a review finishes cannot leave two. Their default times are local to the user's zone — `memory.workspace_settings.get_user_timezone()`: the zone set through `PUT /workspace`, else `USER_TIMEZONE`, else UTC — computed with the cadence parser above. An operator who pinned a valid `HH:MM` in `PRINCIPAL_BRIEF_MORNING_TIME` / `PRINCIPAL_BRIEF_EOD_TIME` / `PRINCIPAL_REFLECTION_TIME` keeps that time read as UTC, as before zones existed, so a pinned time never moves; a malformed value is logged and treated as unset. An install that set `USER_TIMEZONE` but pinned nothing does move to that zone, from each kind's first fire after the upgrade (a row seeded before it keeps its old UTC time once). When the zone in effect changes, `reschedule_principal_rhythm()` re-times each kind's pending, not-yet-due row **in place** — it only updates `run_at` (guarded on the row being unchanged since it was read), never inserts or cancels, so it cannot race a chain into a duplicate. The new time is the next occurrence in the new zone after `max(now, last fired run + 12h)`, so a kind never runs twice within 12 hours; and if that is more than 12 hours later than the row's current time — moving would skip a day, as when someone switches to Europe/London at 07:59 UTC with the 08:00 UTC brief a minute away — the row keeps its time once. A kind with no such row is left alone: a row that is running, one between being marked done and its chain insert, or a due row held by a pause or a missing company profile. Its chain times the next one in the new zone, and the chain itself starts from `max(now, fired run + 12h)`, so a zone change while a brief runs cannot put a second brief a few hours after it. The weekly review follows the same rules with a 3.5-day gap (`_min_gap`) in place of 12 hours, so a zone change can neither run it twice in a week nor skip one.\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 — with one exception, the **held-writes** pause: when an action step holds a write to a new target, the runner checkpoints the run (`checkpoint_gate`, the owner is DMed), still marks the row done and re-chains the cadence, and stamps `deliver_to_person_id` on the resume payload so the resumer DMs the artifact to the cadence recipient once the owner answers (or the 48 h timeout skips the held writes). Any other gate is still refused at execution: 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**Monthly tally.** On the first weekday of each month, in daytime (09:00–18:00 local), a tick hook beside the reminders (`_maybe_send_monthly_value` → `briefing.value_summary.maybe_send_monthly`, checked every 15 minutes) sends the owner last month's counted lines and a link to Pulse → Your month through `_deliver_to_principal`, in solo and team mode alike. It is claimed once per month (`briefing_narrative` scope `value_summary:YYYY-MM`, never released, so one try), skipped for an empty month, audited `value_summary_sent` / `value_summary_not_sent`, and off with `VALUE_SUMMARY_MONTHLY_ENABLED=false`. It is not a `scheduled_actions` row.\n\n### Department authority & cancelling\n\nA department-scoped row passes the authority gate (`departments.authority.gate_action`, see Org) before it is dispatched: `auto_execute` dispatches; `propose_only` raises an approval card and marks the row done without dispatching (deferred to the approver's next availability window when they are outside it); `escalate` raises an urgent `[ESCALATION]` card (severity high) straight away — never deferred — and likewise does not dispatch, because approving the card is what sends it. As that card is the action's only trace it always lands: unrouted when there is no approver and no principal, and deduped on the whole action (kind, channel, recipient and intent) rather than the summary's first 60 characters, so another escalation sharing an opening — or the same text for someone else — cannot swallow it. An identical escalation folds into a still-open card and gets a fresh one once that card was handled, and a card that cannot be written retries the row with backoff and, once the retries are spent, marks it `failed` — never `done`. (It used to raise the card *and* dispatch.) The runner records which action each card holds (`alert_held_actions`, server-side only, never a tag a model could write): approving one (`POST /alerts/{id}/approve`) queues a copy of that exact action with no department, so it goes out on the next tick without meeting the gate again. A `dept_cadence` row is not gated at all — gating it turned every check-in on a propose-only department (all eight seeded ones) into a one-shot card, and the row never chained its next occurrence. Nudge-engine rows carry no department and bypass the gate.\n\nA `pending` row can be cancelled with `DELETE /scheduled/{id}` — the Pulse page's Cancel; the update only moves a row that is still `pending`, so one the scheduler has just claimed is never overwritten. Cancelling only stops work, so, like pause, any signed-in user may: the route accepts a signed-in caller through the UI proxy (its `x-caller-email`, trusted only alongside the `BACKEND_SHARED_SECRET` `x-api-key`), a matching `X-Admin-Token` (`SCHEDULED_ADMIN_TOKEN`, for scripts), or a loopback caller when no token is set — otherwise 401 (token set) or 503. Each cancel is audited as `scheduled_action_cancelled` with who did it.\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\nAn idle initiative is chased with its department's head; with no head to resolve — no department (what the episodic extractor stores), an unknown department, or no head set — the principal owns it. That source used to skip every initiative without a head, so in practice it never fired. The principal gets self-addressed wording (\"<title>\" has not moved since <date> — still active, done, or dropped?). If channel routing cannot reach the principal (no channel configured, or unreachable beyond `NUDGE_MAX_DEFER_DAYS`), the nudge becomes an unrouted Briefing card instead, keyed on the initiative and the ISO week: at most one card per initiative per week, and while one is still unread the scan leaves it alone rather than refreshing it every 15 minutes. The emitted nudge still carries no department, and the usual caps and cooldowns apply. A department-tagged initiative is still skipped while its department's check-in actually ran inside the idle window; a skipped check-in does not count.\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`. The same throttled call also deletes Always in the loop notes past their expiry (`memory.history.sweep_expired`; reads already skip them, and it never raises). Each tick also calls `_maybe_remind_notes` → `memory.history_reminders.maybe_remind` (its own 15-minute throttle, 09:00–18:00 local, one task at a time): a person whose notes say something they promised by email is due today gets one message saying how many, through `deliver_to_person` — the brief's own channel order for any Person, never a shared channel (`delivery_order` now skips a Telegram group id, for the briefs too), with the senders' audit rows private to that person. A hook rather than a `scheduled_actions` row, which `/scheduled` would show to everyone (see Memory).\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\nThe /today **\"What's going on\" header** is kept current from the tick too, so it is fresh before anyone opens the page. `_maybe_refresh_narrative` is a throttled call inside the loop, like the alert sweep — no `scheduled_actions` row. It runs after the pause, company-profile and rotation gates, every `BRIEFING_NARRATIVE_REFRESH_MINUTES` (10; 0 turns it off) and only between `BRIEFING_NARRATIVE_REFRESH_START_HOUR` and `_END_HOUR` (06–22) in the user's zone. It starts `today.refresh_principal_narrative` as its own task, so a slow model call never holds the tick, and never starts a second while one runs. That refreshes the cached calendar read (`live_signals.refresh_calendar`, at most once per 15 minutes) and rewrites the principal's header only when its key moved — new mail, a held reply, a proposal, the hour — with the route's own per-scope lock, so a page view and the tick never write the same header twice (see Today).\n\nAct as me's **reminders** are loop-level too: `_maybe_send_reminders` starts `delegation.reminders.maybe_send` at most once a minute, which claims each due `delegation_reminders` row once (due times are stored in UTC, so they compare in order) (compare-and-set on `claimed_at`) and sends its stored text, prefixed \"Reminder you set on <date>:\", to the person who set it alone through `deliver_to_person`. No model and no tool run; a reminder missed by more than two days is dropped rather than sent late, and one due in the person's quiet hours or leave waits, unclaimed, until they end; audit rows are private to the person. They are not `scheduled_actions` rows for the same reason as the scan below: that list is everyone's, and its rows run an Executive turn when they fire.\n\n**Held messages** are loop-level as well: `_maybe_release_held` starts `people.held_messages.maybe_release` at most once a minute, which sends each person whatever is due to them — messages held for their quiet hours once those end, and brief-held messages made due when the briefs run — as one *While you were away* message through `deliver_to_person`, claims each row first so a brief can't send it too, marks them sent only once that went, postpones a person back in quiet hours, on leave or outside their windows to when that ends, backs off 2, 4, 8 … minutes (at most an hour) after any other failure, and audits every drop (too old, over the cap) privately as a count, and writes audit rows private to the person. The principal-brief handler appends the principal's brief-held messages to the morning brief or end-of-day digest it delivers (`_with_held_messages`; the stored run artifact is unchanged), claims them, marks them sent only when the brief went (otherwise frees the claim), then makes everyone else's due (`_release_others_digests`). The `proactive_nudge` re-check calls `prefer_channel_for` / `next_available_window` with `quiet_hours=True` (urgent for a `nudge:stalled:` scope key), so a nudge due in the person's quiet hours is deferred to their end like one outside an availability window. A dispatch whose message was held is audited `held`, not `delivered`. See Org for the notification settings.\n\nAct as me's **inbox watcher** is loop-level the same way: `_maybe_scan_inbox`, after the same gates, starts the due scans (`delegation.inbox.maybe_scan`) as one task and never a second while one runs. A person is due every `DELEGATION_INBOX_POLL_MINUTES` (default 5) once their **Draft replies to my inbox** switch is on, unless a Gmail failure set a back-off; nobody is scanned while a client slot is active. It is deliberately not a `scheduled_actions` row: those are listed on `/scheduled` for everyone and anyone may cancel them, and a scan reads the owner's own mail. Every row a scan writes is private to the principal (see Act as Me).\n\n### Principal briefs\n\nThe `principal_brief_morning` / `principal_brief_eod` / `principal_weekly_review` rows (and the client-rotation digest) are delivered by `_deliver_to_principal`, not through a row channel. The principal's `preferred_channel` (`slack` / `discord` / `telegram` / `email` / `any`) is tried first, then the other chat channels they have an id for (Slack → Discord → Telegram). Email goes through the active MCP gateway: first when the preference is `email`, and otherwise last, as the backup after every chat channel. Before planning, the delivery asks the gateway supervisor for a start if the gateway is down (`runner.ensure_email_ready` → `mcp_gateway.ensure_active_gateway`, the lazy re-check), and a row action resolves the gateway at execution time rather than from what boot had, so a gateway that failed at boot and came up on a retry carries the brief. The outcome names what happened: `gateway_down` when email is set up but the gateway is not running (the Executive's fault, with the start failure, never `no_channel`, which blamed the owner's setup), and a `send_failed` detail that quotes each channel's own error (`email: invalid_grant …`, `slack_dm: channel_not_found`), stored with the outcome (`brief_state.record_delivery_outcome(detail=…)`) and shown on the Briefing notice and the Setup page's *Daily brief* light, whose fix says to reconnect when the detail shows a dead grant. Delivery stops at the first channel that sends, so an owner linked by email at setup keeps their Slack delivery without extra email, and gets the brief by email only when Slack is missing or fails. The email is formatted HTML (`utils.markdown_email`: raw HTML and images off, unsafe link schemes dropped) with a subject dated in the user's zone (\"Morning Brief — Fri 25 Sep\"). Email counts as ready only when the MCP gateway runs the Google Workspace server. Every run's outcome — delivered, no owner, nowhere to send it, every send failed, or the brief couldn't be written at all (the workflow failed or produced nothing) — is recorded with the channel's name (never an address) under `brief_state`, for the Briefing's notice and the Setup status \"Daily brief\" light (the weekly review's outcome too — `brief_state.DELIVERY_KINDS` — so a weekly review that wasn't sent is reported the same way). The light also turns amber when a brief got through only on a backup channel, naming the one that failed. `_run_principal_brief` sets `morning_brief.PRINCIPAL_DELIVERY` for the run, because it goes to the principal alone: only then (or on the principal's own verified chat turn) does the morning brief read what is private to them. When the workflow reports `private_to_principal` on its `result` event — it did read such a row — the run history keeps `persistence.PRIVATE_RUN_ARTIFACT` in place of the text (`stored_artifact`), since `/workflows/runs` is readable by everyone signed in; the principal gets the full text where it is delivered. When no channel can deliver at all (a web-only principal, or email with no gateway), the brief is still generated and stored as a run with its artifact — a web-only principal reads it on the Artifacts page — it is just not delivered, and the next occurrence is chained; see Workflows.\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. An optional `drive_sync_scan` heartbeat (`DRIVE_SYNC_ENABLED`, off by default, bootstrapped in the lifespan beside it) does the same for the configured Google Drive folders, into the isolated `drive_docs` collection (see RAG). An optional `onedrive_sync_scan` heartbeat (`ONEDRIVE_SYNC_ENABLED`, off by default) does the same for the configured OneDrive folders, into `onedrive_docs`. An optional `confluence_sync_scan` heartbeat (`CONFLUENCE_SYNC_ENABLED`, off by default, bootstrapped in the lifespan the same way) re-indexes the changed pages of the configured Confluence spaces into the isolated `confluence_wiki` collection, leaving out restricted pages, and purges pages that were deleted, moved out or restricted.\n\n**Take the lead wakes.** With Take the lead as the Executive on, a turn from a channel (mail, Slack, Discord, Telegram, Google Chat) calls `take_the_lead.wake`, which inserts one `take_the_lead_wake` `__internal__` action five minutes out. It does nothing while one is pending or running, and nothing within 30 minutes of the last wake. The runner's `_run_take_the_lead_wake` runs the same reflection as the daily rhythm (`_reflect`, shared with `_run_executive_reflection`), only if the switch is still on, and never chains. The pause holds it like every claim.","mermaid": "flowchart TD\n Loop[\"run_scheduler<br/>poll every 30s\"]\n Pause{\"is_paused()?<br/>(executive_control)\"}\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<br/>(skipped when nothing is new)\"]\n Solo[\"solo workspace →<br/>cancelled, no chain\"]\n Nudge[\"nudge_scan →<br/>nudge_engine scan\"]\n Brief[\"principal_brief_morning / _eod →<br/>morning_brief / end_of_day_digest<br/>(user's local time)\"]\n Weekly[\"principal_weekly_review (solo) →<br/>weekly_review, Fri 16:00 local\"]\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 Drive[\"drive_sync_scan →<br/>isolated Drive folder ingest\"]\n Confluence[\"confluence_sync_scan →<br/>isolated Confluence space 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 or email principal\"]\n Alerts[\"alerts pipeline → /today\"]\n Loop --> Pause\n Pause -- \"paused: hold, sleep\" --> Loop\n Pause -- \"running\" --> Claim\n Claim -- \"claim due rows\" --> Table\n Claim -- \"ad_hoc / proactive_nudge\" --> Dispatch\n Claim -- \"dept_cadence\" --> Dept\n Claim -- \"dept_cadence (solo)\" --> Solo\n Claim -- \"nudge_scan\" --> Nudge\n Claim -- \"principal_brief_*\" --> Brief\n Claim -- \"principal_weekly_review\" --> Weekly\n Claim -- \"executive_reflection\" --> Reflect\n Claim -- \"external_monitor_scan\" --> ExtMon\n Claim -- \"watchlist_research_scan\" --> Research\n Claim -- \"notion_sync_scan\" --> Notion\n Claim -- \"drive_sync_scan\" --> Drive\n Claim -- \"confluence_sync_scan\" --> Confluence\n Nudge -- \"prefer_channel_for\" --> Prefer\n Prefer -- \"emits proactive_nudge\" --> Table\n Dispatch --> Channels\n Brief --> Principal\n Weekly --> Principal\n ExtMon --> Alerts\n Dept --> Chain\n Nudge --> Chain\n Brief --> Chain\n Weekly -- \"while solo\" --> Chain\n Reflect --> Chain\n ExtMon --> Chain\n Research --> Chain\n Notion --> Chain\n Drive --> Chain\n Confluence --> 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 Solo compute\n class Nudge compute\n class Brief compute\n class Weekly compute\n class Reflect compute\n class ExtMon compute\n class Research compute\n class Notion compute\n class Drive compute\n class Confluence compute\n class Chain compute\n class Prefer compute\n class Channels external\n class Principal external\n class Alerts hot",- "generated_at": "2026-10-13T20:51:24Z"+ "generated_at": "2026-10-14T05:32:32Z"}diff --git a/packages/core/openexecutive/architecture/prebuilt/today.json b/packages/core/openexecutive/architecture/prebuilt/today.jsonindex 10dd6a20..5ec9cee3 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>`). Every signed-in page shares one sidebar (`AppSidebar`). Its Recent list is capped at the 7 newest web chats. The full history, including Slack, Telegram and Discord conversations (recognised by their session-id prefix), lives on `/chats`. A chat opens from any page through `/?session=<id>`.\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- **Private cards.** An alert tagged `private:principal` (`alerts.models.PRIVATE_ALERT_TAG` — raised on a turn about mail from one of the principal's contacts or mail they forwarded, or a meeting proposal with a contact) is in `proposals` only when the caller is the principal. `_build_today` leaves it out by default, so the end-of-day digest, the reflection and Discord's `/today` never see it, and the morning brief reads it only on a run for the principal (the scheduler's, or the principal's own verified chat turn in a conversation only they can read — see Workflows). The narrative is written from one only in the principal's own `principal` scope, which nobody else is served; the shared `company` scope an unresolved caller gets, and a teammate's scope, never are. The activity rail skips it, and the chat digest includes it only on the principal's own verified turn.\n- **Roster-request cards.** When someone not on the People list writes in (see Org and Integrations), `people.roster_requests.surface_card` raises an alert of source `roster_request` (medium, tagged `roster_request:<id>` and `private:principal`, routed to the principal), so it follows every private-card rule above. `GET /today` attaches `roster_request` to that proposal (`_roster_request_card`: channel, address or account id, the sender's sanitised and unverified name, profile email, company-domain flag, suggested kind and person, message count, whether they were acknowledged, first seen, and the held messages' first lines) while the request is still pending. The Briefing renders it as its own card (`RosterRequestCard`: add as a new person with a name and an explicit team/contact choice — pre-filled as team on a company domain — or \"someone already on the list\", with a replace-account option for a chat id, or Ignore), which calls `/people/requests/{id}` directly and never hands off to chat, so what a stranger wrote never seeds a turn. The card is kept out of everything that could close it without answering it or put the stranger's words in front of a model: the narrative (`_action_proposals` drops it), the chat's open-alert digest (`<briefing>` — the principal's verified turn gets a separate `<roster_requests>` block instead; see Agents), `ack_alert`, a single ack (`POST /alerts/{id}/ack` is a 409), the \"Dismiss N older than 7 days\" count and the server's bulk ack, reopen, the TTL sweep and the alert review (`roster_request` is in `lifecycle.TTL_EXEMPT_SOURCES`). It ends when the request does: answered (`ack`, or `dismissed` on a decline) or expired after `ROSTER_REQUEST_TTL_DAYS`.\n- **`people`** — an attention-ranked roster of the **team** (the principal's contacts are never listed, and get no insight note). 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)`. Stale insight notes are regenerated in the background only when the roster has more than one person: the UI shows the People sidebar only for more than one, so a one-person install (solo, or a team before anyone else is added) does not pay a daily model and peer-memory call for a note nobody sees. Cached notes are still served.\n- **`proposals`** — the *live* unread alerts (workflow approvals, triage-classified inbound, Executive signals, flagged artifacts, and gated calendar bookings; an artifact is listed only to its owner (`alerts.models.visible_alert`; every other build of the board — the briefs, the reflection, the review, the chat digest on anyone else's turn, the activity rail — leaves drafted artifacts out) and carries `artifact_format` / `artifact_url` and a `body` already rendered to Markdown for its format, so the card badges it as a web page, Word doc, spreadsheet or link and offers *Open artifact*): 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). `failed_run_id` is set only on a `workflow_failed` card (a scheduled run that ended in error, see Scheduler): its main button is **Run again** (`POST /workflows/runs/{id}/rerun`, which also closes the card) and its ⋯ opens the run; it has no Approve. The response also carries `held_back` for the principal alone: the lines grounding left out of the morning brief or end-of-day digest in the last day, which Home lists under **Left out of your brief** (the brief's note names it; Hide is remembered in that browser). The UI splits them into 'mine' vs 'across the team' using `caller_person_id`. Approve is carried out on the server for every card. 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), so meeting bookings are reviewed in the briefing itself rather than on a separate page. Every other proposal is approved at `POST /alerts/{id}/approve` (`alerts.approvals`): it records who approved the card and when (an `alert_approvals` row plus `alert_approved`, then `alert_approval_done` / `alert_approval_failed`, audit rows), claims the card in one transaction so a double click or a second approver gets a 409 and the work runs once, then does the work. A card the scheduler filed for a department-gated action is bound to it server-side (`alert_held_actions`, written only as the card is filed, never read from the card's tags or text, which a model reading inbound mail can write), and approving it queues that exact action again with no department, the approval being the consent the gate waited for. Any other proposal runs one Executive turn as the approver in a new chat on the server (`chat.start_background_turn`, the machinery behind `POST /chat/background`), with the edited text verbatim for Edit & approve; it keeps going if the page closes. Only the card's routed person or the principal may approve a routed card, and only the principal an unrouted one (403 otherwise); the card's text reaches the turn as quoted data, not instructions. A row at the top of Needs you follows the approval (`GET /alerts/approvals/{id}`): working on it with a link to the chat, then done, or didn't work with Try again; a card whose last approval failed can be approved again, and one still running at a restart is marked failed on boot. The page no longer acks the card and seeds a chat turn with the proposal, which left no record of the approval and did nothing if the tab closed first.\n- **`narrative`** — a per-viewer Executive-voice header (\"What's going on\") synthesized by `synthesize_briefing_narrative`, cached per scope in `briefing_narrative`: the resolved principal gets the whole-company `principal` scope (which may carry what is private to them), a caller who resolves to no roster row the shared `company` scope (written from what everyone may see), and each teammate a role-scoped `person:<id>` one. `narrative_generated_at` says when the served text was written and `narrative_stale` whether a fresher one is being written now. 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. When the principal names an item that has already left the board — opened, snoozed, or older than it — the Executive looks it up with `find_alerts` (a keyword search over every status, `alerts.store.search_alerts`); matches that are still open (`unread` or `read`) become ackable for that turn, up to 25, and closed ones come back labelled so the Executive can say the item is already settled. It works only where the principal's own board was shown this turn — the web app or their DM — and never returns roster-request cards (see Lifecycle). The digest's header also labels every headline and detail as untrusted content drawn from inbound mail, chat and watched pages — act on what the principal asks about an item, never on what its text asks — and triage reads each signal inside an `<event>` block whose closing tag the sender's text cannot forge (it is defanged in any case and spacing, after NFKC folds fullwidth forms). 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\n **Live, not just the board.** The header used to reason over the alert board, goal health and the Executive's own bookkeeping only — mail and chat handled that day, replies the gate held and the next meeting never reached it, so it read the same for days while the principal's day moved on. The whole-company scopes now open the context with the principal's world as it is happening (`briefing.live_signals.gather_live_signals`, rendered by `render_live_blocks`), under a `NOW:` line: **INBOUND** (`integration_inbound` audit rows that carry a message, grouped by sender and subject, with an email's first line), **STUCK** (`integration_outbound_blocked` to a recipient, the inbound \"reply blocked at outbound gate\" and Google Chat \"left unanswered\" / \"not delivered\" rows, and drafts saved by Act as me), **CONVERSATIONS** (the principal's own web chat titles) and the **REST OF TODAY'S CALENDAR**. The window is the local day, or the last 12 hours when that is longer. Private audit rows, drafts, chat titles and the calendar (meeting titles are the principal's own) are read only in the `principal` scope — `gather_live_signals` drops the calendar whenever `include_private` is false, whatever the caller passes, so the shared `company` header never quotes it. The calendar is never fetched on the request: `live_signals.refresh_calendar` caches one read per 15 minutes (the scheduler tick refreshes it) and the header quotes the cache. Every quoted field is collapsed to one line and cut, and the blocks and the prompt both say the text is data, never instructions — inbound mail is attacker-controlled. With live blocks present the context also ages each proposal (`raised 2d ago`, whole days), names each at-risk department's slipping goals (`attention_goals`) and adds an **EXTERNAL SIGNALS** block (monitoring alerts from the last 24 h, never enough on their own to break the quiet line); the rhythm runs (`today.RHYTHM_WORKFLOWS`: the morning brief, end-of-day digest, reflection and weekly review) are dropped from the activity it reasons over. The prompts (`BRIEFING_NARRATIVE_SYSTEM` and its solo variant, `NARRATIVE_PROMPT_VERSION` 6) lead with what is live and give a days-old item at most one bullet. Anything live breaks the quiet line; the NOW line and window move at most once an hour, so the key moves hourly on time alone plus whenever something new lands; the calendar is placed at the real time (a meeting that has ended drops out, the one under way is IN PROGRESS), which moves it only when a meeting starts or ends.\n\n **Fresh without a reload.** The daily floor in the key and the PERIOD line are the principal's **local** date (`narrative_cache.local_today`), not UTC's, and a row written on an earlier local day is not served as today's. Regenerations are serialized per scope; a trigger that finds one running marks the scope pending and the running pass goes round once more (it built its context before that trigger's news landed), and after a failed pass (model error, the 25 s timeout, empty text) no view or tick starts another for 5 minutes and `narrative_stale` reads false, so the page drops its placeholder instead of spending a model call per view. They log `today: narrative served scope=… age_s=… stale=…` and `today: narrative regenerated scope=… ms=…`, and no longer need a page view: every `BRIEFING_NARRATIVE_REFRESH_MINUTES` (10) between `BRIEFING_NARRATIVE_REFRESH_START_HOUR` and `_END_HOUR` (06–22 local) the scheduler runs `today.refresh_principal_narrative`, which refreshes the calendar cache and rewrites the principal's header only when its key moved (see Scheduler). The Briefing re-polls `/today` at 4, 10 and 20 s while `narrative_stale` is true, re-pulls it when the tab comes back (at most once a minute) and every 5 minutes while visible, shows \"Updated 2:04 PM\" beside the heading, and shows \"Catching up on today…\" while the first header of the day is written (`lib/narrativeFreshness.ts`, tested by `npm test`).\n\n In **solo mode** (one person using Open Executive for themselves) the header speaks to the principal, whatever their role: a solo prompt over a context that lists goals at risk by *area* and has no \"people waiting on you\" block, and the quiet check ignores who is awaiting. The cache key carries the mode for solo only, so solo and team never share a cached narrative while every team key stays exactly what it was — no team cache is invalidated. The response shape does not change. For the principal's own view the solo context also carries a **DUE THIS WEEK** block — the principal's open loops that are overdue or due within 7 days (`today._with_due_soon` → `open_loops.principal_due_soon`, labelled OVERDUE / due today / due <weekday>) — which counts as needing attention in the quiet check and moves the cache key when an item is added, closed or falls due; a teammate's scoped view and team mode never get it. The header never gets the morning brief's *top three today* block — that is the DM brief's (see Workflows); the page shows the same top three in a card of its own (see *Solo focus cards* below). It does get the rest of today's calendar through the live blocks above, from the cached read.\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. Audit rows private to the principal (say, one naming their contact) are in this list only on the principal's own `/today`: `brief_state.handled_since` leaves them out unless asked, and the written briefs never ask, since a brief can be read by others. The Pulse heatmap's per-day counts (`GET /today/activity/daily`) likewise leave out a private decision or private alert, as the activity rail does. The morning brief also carries a one-line count of research watch suggestions waiting on `/watchlist`.\n\n**Standing facts.** `render_briefing_context` appends the standing facts (`memory.facts`: corrections kept from chat, a teammate's marked `(per <name>)`) as its last block, after the quiet-day check, so a fact never makes a quiet day look busy. The morning brief also carries **TEAMMATE CORRECTIONS SINCE LAST BRIEF** (`facts.render_teammate_changes(since)`: each teammate fact recorded in the window that is in use now, plus — only when the brief is the principal's own private one (`_private_ok`), which then keeps the run out of the shared history — those waiting for their approval, since other teammates may run the brief and never see a proposal that is not theirs) before the quiet check — it is news, the principal's only FYI of it — and in the brief's fingerprint (`build_brief_fingerprint(teammate_changes=)`), so a correction alone un-suppresses an otherwise unchanged brief. Every other caller passes none, so its context is unchanged. The /today header hashes that rendered string as its cache key, so a new or retired fact marks the header stale and it is rewritten with the correction. The morning brief (standalone) and the teammate-scoped header get the same block. On the scheduler's delivery to the owner alone, with their Always in the loop switch on, `render_briefing_context(owner_notes=)` also carries FROM YOUR NOTES — DUE SOON (their own notes of what they promised or asked, overdue to a week ahead; `memory.history_brief`), which counts against a quiet day, enters the fingerprint and marks the run private; both standalone prompts turn it into a **From your notes** section. The /today header never gets it. **The first week.** For seven days from the principal's People row (`briefing.first_week`), `render_briefing_context(getting_started=)` carries a GETTING STARTED block right after the live blocks: the goals saved at onboarding (department, key result, target, period), departments with no `head_person_id`, and, on the scheduler's delivery to the principal alone with Act as me and Draft replies to my inbox both on and the mailbox connected (the inbox watcher's consent), up to five people who wrote to their own mailbox in the last 48 hours as sender and subject only (`inbox_message_ids` + headers of `get_message`, bulk and automated mail skipped; the same \"where, never what\" rule as `delegation.mail_reads`). It counts against a quiet day, enters the fingerprint (`getting_started=` keys, no dates) and, with the inbox part, marks the run private. Both standalone prompts open with a **Getting started** section and take the Top call from it (`GETTING_STARTED_RULE`); the whole-company /today header gets the block without the inbox (`getting_started_shared`, synchronous, no mailbox read) and the header prompts take the bottom line and move from it (`GETTING_STARTED_HEADER_RULE`), so a new install's header is not short-circuited to the quiet line. `GET /today` sets `first_week`, and the Briefing hides the \"Quiet day\" banner while it is true. A teammate's scoped header never gets it. The alert review's `render_batch` puts the same block ahead of the alerts (read once per pass), so a note, rewrite or routed DM never repeats a figure the principal already corrected.\n\n**When a brief isn't sent.** Above the Briefing, the owner sees a one-line notice when their latest morning brief, end-of-day digest or (in solo mode) weekly review wasn't sent — \"Your morning brief wasn't sent: nothing is set up to send it to you\" — with the day, what fixes it, a link to read the brief on the Artifacts page (left out when the brief couldn't be written at all) and one to Setup status. It comes from `GET /today/brief-delivery` (the scheduler records each run's outcome), shows nothing while briefs go out or while the scheduler is off, and clears once the cause is fixed. When the Executive's mail connection wasn't running (the MCP gateway failed to start and is retrying), the notice says that instead of blaming the owner's setup; a send that failed on every channel names what each channel answered, from the recorded `detail`, with addresses left out. Teammates never see it.\n\n**Replies waiting.** With Act as me's **Draft replies to my inbox** on, the top of the Briefing's left column lists the replies the Executive drafted in the owner's own Gmail for mail that needs them (`RepliesWaiting`, from `GET /delegation/replies` — see Act as Me). They belong to the owner alone: the route answers only the person who can have Act as me, the decisions behind the cards (`delegation_reply`) are principal-only and carry `private: true`, so `/today/activity` and the heatmap leave them out, and none is ever an alert, so nothing of them reaches `GET /today`, the header or the briefs. Each card shows who wrote and who they are to the owner, whether their address was verified, the subject, what they wrote (as plain text), the draft, **Decide before sending** (its open questions) and its warnings, with **Send**, **Edit in Gmail** (the thread in their Gmail) and **Dismiss** (which deletes the draft unless they edited it). **Send** asks first, naming who the reply goes to, then sends the draft exactly as it is in Gmail (`POST /decisions/{id}/approve`); when its recipients changed in Gmail or a newer message arrived, the backend's 409 `confirm` becomes a second question naming them. The card hides itself when nothing is waiting.\n\n**Solo focus cards.** `GET /today/top-three` and `GET /today/weekly-review` feed two solo-only cards, so a principal who only uses the web app — no chat app, no Google Workspace — sees today's top three and the weekly review instead of finding them only in the Workflows run history. Both answer only in solo mode (`effective_workspace_mode`) and only to the principal, by the stricter rule for starting a principal-only run (`workflows._caller_is_the_principal`: the caller's own email on a principal entry that is not archived, or no `x-caller-email` at all — never \"nobody is principal yet\"); a teammate, any other signed-in caller and team mode get null. `top-three` hands `open_loops.principal_due_soon()` to `briefing.top_three.build_top_three` — the morning brief's own inputs and code, so the items, their order and their free slots are the brief's — and returns `{items: [{key, kind, text, why, slot}]}`: `slot` is the free block (\"10:00–11:00\", the user's zone), \"\" when none is left, or null when no calendar was read (none connected, a failure or the 4 s timeout, a weekend); `items` is empty when there is nothing to pick. It is a route of its own, never part of `GET /today`, so the Briefing never waits on the calendar. `weekly-review` returns the latest `weekly_review` run with status `done` (`persistence.list_runs(..., status=\"done\", limit=1)`, newest `updated_at` first; failed and running runs never count) as `{run_id, completed_at, period, top_three, excerpt}`: `weekly_review.summarize_review` reads the artifact's title line and its last *Next week's top 3* section back as plain text, and `excerpt` stands in when that list is empty (the section's own note, else the review's first lines). Null when no review has completed or the run store cannot be read.\n\nThe route resolves the caller from `x-caller-email`, serves the viewer's cached narrative and, when its key moved, rewrites it in a `BackgroundTask` so the request never blocks on an LLM call (the page re-polls while `narrative_stale` is true). `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; solo mode has its own, with goals at risk by area and no waiting-on section). `GET /morning-brief` is a deprecated alias.\n\n**Solo mode in the UI.** The response is the same in both modes; the briefing reads the workspace mode from the app-wide `WorkspaceProvider` (which reads team while loading or on error, so a team install never flashes solo) and, in solo, drops the team surfaces: the Departments card, the People card, the \"Across the team\" lane (every action proposal is the one user's, so all of them land in \"Needs you\"), the people-awaiting, people-overdue and departments-at-risk status pills, and the quiet-day \"Set up a check-in\" link. A \"N goals at risk\" pill (at-risk plus off-track goals, from `departments`) links to `/goals` instead, so the strip never reads \"All clear\" over a goal that is slipping. In the Departments card's place, **Your projects** lists the initiatives with status `active` (`GET /memories/initiatives`): **Done** marks one `completed` through `PATCH /memories/initiatives/{id}` (only `completed` takes an initiative out of the Executive's active context), and **Drop** deletes it through `DELETE /memories/initiatives/{id}` after a confirm. Under **Needs you**, a **Due soon** card lists the principal's open loops that are overdue or due within 7 days — their dated commitments and what others asked of them — read from `GET /people/{id}/open-loops` for the principal (the oldest principal in `people`, the backend's rule), labelled by `lib/dueSoon.ts` (tested by `npm test`: \"Overdue since Sep 23\" / \"Due today\" / \"Due Mon, Sep 28\", with a count of anything due later); **Done** closes one through `POST /open-loops/{id}/close`, which also stops the nudge engine chasing it. Above it, **Top three today** numbers the morning brief's three (`GET /today/top-three`) with each one's reason and, when a calendar was read, its free slot (or \"No free time left today\"); at the top of the right-hand column, **This week's review** (`GET /today/weekly-review`) shows the period, when it ran, next week's top three (or the excerpt) and a *Read the review* link to its run page (`/jobs/runs/{id}`). Each card fetches on its own once the Briefing has loaded, so a slow calendar never holds the page up, and renders nothing when the API returns null or an empty list. A commitment in the top three reads as the owner's own (\"Send the proposal\") through `lib/dueSoon.ts`'s `loopText`, as in Due soon; the cards' wording lives in `lib/rhythmCards.ts` (tested by `npm test`). The Pulse page hides its \"Department check-ins\" and \"Awaiting people\" blocks in solo, and its header shows active projects in place of the department check-in count. Team rendering is unchanged.\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. Four things now keep it live and true:\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. **Snooze** (a card's ⋯: later today, tomorrow 9:00, Monday 9:00, in the viewer's clock; `POST /alerts/{id}/snooze`) hides a card until `snoozed_until`, with an Undo; the TTL anchor is the latest of `created_at`, `last_seen_at` and `snoozed_until`, so a snoozed card comes back rather than expiring unseen.\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- **Collection tags** (`alerts.pipeline`). A triaged alert never carries a `collection:<name>` tag: the pipeline strips them before inserting. Only an installed extension's own code files a document into its collection (`orchestrator.extensions`), so injected text can't make a card that the extension would treat as its own.\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 (team members only — an alert routed to a contact never puts them in the slice, so they are never routed to, nudged or chased; a private card is never reviewed at all, nor used as evidence for another), 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). A review DM is proactive outreach, so the recipient's notification settings apply: one held for their quiet hours or brief counts as a route made but not as a nudge toward the cap (and no second nudge is held while one waits), and one about an alert whose severity is (or becomes) `urgent` is marked urgent (`notifications.urgent_send`) and gets through when they let urgent things through.\n- **Grounded text** (`openexecutive.briefing.grounding`). Nobody reads an alert's text before it is dispatched, so what the model wrote onto it must be supported by what it read. After triage (`alerts.pipeline._ground_decision`, before coalescing or inserting), a headline naming a person or figure the event does not hold — sources are the event's subject, sender, title and body, the initiatives triage was shown and the company profile — is replaced by the event's own subject, such body sentences are dropped (all of them → the event body cut to 280 chars); both fallbacks are raw event text, so they are made inert first — links masked, Markdown and Slack `<…>` syntax and @-mentions stripped — because a broadcast posts them as written, and such a suggested action is dropped. A review `changed` rewrite is checked against the alert's own text and the evidence it was reviewed with (signals, related alerts, activity, the roster slice), plus the standing facts the batch was shown, so a rewrite that corrects a card to one of the principal's corrections is grounded; an ungrounded rewrite keeps the old text, still applies a severity change, and audits `text_ungrounded`. A name counts as grounded only when one source line holds all of it; a figure only when a source number matches it within the precision it is written with. Each finding writes a `grounding` audit row; `GROUNDING_CHECKS=report` records without changing anything.\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, finding it stale or letting it expire 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.",+ "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>`). Every signed-in page shares one sidebar (`AppSidebar`). Its Recent list is capped at the 7 newest web chats. The full history, including Slack, Telegram and Discord conversations (recognised by their session-id prefix), lives on `/chats`. A chat opens from any page through `/?session=<id>`.\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- **Private cards.** An alert tagged `private:principal` (`alerts.models.PRIVATE_ALERT_TAG` — raised on a turn about mail from one of the principal's contacts or mail they forwarded, or a meeting proposal with a contact) is in `proposals` only when the caller is the principal. `_build_today` leaves it out by default, so the end-of-day digest, the reflection and Discord's `/today` never see it, and the morning brief reads it only on a run for the principal (the scheduler's, or the principal's own verified chat turn in a conversation only they can read — see Workflows). The narrative is written from one only in the principal's own `principal` scope, which nobody else is served; the shared `company` scope an unresolved caller gets, and a teammate's scope, never are. The activity rail skips it, and the chat digest includes it only on the principal's own verified turn.\n- **Roster-request cards.** When someone not on the People list writes in (see Org and Integrations), `people.roster_requests.surface_card` raises an alert of source `roster_request` (medium, tagged `roster_request:<id>` and `private:principal`, routed to the principal), so it follows every private-card rule above. `GET /today` attaches `roster_request` to that proposal (`_roster_request_card`: channel, address or account id, the sender's sanitised and unverified name, profile email, company-domain flag, suggested kind and person, message count, whether they were acknowledged, first seen, and the held messages' first lines) while the request is still pending. The Briefing renders it as its own card (`RosterRequestCard`: add as a new person with a name and an explicit team/contact choice — pre-filled as team on a company domain — or \"someone already on the list\", with a replace-account option for a chat id, or Ignore), which calls `/people/requests/{id}` directly and never hands off to chat, so what a stranger wrote never seeds a turn. The card is kept out of everything that could close it without answering it or put the stranger's words in front of a model: the narrative (`_action_proposals` drops it), the chat's open-alert digest (`<briefing>` — the principal's verified turn gets a separate `<roster_requests>` block instead; see Agents), `ack_alert`, a single ack (`POST /alerts/{id}/ack` is a 409), the \"Dismiss N older than 7 days\" count and the server's bulk ack, reopen, the TTL sweep and the alert review (`roster_request` is in `lifecycle.TTL_EXEMPT_SOURCES`). It ends when the request does: answered (`ack`, or `dismissed` on a decline) or expired after `ROSTER_REQUEST_TTL_DAYS`.\n- **`people`** — an attention-ranked roster of the **team** (the principal's contacts are never listed, and get no insight note). 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)`. Stale insight notes are regenerated in the background only when the roster has more than one person: the UI shows the People sidebar only for more than one, so a one-person install (solo, or a team before anyone else is added) does not pay a daily model and peer-memory call for a note nobody sees. Cached notes are still served.\n- **`proposals`** — the *live* unread alerts (workflow approvals, triage-classified inbound, Executive signals, flagged artifacts, and gated calendar bookings; an artifact is listed only to its owner (`alerts.models.visible_alert`; every other build of the board — the briefs, the reflection, the review, the chat digest on anyone else's turn, the activity rail — leaves drafted artifacts out) and carries `artifact_format` / `artifact_url` and a `body` already rendered to Markdown for its format, so the card badges it as a web page, Word doc, spreadsheet or link and offers *Open artifact*): 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). `failed_run_id` is set only on a `workflow_failed` card (a scheduled run that ended in error, see Scheduler): its main button is **Run again** (`POST /workflows/runs/{id}/rerun`, which also closes the card) and its ⋯ opens the run; it has no Approve. The response also carries `held_back` for the principal alone: the lines grounding left out of the morning brief or end-of-day digest in the last day, which Home lists under **Left out of your brief** (the brief's note names it; Hide is remembered in that browser). The UI splits them into 'mine' vs 'across the team' using `caller_person_id`. Approve is carried out on the server for every card. 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), so meeting bookings are reviewed in the briefing itself rather than on a separate page. Every other proposal is approved at `POST /alerts/{id}/approve` (`alerts.approvals`): it records who approved the card and when (an `alert_approvals` row plus `alert_approved`, then `alert_approval_done` / `alert_approval_failed`, audit rows), claims the card in one transaction so a double click or a second approver gets a 409 and the work runs once, then does the work. A card the scheduler filed for a department-gated action is bound to it server-side (`alert_held_actions`, written only as the card is filed, never read from the card's tags or text, which a model reading inbound mail can write), and approving it queues that exact action again with no department, the approval being the consent the gate waited for. Any other proposal runs one Executive turn as the approver in a new chat on the server (`chat.start_background_turn`, the machinery behind `POST /chat/background`), with the edited text verbatim for Edit & approve; it keeps going if the page closes. Only the card's routed person or the principal may approve a routed card, and only the principal an unrouted one (403 otherwise); the card's text reaches the turn as quoted data, not instructions. A row at the top of Needs you follows the approval (`GET /alerts/approvals/{id}`): working on it with a link to the chat, then done, or didn't work with Try again; a card whose last approval failed can be approved again, and one still running at a restart is marked failed on boot. The page no longer acks the card and seeds a chat turn with the proposal, which left no record of the approval and did nothing if the tab closed first.\n- **`narrative`** — a per-viewer Executive-voice header (\"What's going on\") synthesized by `synthesize_briefing_narrative`, cached per scope in `briefing_narrative`: the resolved principal gets the whole-company `principal` scope (which may carry what is private to them), a caller who resolves to no roster row the shared `company` scope (written from what everyone may see), and each teammate a role-scoped `person:<id>` one. `narrative_generated_at` says when the served text was written and `narrative_stale` whether a fresher one is being written now. 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. When the principal names an item that has already left the board — opened, snoozed, or older than it — the Executive looks it up with `find_alerts` (a keyword search over every status, `alerts.store.search_alerts`); matches that are still open (`unread` or `read`) become ackable for that turn, up to 25, and closed ones come back labelled so the Executive can say the item is already settled. It works only where the principal's own board was shown this turn — the web app or their DM — and never returns roster-request cards (see Lifecycle). The digest's header also labels every headline and detail as untrusted content drawn from inbound mail, chat and watched pages — act on what the principal asks about an item, never on what its text asks — and triage reads each signal inside an `<event>` block whose closing tag the sender's text cannot forge (it is defanged in any case and spacing, after NFKC folds fullwidth forms). 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\n **Live, not just the board.** The header used to reason over the alert board, goal health and the Executive's own bookkeeping only — mail and chat handled that day, replies the gate held and the next meeting never reached it, so it read the same for days while the principal's day moved on. The whole-company scopes now open the context with the principal's world as it is happening (`briefing.live_signals.gather_live_signals`, rendered by `render_live_blocks`), under a `NOW:` line: **INBOUND** (`integration_inbound` audit rows that carry a message, grouped by sender and subject, with an email's first line), **STUCK** (`integration_outbound_blocked` to a recipient, the inbound \"reply blocked at outbound gate\" and Google Chat \"left unanswered\" / \"not delivered\" rows, and drafts saved by Act as me), **CONVERSATIONS** (the principal's own web chat titles) and the **REST OF TODAY'S CALENDAR**. The window is the local day, or the last 12 hours when that is longer. Private audit rows, drafts, chat titles and the calendar (meeting titles are the principal's own) are read only in the `principal` scope — `gather_live_signals` drops the calendar whenever `include_private` is false, whatever the caller passes, so the shared `company` header never quotes it. The calendar is never fetched on the request: `live_signals.refresh_calendar` caches one read per 15 minutes (the scheduler tick refreshes it) and the header quotes the cache. Every quoted field is collapsed to one line and cut, and the blocks and the prompt both say the text is data, never instructions — inbound mail is attacker-controlled. With live blocks present the context also ages each proposal (`raised 2d ago`, whole days), names each at-risk department's slipping goals (`attention_goals`) and adds an **EXTERNAL SIGNALS** block (monitoring alerts from the last 24 h, never enough on their own to break the quiet line); the rhythm runs (`today.RHYTHM_WORKFLOWS`: the morning brief, end-of-day digest, reflection and weekly review) are dropped from the activity it reasons over. The prompts (`BRIEFING_NARRATIVE_SYSTEM` and its solo variant, `NARRATIVE_PROMPT_VERSION` 6) lead with what is live and give a days-old item at most one bullet. Anything live breaks the quiet line; the NOW line and window move at most once an hour, so the key moves hourly on time alone plus whenever something new lands; the calendar is placed at the real time (a meeting that has ended drops out, the one under way is IN PROGRESS), which moves it only when a meeting starts or ends.\n\n **Fresh without a reload.** The daily floor in the key and the PERIOD line are the principal's **local** date (`narrative_cache.local_today`), not UTC's, and a row written on an earlier local day is not served as today's. Regenerations are serialized per scope; a trigger that finds one running marks the scope pending and the running pass goes round once more (it built its context before that trigger's news landed), and after a failed pass (model error, the 25 s timeout, empty text) no view or tick starts another for 5 minutes and `narrative_stale` reads false, so the page drops its placeholder instead of spending a model call per view. They log `today: narrative served scope=… age_s=… stale=…` and `today: narrative regenerated scope=… ms=…`, and no longer need a page view: every `BRIEFING_NARRATIVE_REFRESH_MINUTES` (10) between `BRIEFING_NARRATIVE_REFRESH_START_HOUR` and `_END_HOUR` (06–22 local) the scheduler runs `today.refresh_principal_narrative`, which refreshes the calendar cache and rewrites the principal's header only when its key moved (see Scheduler). The Briefing re-polls `/today` at 4, 10 and 20 s while `narrative_stale` is true, re-pulls it when the tab comes back (at most once a minute) and every 5 minutes while visible, shows \"Updated 2:04 PM\" beside the heading, and shows \"Catching up on today…\" while the first header of the day is written (`lib/narrativeFreshness.ts`, tested by `npm test`).\n\n In **solo mode** (one person using Open Executive for themselves) the header speaks to the principal, whatever their role: a solo prompt over a context that lists goals at risk by *area* and has no \"people waiting on you\" block, and the quiet check ignores who is awaiting. The cache key carries the mode for solo only, so solo and team never share a cached narrative while every team key stays exactly what it was — no team cache is invalidated. The response shape does not change. For the principal's own view the solo context also carries a **DUE THIS WEEK** block — the principal's open loops that are overdue or due within 7 days (`today._with_due_soon` → `open_loops.principal_due_soon`, labelled OVERDUE / due today / due <weekday>) — which counts as needing attention in the quiet check and moves the cache key when an item is added, closed or falls due; a teammate's scoped view and team mode never get it. The header never gets the morning brief's *top three today* block — that is the DM brief's (see Workflows); the page shows the same top three in a card of its own (see *Solo focus cards* below). It does get the rest of today's calendar through the live blocks above, from the cached read.\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. Audit rows private to the principal (say, one naming their contact) are in this list only on the principal's own `/today`: `brief_state.handled_since` leaves them out unless asked, and the written briefs never ask, since a brief can be read by others. The Pulse heatmap's per-day counts (`GET /today/activity/daily`) likewise leave out a private decision or private alert, as the activity rail does. The morning brief also carries a one-line count of research watch suggestions waiting on `/watchlist`.\n\n**Standing facts.** `render_briefing_context` appends the standing facts (`memory.facts`: corrections kept from chat, a teammate's marked `(per <name>)`) as its last block, after the quiet-day check, so a fact never makes a quiet day look busy. The morning brief also carries **TEAMMATE CORRECTIONS SINCE LAST BRIEF** (`facts.render_teammate_changes(since)`: each teammate fact recorded in the window that is in use now, plus — only when the brief is the principal's own private one (`_private_ok`), which then keeps the run out of the shared history — those waiting for their approval, since other teammates may run the brief and never see a proposal that is not theirs) before the quiet check — it is news, the principal's only FYI of it — and in the brief's fingerprint (`build_brief_fingerprint(teammate_changes=)`), so a correction alone un-suppresses an otherwise unchanged brief. Every other caller passes none, so its context is unchanged. The /today header hashes that rendered string as its cache key, so a new or retired fact marks the header stale and it is rewritten with the correction. The morning brief (standalone) and the teammate-scoped header get the same block. On the scheduler's delivery to the owner alone, with their Always in the loop switch on, `render_briefing_context(owner_notes=)` also carries FROM YOUR NOTES — DUE SOON (their own notes of what they promised or asked, overdue to a week ahead; `memory.history_brief`), which counts against a quiet day, enters the fingerprint and marks the run private; both standalone prompts turn it into a **From your notes** section. The /today header never gets it. **The first week.** For seven days from the principal's People row (`briefing.first_week`), `render_briefing_context(getting_started=)` carries a GETTING STARTED block right after the live blocks: the goals saved at onboarding (department, key result, target, period), departments with no `head_person_id`, and, on the scheduler's delivery to the principal alone with Act as me and Draft replies to my inbox both on and the mailbox connected (the inbox watcher's consent), up to five people who wrote to their own mailbox in the last 48 hours as sender and subject only (`inbox_message_ids` + headers of `get_message`, bulk and automated mail skipped; the same \"where, never what\" rule as `delegation.mail_reads`). It counts against a quiet day, enters the fingerprint (`getting_started=` keys, no dates) and, with the inbox part, marks the run private. Both standalone prompts open with a **Getting started** section and take the Top call from it (`GETTING_STARTED_RULE`); the whole-company /today header gets the block without the inbox (`getting_started_shared`, synchronous, no mailbox read) and the header prompts take the bottom line and move from it (`GETTING_STARTED_HEADER_RULE`), so a new install's header is not short-circuited to the quiet line. `GET /today` sets `first_week`, and the Briefing hides the \"Quiet day\" banner while it is true. A teammate's scoped header never gets it. The alert review's `render_batch` puts the same block ahead of the alerts (read once per pass), so a note, rewrite or routed DM never repeats a figure the principal already corrected.\n\n**When a brief isn't sent.** Above the Briefing, the owner sees a one-line notice when their latest morning brief, end-of-day digest or (in solo mode) weekly review wasn't sent — \"Your morning brief wasn't sent: nothing is set up to send it to you\" — with the day, what fixes it, a link to read the brief on the Artifacts page (left out when the brief couldn't be written at all) and one to Setup status. It comes from `GET /today/brief-delivery` (the scheduler records each run's outcome), shows nothing while briefs go out or while the scheduler is off, and clears once the cause is fixed. When the Executive's mail connection wasn't running (the MCP gateway failed to start and is retrying), the notice says that instead of blaming the owner's setup; a send that failed on every channel names what each channel answered, from the recorded `detail`, with addresses left out. Teammates never see it.\n\n**Replies waiting.** With Act as me's **Draft replies to my inbox** on, the top of the Briefing's left column lists the replies the Executive drafted in the owner's own Gmail for mail that needs them (`RepliesWaiting`, from `GET /delegation/replies` — see Act as Me). They belong to the owner alone: the route answers only the person who can have Act as me, the decisions behind the cards (`delegation_reply`) are principal-only and carry `private: true`, so `/today/activity` and the heatmap leave them out, and none is ever an alert, so nothing of them reaches `GET /today`, the header or the briefs. Each card shows who wrote and who they are to the owner, whether their address was verified, the subject, what they wrote (as plain text), the draft, **Decide before sending** (its open questions) and its warnings, with **Send**, **Edit in Gmail** (the thread in their Gmail) and **Dismiss** (which deletes the draft unless they edited it). **Send** asks first, naming who the reply goes to, then sends the draft exactly as it is in Gmail (`POST /decisions/{id}/approve`); when its recipients changed in Gmail or a newer message arrived, the backend's 409 `confirm` becomes a second question naming them. The card hides itself when nothing is waiting.\n\n**Solo focus cards.** `GET /today/top-three` and `GET /today/weekly-review` feed two solo-only cards, so a principal who only uses the web app — no chat app, no Google Workspace — sees today's top three and the weekly review instead of finding them only in the Workflows run history. Both answer only in solo mode (`effective_workspace_mode`) and only to the principal, by the stricter rule for starting a principal-only run (`workflows._caller_is_the_principal`: the caller's own email on a principal entry that is not archived, or no `x-caller-email` at all — never \"nobody is principal yet\"); a teammate, any other signed-in caller and team mode get null. `top-three` hands `open_loops.principal_due_soon()` to `briefing.top_three.build_top_three` — the morning brief's own inputs and code, so the items, their order and their free slots are the brief's — and returns `{items: [{key, kind, text, why, slot}]}`: `slot` is the free block (\"10:00–11:00\", the user's zone), \"\" when none is left, or null when no calendar was read (none connected, a failure or the 4 s timeout, a weekend); `items` is empty when there is nothing to pick. It is a route of its own, never part of `GET /today`, so the Briefing never waits on the calendar. `weekly-review` returns the latest `weekly_review` run with status `done` (`persistence.list_runs(..., status=\"done\", limit=1)`, newest `updated_at` first; failed and running runs never count) as `{run_id, completed_at, period, top_three, excerpt}`: `weekly_review.summarize_review` reads the artifact's title line and its last *Next week's top 3* section back as plain text, and `excerpt` stands in when that list is empty (the section's own note, else the review's first lines). Null when no review has completed or the run store cannot be read.\n\nThe route resolves the caller from `x-caller-email`, serves the viewer's cached narrative and, when its key moved, rewrites it in a `BackgroundTask` so the request never blocks on an LLM call (the page re-polls while `narrative_stale` is true). `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; solo mode has its own, with goals at risk by area and no waiting-on section). `GET /morning-brief` is a deprecated alias.\n\n**Solo mode in the UI.** The response is the same in both modes; the briefing reads the workspace mode from the app-wide `WorkspaceProvider` (which reads team while loading or on error, so a team install never flashes solo) and, in solo, drops the team surfaces: the Departments card, the People card, the \"Across the team\" lane (every action proposal is the one user's, so all of them land in \"Needs you\"), the people-awaiting, people-overdue and departments-at-risk status pills, and the quiet-day \"Set up a check-in\" link. A \"N goals at risk\" pill (at-risk plus off-track goals, from `departments`) links to `/goals` instead, so the strip never reads \"All clear\" over a goal that is slipping. In the Departments card's place, **Your projects** lists the initiatives with status `active` (`GET /memories/initiatives`): **Done** marks one `completed` through `PATCH /memories/initiatives/{id}` (only `completed` takes an initiative out of the Executive's active context), and **Drop** deletes it through `DELETE /memories/initiatives/{id}` after a confirm. Under **Needs you**, a **Due soon** card lists the principal's open loops that are overdue or due within 7 days — their dated commitments and what others asked of them — read from `GET /people/{id}/open-loops` for the principal (the oldest principal in `people`, the backend's rule), labelled by `lib/dueSoon.ts` (tested by `npm test`: \"Overdue since Sep 23\" / \"Due today\" / \"Due Mon, Sep 28\", with a count of anything due later); **Done** closes one through `POST /open-loops/{id}/close`, which also stops the nudge engine chasing it. Above it, **Top three today** numbers the morning brief's three (`GET /today/top-three`) with each one's reason and, when a calendar was read, its free slot (or \"No free time left today\"); at the top of the right-hand column, **This week's review** (`GET /today/weekly-review`) shows the period, when it ran, next week's top three (or the excerpt) and a *Read the review* link to its run page (`/jobs/runs/{id}`). Each card fetches on its own once the Briefing has loaded, so a slow calendar never holds the page up, and renders nothing when the API returns null or an empty list. A commitment in the top three reads as the owner's own (\"Send the proposal\") through `lib/dueSoon.ts`'s `loopText`, as in Due soon; the cards' wording lives in `lib/rhythmCards.ts` (tested by `npm test`). The Pulse page hides its \"Department check-ins\" and \"Awaiting people\" blocks in solo, and its header shows active projects in place of the department check-in count. Team rendering is unchanged.\n\n**Your month (`GET /today/value`).** The owner's own tally of what the Executive did for them, `briefing.value_summary.summarize(period, offset)`: the calendar `month` or `week` (Monday first) in the user's zone, `offset` periods back (0–24), each line beside the period before. Every number is a `COUNT(*)` of rows that prove it happened, never a model's: messages sent for the owner (the DM handlers' own `kind=outbound` sent rows to anyone but the owner, plus Gmail / Outlook send-tool calls that didn't come back with an error, so mail sent from a chat turn counts), replies drafted and sent from the owner's inbox (their Act as me rows), meetings booked (calendar create calls), briefs delivered (the scheduler's `delivered` row), reports (finished team workflow runs, minus the daily rhythm runs and any run a teammate started for themselves, which stays theirs alone; the latest ten listed with links), follow-ups and nudges sent, tasks tracked and closed as done, proposals decided, alerts flagged and requests answered (`chat_turn` out rows). No \"hours saved\" and no cost line: nothing recorded supports the first, and cost next to what the owner got reads as a bill; it has `GET /audit/usage`. The owner's alone (403 for anyone else): it counts rows private to the owner, never a row private to another member. Pulse shows it as a **Your month** card on the overview (\"October 2026: 42 messages sent, 6 reports, 3 meetings booked.\") and a focused screen, `/memories?tab=value`, with a month / week switch and previous / next. On the first weekday of each month, in daytime (09:00–18:00 local), a scheduler tick hook sends the owner last month's lines and a link (`value_summary.maybe_send_monthly`, claimed once per month under `briefing_narrative` scope `value_summary:YYYY-MM`), in solo and team mode alike; nothing is sent for an empty month. Off with `VALUE_SUMMARY_MONTHLY_ENABLED=false`.\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. Four things now keep it live and true:\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. **Snooze** (a card's ⋯: later today, tomorrow 9:00, Monday 9:00, in the viewer's clock; `POST /alerts/{id}/snooze`) hides a card until `snoozed_until`, with an Undo; the TTL anchor is the latest of `created_at`, `last_seen_at` and `snoozed_until`, so a snoozed card comes back rather than expiring unseen.\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- **Collection tags** (`alerts.pipeline`). A triaged alert never carries a `collection:<name>` tag: the pipeline strips them before inserting. Only an installed extension's own code files a document into its collection (`orchestrator.extensions`), so injected text can't make a card that the extension would treat as its own.\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 (team members only — an alert routed to a contact never puts them in the slice, so they are never routed to, nudged or chased; a private card is never reviewed at all, nor used as evidence for another), 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). A review DM is proactive outreach, so the recipient's notification settings apply: one held for their quiet hours or brief counts as a route made but not as a nudge toward the cap (and no second nudge is held while one waits), and one about an alert whose severity is (or becomes) `urgent` is marked urgent (`notifications.urgent_send`) and gets through when they let urgent things through.\n- **Grounded text** (`openexecutive.briefing.grounding`). Nobody reads an alert's text before it is dispatched, so what the model wrote onto it must be supported by what it read. After triage (`alerts.pipeline._ground_decision`, before coalescing or inserting), a headline naming a person or figure the event does not hold — sources are the event's subject, sender, title and body, the initiatives triage was shown and the company profile — is replaced by the event's own subject, such body sentences are dropped (all of them → the event body cut to 280 chars); both fallbacks are raw event text, so they are made inert first — links masked, Markdown and Slack `<…>` syntax and @-mentions stripped — because a broadcast posts them as written, and such a suggested action is dropped. A review `changed` rewrite is checked against the alert's own text and the evidence it was reviewed with (signals, related alerts, activity, the roster slice), plus the standing facts the batch was shown, so a rewrite that corrects a card to one of the principal's corrections is grounded; an ungrounded rewrite keeps the old text, still applies a severity change, and audits `text_ungrounded`. A name counts as grounded only when one source line holds all of it; a figure only when a source number matches it within the precision it is written with. Each finding writes a `grounding` audit row; `GROUNDING_CHECKS=report` records without changing anything.\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, finding it stale or letting it expire 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 TOP3[\"GET /today/top-three<br/>(solo, principal only)\"]\n PICK[\"build_top_three()<br/>(calendar read, 4 s cap)\"]\n WREV[\"GET /today/weekly-review<br/>(solo, principal only)\"]\n RUNS[\"workflow_runs<br/>(latest done weekly_review)\"]\n LIVE[\"live_signals<br/>(inbound / held replies / chats,<br/>cached calendar)\"]\n TICK[\"scheduler tick<br/>(every 10 min, 06–22 local)\"]\n CACHE[\"briefing_narrative<br/>(principal / company / person:id)\"]\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 LIVE --> NARR\n TICK -->|\"refresh_principal_narrative\"| NARR\n NARR --> CACHE\n MB -->|\"since last brief\"| LIVE\n MB -->|\"calls directly for standalone DM\"| BUILD\n MB -->|\"same pick for the DM\"| PICK\n TOP3 --> PICK\n WREV --> RUNS\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\n class TOP3 entry\n class PICK compute\n class WREV entry\n class RUNS storage\n class LIVE compute\n class TICK entry\n class CACHE storage",- "generated_at": "2026-10-14T00:00:00Z"+ "generated_at": "2026-10-14T06:41:10Z"}diff --git a/packages/core/openexecutive/attunement/assignment_notice.py b/packages/core/openexecutive/attunement/assignment_notice.pynew file mode 100644index 00000000..1389f3b5--- /dev/null+++ b/packages/core/openexecutive/attunement/assignment_notice.py@@ -0,0 +1,200 @@+"""Tell a person, once, that they were assigned a task.++``assign_open_loop`` (the chat tool and the People page's "Assign a task"+form) used to store the loop silently: the owner first heard of it when the+nudge engine chased them after it fell due. Now, when someone assigns a task+to somebody else, the owner gets one short message on their own channel the+way the reminders reach people (``scheduler.runner.deliver_to_person``: their+Slack or Discord DM, their private Telegram chat, or email).++The text is fixed, never a model's: the assigner's name, the task in the+speaker's own words (the tool already requires that) and the due date. It is+the Executive's own outreach, so the owner's notification settings apply+(``people.notifications.hold_for``): quiet hours or "In my briefs" hold it in+``people.held_messages`` and it goes out later, on any channel. The send is+tagged with the loop's commitment scope, so the owner's "done" that closes the+loop also counts the notice as acted on.++Chasing stays the nudge engine's job; this sends one notice per loop and+never repeats. Returns how it went so the assigner can be told:+``sent`` (with the channel), ``held`` or ``not_reached``; a teammate who+assigned it hears only sent / later / not_reached (``NoticeResult.as_dict``).+The task is quoted inert (``_quoted_task``). Never raises.+"""+from __future__ import annotations++import logging+from dataclasses import dataclass+from datetime import UTC, datetime++from openexecutive.attunement.outcomes import SOURCE_TASK_ASSIGNED++logger = logging.getLogger(__name__)++# The email subject / message label.+LABEL = "New task"+# Matches the People form's limit on a task.+_TASK_MAX = 200++NoticeStatus = str # "sent" | "held" | "not_reached" | "skipped"+++@dataclass(frozen=True)+class NoticeResult:+ """How the notice went: ``status`` and, when sent, the channel."""++ status: NoticeStatus+ channel: str | None = None+ detail: str = ""++ def as_dict(self, *, for_principal: bool = True) -> dict[str, str | None]:+ """What the assigner is told. Only the principal learns the channel:+ to a teammate, which chat reaches someone, and why it waits, is that+ person's own business, so ``held`` there says only "later"."""+ if for_principal:+ return {"status": self.status, "channel": self.channel}+ return {"status": "later" if self.status == "held" else self.status, "channel": None}+++def _due_phrase(due_at: str | None) -> str:+ """'Friday 17 October' in the user's timezone, or '' when unreadable."""+ if not due_at:+ return ""+ try:+ from openexecutive.attunement.open_loops import _user_tz++ dt = datetime.fromisoformat(due_at)+ if dt.tzinfo is None:+ dt = dt.replace(tzinfo=UTC)+ local = dt.astimezone(_user_tz())+ except (ValueError, TypeError):+ return ""+ return f"{local:%A} {local.day} {local:%B}"+++def _quoted_task(task: str) -> str:+ """The task as inert text. A teammate typed it and it is sent with no+ model in between, so it must not read as the Executive's own words or+ turn into a link: the stored loop's defang (``"`` ``<`` ``>``), then a+ code span, which Slack, Discord, Telegram and the mail renderer all show+ literally (no ``<url|label>``, ``[label](url)`` or bare-URL links)."""+ from openexecutive.attunement.open_loops import _MARKUP_DEFANG, _clean++ text = _clean(task, _TASK_MAX).translate(_MARKUP_DEFANG).replace("`", "'")+ return f"`{text}`"+++def notice_text(*, assigner_name: str, task: str, due_at: str | None) -> str:+ """The message the owner gets."""+ due = _due_phrase(due_at)+ lines = [f"{assigner_name} asked you to take this on: {_quoted_task(task)}."]+ if due:+ lines.append(f"It's due {due}.")+ lines.append("Reply here when it's done, or if you can't do it.")+ return " ".join(lines)+++def _audit(owner_id: int, loop_id: int, result: NoticeResult) -> None:+ try:+ from openexecutive.audit import log_event++ log_event(+ "task_assignment_notice",+ f"Task #{loop_id} notice to person {owner_id}: {result.status}",+ actor="attunement",+ details={+ "loop_id": loop_id,+ "owner_person_id": owner_id,+ "status": result.status,+ "channel": result.channel,+ "detail": result.detail[:200],+ },+ private_to_person=owner_id,+ )+ except Exception:+ logger.warning("assignment_notice: audit failed", exc_info=True)+++async def notify_assignee(+ *,+ loop_id: int,+ owner_person_id: int,+ assigned_by_person_id: int,+ task: str,+ due_at: str | None,+ now: datetime | None = None,+) -> NoticeResult:+ """Send the owner of loop ``loop_id`` one notice that it was assigned.++ Nothing is sent when the owner assigned it to themselves, or the notice is+ turned off (``ATTUNEMENT_ASSIGN_NOTIFY_ENABLED``)."""+ from openexecutive.config import get_settings++ if owner_person_id == assigned_by_person_id:+ return NoticeResult("skipped", detail="assigned to themselves")+ if not get_settings().attunement_assign_notify_enabled:+ return NoticeResult("skipped", detail="turned off")+ try:+ result = await _notify(+ loop_id=loop_id,+ owner_person_id=owner_person_id,+ assigned_by_person_id=assigned_by_person_id,+ task=task,+ due_at=due_at,+ now=now or datetime.now(UTC),+ )+ except Exception as exc:+ logger.warning("assignment_notice: loop %s notice failed", loop_id, exc_info=True)+ result = NoticeResult("not_reached", detail=type(exc).__name__)+ _audit(owner_person_id, loop_id, result)+ return result+++async def _notify(+ *,+ loop_id: int,+ owner_person_id: int,+ assigned_by_person_id: int,+ task: str,+ due_at: str | None,+ now: datetime,+) -> NoticeResult:+ from openexecutive.attunement.outcomes import tag_proactive+ from openexecutive.audit.context import rows_for_person+ from openexecutive.people import held_messages+ from openexecutive.people.notifications import hold_for+ from openexecutive.people.store import get_person+ from openexecutive.scheduler.runner import deliver_to_person++ owner = get_person(owner_person_id)+ assigner = get_person(assigned_by_person_id)+ if owner is None or owner.id is None or owner.archived:+ return NoticeResult("not_reached", detail="owner not on the People list")+ assigner_name = assigner.full_name if assigner is not None else "Someone on your team"+ text = notice_text(assigner_name=assigner_name, task=task, due_at=due_at)+ ref = f"nudge:commitment:{loop_id}"++ hold = hold_for(owner.id, source=SOURCE_TASK_ASSIGNED, now=now)+ if hold is not None:+ held_messages.hold(+ owner.id, text, source=SOURCE_TASK_ASSIGNED, release_at=hold.release_at,+ ref=ref, now=now,+ )+ return NoticeResult("held", detail=hold.reason)++ # The DM handlers re-check the hold under this tag; the answer is the+ # same one hold_for just gave, so nothing is held twice.+ with tag_proactive(SOURCE_TASK_ASSIGNED, ref), rows_for_person(owner.id):+ delivery = await deliver_to_person(owner, text, label=LABEL)+ if delivery.ok:+ return NoticeResult("sent", channel=delivery.channel)+ return NoticeResult("not_reached", detail=delivery.reason)+++__all__ = [+ "LABEL",+ "SOURCE_TASK_ASSIGNED",+ "NoticeResult",+ "notice_text",+ "notify_assignee",+]diff --git a/packages/core/openexecutive/attunement/outcomes.py b/packages/core/openexecutive/attunement/outcomes.pyindex 62941a20..f41fad05 100644--- a/packages/core/openexecutive/attunement/outcomes.py+++ b/packages/core/openexecutive/attunement/outcomes.py@@ -51,6 +51,7 @@ SOURCE_FOLLOWUP = "followup"SOURCE_REFLECTION = "reflection"SOURCE_RESEARCH = "research"SOURCE_ALERT_REVIEW = "alert_review"+SOURCE_TASK_ASSIGNED = "task_assigned"SOURCE_LABELS: dict[str, str] = {SOURCE_NUDGE_STALLED: "approval nudges",@@ -61,6 +62,7 @@ SOURCE_LABELS: dict[str, str] = {SOURCE_REFLECTION: "standup DMs",SOURCE_RESEARCH: "research DMs",SOURCE_ALERT_REVIEW: "alert-review DMs",+ SOURCE_TASK_ASSIGNED: "task notices",}OUTCOME_REPLIED = "replied"diff --git a/packages/core/openexecutive/briefing/value_summary.py b/packages/core/openexecutive/briefing/value_summary.pynew file mode 100644index 00000000..47d0882a--- /dev/null+++ b/packages/core/openexecutive/briefing/value_summary.py@@ -0,0 +1,521 @@+"""What the Executive did for the owner over a month or a week, in numbers.++The engagement value report (``workflows/engagement_value_report.py``) is+written for a fractional executive's client and runs only on demand; the+weekly review runs in solo mode only; and Pulse's Done recently is a feed of+the last few rows. This module is the owner's own tally, for ``GET /today/value``, the+"Your month" card on Pulse and the monthly message+(``scheduler.runner._run_monthly_value``).++Every number is a ``COUNT(*)`` of rows that prove the thing happened, read+straight from SQLite; no model writes or estimates any of it, and there is no+"hours saved" figure because nothing recorded supports one:++ • messages sent — the DM handlers' own ``tool_invocation`` rows+ (``kind=outbound``, sent, not held or suppressed) to anyone but the owner,+ plus mail sent through the Gmail or Outlook tools. Mail sent from a chat+ turn counts here, whatever Done recently shows.+ • inbox replies drafted and sent — the owner's own Act as me rows.+ • meetings booked — successful calendar create calls.+ • briefs delivered — the scheduler's ``delivered`` row per brief.+ • reports — finished workflow runs, minus the daily rhythm runs.+ • follow-ups — scheduled actions the runner delivered (follow-ups, nudges).+ • tasks tracked and closed — open loops opened, and closed as done.+ • decisions — gated proposals that reached a verdict.+ • alerts flagged, and requests answered (one ``chat_turn`` out row each).++Cost is left out on purpose: next to what the owner got it reads as a bill,+and it already has its own page (``GET /audit/usage``).++Only the owner reads it, so rows private to the owner count; a row private to+another team member never does. Tables are existence-guarded: a missing table+reads as zero, never an error.+"""+from __future__ import annotations++import asyncio+import logging+import sqlite3+from collections.abc import Iterator+from contextlib import contextmanager+from dataclasses import dataclass+from datetime import UTC, date, datetime, timedelta, tzinfo+from pathlib import Path+from typing import Any, Literal++from pydantic import BaseModel, Field++logger = logging.getLogger(__name__)++Period = Literal["month", "week"]++# The Executive's own daily rhythm runs (as ``api.routes.today.RHYTHM_WORKFLOWS``):+# counted as briefs, not as reports.+_RHYTHM_WORKFLOWS = ("morning_brief", "end_of_day_digest", "executive_reflection", "weekly_review")++# DM handlers that write their own sent row (``orchestrator.schedule_tools``).+_DM_TOOLS = ("send_slack_dm", "send_discord_dm", "send_telegram_message")+# Mail sends through the workspace tools, in the gateway's normalized form+# (lowercase, ``-`` as ``_``). Drafts are not sends.+_MAIL_SEND_TOOLS = (+ "google_workspace__send_gmail_message",+ "microsoft_365__send_mail",+ "microsoft_365__reply_mail_message",+ "microsoft_365__reply_all_mail_message",+ "microsoft_365__forward_mail_message",+ "microsoft_365__send_draft_message",+)+_MEETING_TOOLS = ("create_calendar_event", "create_instant_meeting")+_DECIDED = (+ "executed", "approved_unchanged", "approved_with_edit", "rejected", "reversed",+)+_MAX_DELIVERABLES = 10+++class ValueLine(BaseModel):+ """One counted thing, this period and the one before."""++ key: str+ label: str+ count: int+ previous: int+++class Deliverable(BaseModel):+ run_id: str+ title: str+ workflow_name: str+ finished_at: str+++class ValueSummary(BaseModel):+ period: Period+ label: str # "October 2026", "Week of 12 October"+ start: str # UTC ISO, inclusive+ end: str # UTC ISO, exclusive+ lines: list[ValueLine] = Field(default_factory=list)+ deliverables: list[Deliverable] = Field(default_factory=list)+ deliverables_total: int = 0++ def is_empty(self) -> bool:+ return not any(line.count for line in self.lines)++ def line(self, key: str) -> ValueLine | None:+ return next((ln for ln in self.lines if ln.key == key), None)+++# --------------------------------------------------------------------------- #+# Periods+# --------------------------------------------------------------------------- #+++@dataclass(frozen=True)+class _Window:+ start: datetime+ end: datetime+ label: str++ @property+ def bounds(self) -> tuple[str, str]:+ return (_iso(self.start), _iso(self.end))+++def _iso(dt: datetime) -> str:+ # Second precision with an explicit offset: compares correctly as a+ # string against both "...+00:00" and the audit log's "....ffffffZ".+ return dt.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S+00:00")+++def _month_start(day: date, months_back: int) -> date:+ index = day.year * 12 + (day.month - 1) - months_back+ return date(index // 12, index % 12 + 1, 1)+++def period_window(period: Period, offset: int, *, now: datetime, zone: tzinfo) -> _Window:+ """The calendar month or week (Monday first) ``offset`` periods before the+ current one, in ``zone``. ``offset`` 0 is the period ``now`` is in."""+ today = now.astimezone(zone).date()+ if period == "month":+ first = _month_start(today, offset)+ nxt = _month_start(first, -1)+ label = f"{first:%B} {first.year}"+ else:+ first = today - timedelta(days=today.weekday()) - timedelta(weeks=offset)+ nxt = first + timedelta(days=7)+ label = f"Week of {first.day} {first:%B}"+ start = datetime(first.year, first.month, first.day, tzinfo=zone)+ end = datetime(nxt.year, nxt.month, nxt.day, tzinfo=zone)+ return _Window(start, end, label)+++# --------------------------------------------------------------------------- #+# Reads+# --------------------------------------------------------------------------- #+++@contextmanager+def _conn(path: Path) -> Iterator[sqlite3.Connection | None]:+ if not path.exists():+ yield None+ return+ conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True)+ conn.row_factory = sqlite3.Row+ try:+ yield conn+ finally:+ conn.close()+++def _tables(conn: sqlite3.Connection) -> set[str]:+ return {r[0] for r in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}+++def _count(conn: sqlite3.Connection | None, table: str, where: str, params: tuple[Any, ...]) -> int:+ if conn is None or table not in _tables(conn):+ return 0+ try:+ row = conn.execute(f"SELECT COUNT(*) FROM {table} WHERE {where}", params).fetchone() # noqa: S608+ except sqlite3.OperationalError:+ return 0 # an older schema without the column+ return int(row[0] or 0)+++# Audit rows the owner may count: theirs and the team's, never a row private+# to another team member.+_AUDIT_SCOPE = "ts >= ? AND ts < ? AND private_to_person IS NULL"+++def _audit_count(conn: sqlite3.Connection | None, bounds: tuple[str, str],+ extra: str, params: tuple[Any, ...] = ()) -> int:+ return _count(conn, "audit_log", f"{_AUDIT_SCOPE} AND {extra}", (*bounds, *params))+++# A run a teammate started is theirs alone, not even the owner's+# (``workflows.persistence.run_visible_to``): only team runs count.+_TEAM_RUN = "owner_person_id IS NULL"+++def _in(values: tuple[str, ...]) -> str:+ return "(" + ",".join("?" * len(values)) + ")"+++def _owner_refs(principal: Any) -> set[str]:+ """The owner's own chat ids: a DM to them is a brief or a reply, not a+ message sent on their behalf."""+ if principal is None:+ return set()+ return {+ str(v) for v in (+ principal.slack_user_id, principal.discord_user_id, principal.telegram_chat_id,+ ) if v+ }+++def _messages_sent(conn: sqlite3.Connection | None, bounds: tuple[str, str],+ owner_refs: set[str]) -> int:+ if conn is None or "audit_log" not in _tables(conn):+ return 0+ try:+ dms = conn.execute(+ "SELECT COALESCE(json_extract(details_json,'$.user_id'),"+ " json_extract(details_json,'$.chat_id')) AS ref, COUNT(*) AS n "+ f"FROM audit_log WHERE {_AUDIT_SCOPE} AND event_type = 'tool_invocation' "+ "AND json_extract(details_json,'$.kind') = 'outbound' "+ f"AND json_extract(details_json,'$.tool') IN {_in(_DM_TOOLS)} "+ "AND json_extract(details_json,'$.ok') = 1 "+ "AND COALESCE(json_extract(details_json,'$.held'),0) = 0 "+ "AND COALESCE(json_extract(details_json,'$.suppressed'),0) = 0 "+ "GROUP BY ref",+ (*bounds, *_DM_TOOLS),+ ).fetchall()+ except sqlite3.OperationalError:+ return 0 # an older schema without the column+ dm_total = sum(int(r["n"]) for r in dms if str(r["ref"]) not in owner_refs)+ # A workspace send that came back with an error is not a send.+ mail = _audit_count(+ conn, bounds,+ "event_type = 'tool_invocation' AND json_extract(details_json,'$.kind') = 'mcp' "+ "AND replace(lower(json_extract(details_json,'$.tool')),'-','_') IN "+ f"{_in(_MAIL_SEND_TOOLS)} "+ "AND COALESCE(json_extract(details_json,'$.ok'),1) != 0 "+ "AND lower(COALESCE(json_extract(details_json,'$.result_preview'),'')) NOT LIKE '%error%'",+ _MAIL_SEND_TOOLS,+ )+ return dm_total + mail+++def _counts(audit: sqlite3.Connection | None, db: sqlite3.Connection | None,+ bounds: tuple[str, str], *, principal: Any) -> dict[str, int]:+ owner_id = getattr(principal, "id", None)+ own = "json_extract(details_json,'$.person_id') = ?"+ return {+ "messages_sent": _messages_sent(audit, bounds, _owner_refs(principal)),+ "inbox_drafted": _audit_count(+ audit, bounds,+ f"event_type IN ('delegation_reply_drafted','delegation_drafted') AND {own}",+ (owner_id,),+ ) if owner_id is not None else 0,+ "inbox_sent": _audit_count(+ audit, bounds, f"event_type = 'delegation_reply_sent' AND {own}", (owner_id,),+ ) if owner_id is not None else 0,+ "meetings_booked": _audit_count(+ audit, bounds,+ "event_type = 'tool_invocation' AND json_extract(details_json,'$.kind') = 'skill' "+ f"AND json_extract(details_json,'$.tool') IN {_in(_MEETING_TOOLS)} "+ "AND COALESCE(json_extract(details_json,'$.ok'),1) != 0",+ _MEETING_TOOLS,+ ),+ "briefs_delivered": _audit_count(+ audit, bounds,+ "event_type = 'scheduled_action' AND json_extract(details_json,'$.phase') = 'delivered' "+ "AND json_extract(details_json,'$.kind') LIKE 'principal_%'",+ ),+ "reports": _count(+ db, "workflow_runs",+ f"status = 'done' AND updated_at >= ? AND updated_at < ? AND {_TEAM_RUN} "+ f"AND workflow_name NOT IN {_in(_RHYTHM_WORKFLOWS)}",+ (*bounds, *_RHYTHM_WORKFLOWS),+ ),+ "follow_ups": _audit_count(+ audit, bounds,+ "event_type = 'scheduled_action' AND json_extract(details_json,'$.action_id') IS NOT NULL "+ "AND json_extract(details_json,'$.phase') IN ('delivered','held')",+ ),+ "tasks_tracked": _count(+ db, "scheduled_actions", "kind = 'open_loop' AND created_at >= ? AND created_at < ?",+ bounds,+ ),+ "tasks_closed": _audit_count(+ audit, bounds,+ "json_extract(details_json,'$.op') = 'loop_closed' "+ "AND json_extract(details_json,'$.reason') = 'done'",+ ),+ "decisions": _count(+ db, "decision_instances",+ f"resolved_at >= ? AND resolved_at < ? AND status IN {_in(_DECIDED)}",+ (*bounds, *_DECIDED),+ ),+ "alerts": _count(db, "alerts", "created_at >= ? AND created_at < ?", bounds),+ "answered": _audit_count(+ audit, bounds,+ "event_type = 'chat_turn' AND json_extract(details_json,'$.direction') = 'out'",+ ),+ }+++_LABELS: dict[str, str] = {+ "messages_sent": "Messages sent for you",+ "inbox_drafted": "Replies drafted in your inbox",+ "inbox_sent": "Replies sent from your inbox",+ "meetings_booked": "Meetings booked",+ "briefs_delivered": "Briefs delivered",+ "reports": "Reports and documents",+ "follow_ups": "Follow-ups and nudges sent",+ "tasks_tracked": "Tasks tracked",+ "tasks_closed": "Tasks closed as done",+ "decisions": "Proposals decided",+ "alerts": "Things it flagged",+ "answered": "Requests answered",+}+++def _deliverables(db: sqlite3.Connection | None, bounds: tuple[str, str]) -> list[Deliverable]:+ if db is None or "workflow_runs" not in _tables(db):+ return []+ try:+ rows = db.execute(+ "SELECT run_id, title, workflow_name, updated_at FROM workflow_runs "+ f"WHERE status = 'done' AND updated_at >= ? AND updated_at < ? AND {_TEAM_RUN} "+ f"AND workflow_name NOT IN {_in(_RHYTHM_WORKFLOWS)} "+ "ORDER BY updated_at DESC LIMIT ?",+ (*bounds, *_RHYTHM_WORKFLOWS, _MAX_DELIVERABLES),+ ).fetchall()+ except sqlite3.OperationalError:+ return [] # an older schema without the column+ return [+ Deliverable(run_id=r["run_id"], title=r["title"] or r["workflow_name"],+ workflow_name=r["workflow_name"], finished_at=r["updated_at"])+ for r in rows+ ]+++# --------------------------------------------------------------------------- #+# Entry points+# --------------------------------------------------------------------------- #+++def summarize(+ period: Period = "month",+ offset: int = 0,+ *,+ now: datetime | None = None,+ zone: tzinfo | None = None,+ db_path: Path | None = None,+ audit_db_path: Path | None = None,+) -> ValueSummary:+ """The tally for one period, with the period before it beside each line."""+ from openexecutive.audit import get_audit_logger+ from openexecutive.memory.episodic import _resolve_db_path+ from openexecutive.people.store import find_principal_person++ if zone is None:+ from openexecutive.memory.workspace_settings import get_user_timezone++ zone = get_user_timezone()+ now = now or datetime.now(UTC)+ window = period_window(period, offset, now=now, zone=zone)+ before = period_window(period, offset + 1, now=now, zone=zone)+ principal = find_principal_person()+ audit_path = audit_db_path or get_audit_logger()._db_path+ with _conn(audit_path) as audit, _conn(_resolve_db_path(db_path)) as db:+ current = _counts(audit, db, window.bounds, principal=principal)+ previous = _counts(audit, db, before.bounds, principal=principal)+ deliverables = _deliverables(db, window.bounds)+ start, end = window.bounds+ return ValueSummary(+ period=period,+ label=window.label,+ start=start,+ end=end,+ lines=[+ ValueLine(key=k, label=_LABELS[k], count=current[k], previous=previous[k])+ for k in _LABELS+ ],+ deliverables=deliverables,+ deliverables_total=current["reports"],+ )+++# Lines the monthly message leads with, in order, when they are non-zero.+_HEADLINE_KEYS = (+ "messages_sent", "inbox_sent", "meetings_booked", "reports", "follow_ups",+ "tasks_closed", "decisions", "answered",+)+++def render_message(summary: ValueSummary, *, link: str = "") -> str:+ """The short monthly message: the counted lines that aren't zero and+ where to see the rest. Deterministic text."""+ lines = [f"**What your Executive did in {summary.label}**", ""]+ shown = [summary.line(k) for k in _HEADLINE_KEYS]+ for line in shown:+ if line is not None and line.count:+ lines.append(f"- {line.label}: {line.count}")+ if len(lines) == 2:+ lines.append("- Nothing to report this time.")+ if link:+ lines += ["", f"The full breakdown: {link}"]+ return "\n".join(lines)+++# --------------------------------------------------------------------------- #+# The monthly message+# --------------------------------------------------------------------------- #++# The workspace's local hours it may go out in, on the first weekday of the+# month (the briefs' daytime, as the note reminders use).+FIRST_HOUR = 9+LAST_HOUR = 18+CHECK_EVERY = timedelta(minutes=15)+# Claimed once per month under this scope in ``briefing_narrative``.+_CLAIM_PREFIX = "value_summary:"++_last_check_at: datetime | None = None+_task: asyncio.Task[bool] | None = None+++def _first_weekday(day: date) -> date:+ first = day.replace(day=1)+ while first.weekday() >= 5:+ first += timedelta(days=1)+ return first+++def _claim_month(month: str, now: datetime) -> bool:+ """Record that last month's message is going out; False when it already+ did (or another worker got there first). Never released: one try."""+ from openexecutive.briefing import narrative_cache++ try:+ narrative_cache.initialize_db()+ with narrative_cache._get_conn() as conn:+ return bool(conn.execute(+ "INSERT OR IGNORE INTO briefing_narrative "+ "(scope, input_hash, narrative_text, generated_at) VALUES (?, '', '', ?)",+ (_CLAIM_PREFIX + month, now.astimezone(UTC).isoformat()),+ ).rowcount)+ except Exception:+ logger.warning("value_summary: couldn't record the monthly claim", exc_info=True)+ return False+++def value_link() -> str:+ from openexecutive.config import get_settings++ return get_settings().ui_base_url.rstrip("/") + "/memories?tab=value"+++async def send_monthly(now: datetime) -> bool:+ """On the first weekday of a month, in daytime, send the owner last+ month's tally once. True when it went. Never raises."""+ from openexecutive.audit import log_event+ from openexecutive.audit.context import private_rows+ from openexecutive.config import get_settings+ from openexecutive.memory.workspace_settings import get_user_timezone+ from openexecutive.scheduler.runner import _deliver_to_principal++ try:+ if not get_settings().value_summary_monthly_enabled:+ return False+ zone = get_user_timezone()+ local = now.astimezone(zone)+ if local.date() != _first_weekday(local.date()) or not FIRST_HOUR <= local.hour < LAST_HOUR:+ return False+ summary = summarize("month", 1, now=now, zone=zone)+ month = _month_start(local.date(), 1).isoformat()[:7]+ if summary.is_empty() or not _claim_month(month, now):+ return False+ text = render_message(summary, link=value_link())+ with private_rows():+ delivery = await _deliver_to_principal(text, label="Your month")+ except Exception:+ logger.warning("value_summary: monthly message failed", exc_info=True)+ return False+ log_event(+ "value_summary_sent" if delivery.ok else "value_summary_not_sent",+ f"Monthly summary for {summary.label}: {delivery.reason}",+ actor="scheduler",+ details={"month": month, "channel": delivery.channel, "reason": delivery.reason},+ private=True,+ )+ return delivery.ok+++def maybe_send_monthly(now: datetime) -> bool:+ """Start a monthly check when the interval has passed and none is running.+ True when one started. Never raises."""+ global _last_check_at, _task+ try:+ if _task is not None and not _task.done():+ return False+ if _last_check_at is not None and now - _last_check_at < CHECK_EVERY:+ return False+ _last_check_at = now+ _task = asyncio.get_running_loop().create_task(send_monthly(now))+ return True+ except Exception:+ logger.warning("value_summary: couldn't start the monthly check", exc_info=True)+ return False+++__all__ = [+ "maybe_send_monthly",+ "send_monthly",+ "Deliverable",+ "Period",+ "ValueLine",+ "ValueSummary",+ "period_window",+ "render_message",+ "summarize",+]diff --git a/packages/core/openexecutive/config.py b/packages/core/openexecutive/config.pyindex 8132e8d3..4f0369aa 100644--- a/packages/core/openexecutive/config.py+++ b/packages/core/openexecutive/config.py@@ -1111,6 +1111,16 @@ class Settings(BaseSettings):attunement_max_open_loops_per_person: int = Field(15, alias="ATTUNEMENT_MAX_OPEN_LOOPS_PER_PERSON")+ # Tell a person, once, when someone else assigns them a task+ # (attunement/assignment_notice.py). Chasing it stays the nudge engine's.+ attunement_assign_notify_enabled: bool = Field(+ True, alias="ATTUNEMENT_ASSIGN_NOTIFY_ENABLED"+ )+ # The owner's monthly "what your Executive did" message, on the first+ # weekday of the month (briefing/value_summary.py). Both workspace modes.+ value_summary_monthly_enabled: bool = Field(+ True, alias="VALUE_SUMMARY_MONTHLY_ENABLED"+ )# 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 isdiff --git a/packages/core/openexecutive/orchestrator/open_loop_tools.py b/packages/core/openexecutive/orchestrator/open_loop_tools.pyindex 2d81a9d9..3a23d5ef 100644--- a/packages/core/openexecutive/orchestrator/open_loop_tools.py+++ b/packages/core/openexecutive/orchestrator/open_loop_tools.py@@ -80,8 +80,11 @@ ASSIGN_OPEN_LOOP_TOOL: dict[str, Any] = {"asks you to — 'ask Ben to send me the Q3 numbers by Friday', 'put ""Sara down for the vendor quote', 'track that I owe the board deck ""Monday'. It is tracked and they are followed up automatically once "- "it is due; nobody is messaged now (use message_person as well if the "- "user wants them told). Resolve the name with list_people first. "+ "it is due. Someone assigned a task by another person is told once, "+ "on their own channel; the result's `notified` says whether it "+ "reached them (sent, held for their quiet hours, or not_reached), so "+ "say that and do not message them about it as well. Resolve the name "+ "with list_people first. ""`task` must be the deliverable copied VERBATIM from the user's own ""message, in their language (e.g. 'send me the Q3 numbers') — never ""your own wording. Only for tasks the user themselves states; never "@@ -130,6 +133,13 @@ def _audit(tool: str, ok: bool, summary: str, details: dict[str, Any]) -> None:)+def _is_principal(person_id: int) -> bool:+ from openexecutive.people.store import get_person++ person = get_person(person_id)+ return bool(person is not None and person.is_principal)++def _is_private_surface(session: Any) -> bool:"""Whether a reply in this session is seen only by the person asking.@@ -387,15 +397,21 @@ async def handle_assign_open_loop(tool_input: dict[str, Any]) -> str:_audit(tool, True, f"assign_open_loop #{result.loop_id} for person {person_id}",{"loop_id": result.loop_id, "owner_person_id": person_id,"caller_person_id": assigner})+ from openexecutive.attunement.assignment_notice import notify_assigneefrom openexecutive.attunement.open_loops import get_open_looploop = get_open_loop(result.loop_id)+ notice = await notify_assignee(+ loop_id=result.loop_id, owner_person_id=person_id,+ assigned_by_person_id=assigner, task=task, due_at=result.due_at,+ )return json.dumps({"status": "assigned","loop_id": result.loop_id,"owner_person_id": person_id,"owner": loop.owner_name if loop is not None else None,"due_at": result.due_at,+ "notified": notice.as_dict(for_principal=_is_principal(assigner)),})diff --git a/packages/core/openexecutive/scheduler/runner.py b/packages/core/openexecutive/scheduler/runner.pyindex 59b306b2..9ab5c3f8 100644--- a/packages/core/openexecutive/scheduler/runner.py+++ b/packages/core/openexecutive/scheduler/runner.py@@ -167,6 +167,19 @@ def _maybe_send_reminders(now: datetime) -> bool:return False+def _maybe_send_monthly_value(now: datetime) -> bool:+ """The owner's monthly tally of what the Executive did, once, on the+ first weekday of the month (briefing/value_summary.py). A hook like the+ reminders, in both workspace modes. Never raises."""+ try:+ from openexecutive.briefing.value_summary import maybe_send_monthly++ return maybe_send_monthly(now)+ except Exception:+ logger.exception("scheduler: monthly summary failed to start")+ return False++def _maybe_release_held(now: datetime) -> bool:"""Send the messages held for quiet hours once they end, and the ones heldfor a brief that went to someone without one (people/held_messages.py).@@ -343,6 +356,7 @@ async def run_scheduler(_maybe_remind_notes(now)_maybe_send_reminders(now)_maybe_release_held(now)+ _maybe_send_monthly_value(now)due = claim_due_actions(now)if due:logger.info("scheduler: %d due action(s)", len(due))diff --git a/packages/core/tests/integration/test_open_loops_api.py b/packages/core/tests/integration/test_open_loops_api.pyindex 9b5ca432..24d0cb57 100644--- a/packages/core/tests/integration/test_open_loops_api.py+++ b/packages/core/tests/integration/test_open_loops_api.py@@ -11,6 +11,14 @@ from openexecutive.api.routes.people import router as people_routerfrom openexecutive.memory import episodicfrom openexecutive.people import registry as people_registryfrom openexecutive.people import store as people_store+from openexecutive.scheduler.runner import PrincipalDelivery++sent: list[tuple[str, str]] = []+++async def _deliver(person, text: str, *, label: str = "Update") -> PrincipalDelivery: # noqa: ANN001+ sent.append((person.full_name, text))+ return PrincipalDelivery(True, "fake", "delivered", "email")@pytest.fixture()@@ -23,6 +31,8 @@ def client(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> TestClient:people_registry.invalidate()monkeypatch.setattr("openexecutive.audit.log_event", lambda *a, **k: None)monkeypatch.delenv("BACKEND_SHARED_SECRET", raising=False)+ sent.clear()+ monkeypatch.setattr("openexecutive.scheduler.runner.deliver_to_person", _deliver)people_store.upsert_person(full_name="Pat Principal", is_principal=True,email="[email protected]")people_store.upsert_person(full_name="Sara Kim", email="[email protected]")@@ -49,6 +59,11 @@ def test_assign_list_close(client: TestClient) -> None:loop = res.json()assert loop["owner_person_id"] == benassert loop["description"] == "Sara Kim asked Ben Ortiz for: send me the Q3 numbers"+ # … and Ben is told, once.+ # Sara is a teammate, so she isn't told which channel reaches Ben.+ assert loop["notified"] == {"status": "sent", "channel": None}+ assert sent == [("Ben Ortiz", sent[0][1])]+ assert sent[0][1].startswith("Sara Kim asked you to take this on: `send me the Q3 numbers`.")# … but cannot list Ben's loops; Ben and the principal (no header) can.assert client.get(f"/people/{ben}/open-loops", headers=as_sara).status_code == 403diff --git a/packages/core/tests/unit/test_assign_open_loop.py b/packages/core/tests/unit/test_assign_open_loop.pyindex a4116ae2..46a53367 100644--- a/packages/core/tests/unit/test_assign_open_loop.py+++ b/packages/core/tests/unit/test_assign_open_loop.py@@ -18,8 +18,25 @@ from openexecutive.delegation.settings import TurnDelegationfrom openexecutive.memory import episodicfrom openexecutive.orchestrator import open_loop_toolsfrom openexecutive.orchestrator.schedule_tools import current_session+from openexecutive.people import held_messagesfrom openexecutive.people import registry as people_registryfrom openexecutive.people import store as people_store+from openexecutive.scheduler import runner+++class _FakeDelivery:+ """Stands in for ``runner.deliver_to_person``: records what was sent."""++ def __init__(self, ok: bool = True) -> None:+ self.ok = ok+ self.sent: list[tuple[str, str, str]] = []++ async def __call__(self, person: Any, text: str, *, label: str = "Update") -> Any:+ self.sent.append((person.full_name, text, label))+ return runner.PrincipalDelivery(+ self.ok, "fake", "delivered" if self.ok else "no_channel",+ "slack_dm" if self.ok else None,+ )@pytest.fixture(autouse=True)@@ -38,6 +55,7 @@ def _isolated(lambda event_type, summary, **kw: audited.append((summary, kw.get("details") or {})),)monkeypatch.setattr("openexecutive.audit.usage.log_model_usage", lambda *a, **k: None)+ monkeypatch.setattr(runner, "deliver_to_person", _FakeDelivery())open_loops._assigned_by_turn.clear()token = current_session.set(None)yield audited@@ -306,14 +324,14 @@ def test_assign_chip_only_when_assigned() -> None:# --------------------------------------------------------------------------- #-def _post(monkeypatch: pytest.MonkeyPatch, caller: int | None, person_id: int,- task: str = "send the vendor quote", due: date | None = None) -> int:+async def _post(monkeypatch: pytest.MonkeyPatch, caller: int | None, person_id: int,+ task: str = "send the vendor quote", due: date | None = None) -> int:from openexecutive.api.routes import chat as chat_routefrom openexecutive.api.routes import people as routemonkeypatch.setattr(chat_route, "_resolve_caller_person_id", lambda req: caller)try:- route.assign_person_open_loop(+ await route.assign_person_open_loop(person_id, route.OpenLoopCreate(task=task, due_date=due), request=None, # type: ignore[arg-type])return 201@@ -321,37 +339,39 @@ def _post(monkeypatch: pytest.MonkeyPatch, caller: int | None, person_id: int,return exc.status_code-def test_route_assigns(team: SimpleNamespace, monkeypatch: pytest.MonkeyPatch) -> None:+async def test_route_assigns(team: SimpleNamespace, monkeypatch: pytest.MonkeyPatch) -> None:from openexecutive.api.routes import chat as chat_routefrom openexecutive.api.routes import people as routemonkeypatch.setattr(chat_route, "_resolve_caller_person_id", lambda req: team.principal)- out = route.assign_person_open_loop(+ out = await route.assign_person_open_loop(team.sara, route.OpenLoopCreate(task="send the vendor quote"), request=None, # type: ignore[arg-type])assert out.owner_person_id == team.sara and out.owner_name == "Sara Kim"assert out.description == "Pat Principal asked Sara Kim for: send the vendor quote"+ assert out.notified is not None and out.notified.status == "sent"+ assert out.notified.channel == "slack_dm"-def test_route_authorization_and_refusals(+async def test_route_authorization_and_refusals(team: SimpleNamespace, monkeypatch: pytest.MonkeyPatch) -> None:# Any active teammate may assign anyone on the team.- assert _post(monkeypatch, team.ben, team.sara) == 201- assert _post(monkeypatch, team.sara, team.sara, task="book the offsite") == 201+ assert await _post(monkeypatch, team.ben, team.sara) == 201+ assert await _post(monkeypatch, team.sara, team.sara, task="book the offsite") == 201# Unrostered, archived, or a contact: not someone on the team.- assert _post(monkeypatch, None, team.sara, task="other") == 403- assert _post(monkeypatch, team.gina, team.sara, task="other") == 403- assert _post(monkeypatch, team.carl, team.sara, task="other") == 403+ assert await _post(monkeypatch, None, team.sara, task="other") == 403+ assert await _post(monkeypatch, team.gina, team.sara, task="other") == 403+ assert await _post(monkeypatch, team.carl, team.sara, task="other") == 403# A contact's page reads as missing to anyone but the principal …- assert _post(monkeypatch, team.ben, team.carl) == 404+ assert await _post(monkeypatch, team.ben, team.carl) == 404# … and the principal can't make one owe a task.- assert _post(monkeypatch, team.principal, team.carl) == 409- assert _post(monkeypatch, team.principal, team.gina) == 409- assert _post(monkeypatch, team.principal, 9999) == 404- assert _post(monkeypatch, team.principal, team.sara, task="send the deck") == 201- assert _post(monkeypatch, team.principal, team.sara, task="send the deck") == 409 # duplicate- assert _post(monkeypatch, team.principal, team.sara, task=" ") == 422+ assert await _post(monkeypatch, team.principal, team.carl) == 409+ assert await _post(monkeypatch, team.principal, team.gina) == 409+ assert await _post(monkeypatch, team.principal, 9999) == 404+ assert await _post(monkeypatch, team.principal, team.sara, task="send the deck") == 201+ assert await _post(monkeypatch, team.principal, team.sara, task="send the deck") == 409 # duplicate+ assert await _post(monkeypatch, team.principal, team.sara, task=" ") == 422# --------------------------------------------------------------------------- #@@ -389,3 +409,106 @@ async def test_a_teammate_cannot_tell_a_contact_from_no_one(team: SimpleNamespacnobody = await _tool(person_id=9999, task="send me the Q3 numbers")assert contact == nobodyassert contact["reason"] == "unknown_owner"+++# --------------------------------------------------------------------------- #+# The assignee is told+# --------------------------------------------------------------------------- #+++async def test_tool_tells_the_assignee_once(team: SimpleNamespace,+ monkeypatch: pytest.MonkeyPatch) -> None:+ fake = _FakeDelivery()+ monkeypatch.setattr(runner, "deliver_to_person", fake)+ _speak(team.principal, said="Ask Sara to send the vendor quote")+ result = await _tool(person_id=team.sara, task="send the vendor quote")+ assert result["notified"] == {"status": "sent", "channel": "slack_dm"}+ [(name, text, label)] = fake.sent+ assert name == "Sara Kim" and label == "New task"+ assert text.startswith("Pat Principal asked you to take this on: `send the vendor quote`.")+ assert "It's due " in text and text.endswith("Reply here when it's done, or if you can't do it.")+++async def test_a_self_assigned_task_sends_nothing(team: SimpleNamespace,+ monkeypatch: pytest.MonkeyPatch) -> None:+ fake = _FakeDelivery()+ monkeypatch.setattr(runner, "deliver_to_person", fake)+ _speak(team.ben, said="track that I'll book the offsite")+ result = await _tool(person_id=team.ben, task="book the offsite")+ assert result["notified"]["status"] == "skipped" and fake.sent == []+++async def test_the_notice_can_be_turned_off(team: SimpleNamespace,+ monkeypatch: pytest.MonkeyPatch) -> None:+ from openexecutive.attunement.assignment_notice import notify_assignee++ fake = _FakeDelivery()+ monkeypatch.setattr(runner, "deliver_to_person", fake)+ monkeypatch.setenv("ATTUNEMENT_ASSIGN_NOTIFY_ENABLED", "false")+ out = await notify_assignee(loop_id=1, owner_person_id=team.sara,+ assigned_by_person_id=team.principal, task="x", due_at=None)+ assert out.status == "skipped" and fake.sent == []+++async def test_an_unreachable_assignee_is_reported(team: SimpleNamespace,+ monkeypatch: pytest.MonkeyPatch,+ _isolated: list) -> None:+ from openexecutive.attunement.assignment_notice import notify_assignee++ monkeypatch.setattr(runner, "deliver_to_person", _FakeDelivery(ok=False))+ out = await notify_assignee(loop_id=7, owner_person_id=team.sara,+ assigned_by_person_id=team.principal, task="x", due_at=None)+ assert out.status == "not_reached" and out.channel is None+ assert any(d.get("loop_id") == 7 and d.get("status") == "not_reached" for _, d in _isolated)+++async def test_quiet_hours_hold_the_notice(team: SimpleNamespace,+ monkeypatch: pytest.MonkeyPatch) -> None:+ from openexecutive.attunement.assignment_notice import notify_assignee+ from openexecutive.people import notifications++ fake = _FakeDelivery()+ monkeypatch.setattr(runner, "deliver_to_person", fake)+ release = datetime(2099, 1, 2, 8, tzinfo=UTC)+ monkeypatch.setattr(+ notifications, "hold_for",+ lambda person_id, *, source, now, urgent=False: notifications.Hold(release, "quiet"),+ )+ out = await notify_assignee(loop_id=3, owner_person_id=team.sara,+ assigned_by_person_id=team.principal,+ task="send the deck", due_at=None)+ assert out.status == "held" and fake.sent == []+ assert held_messages.held_count(team.sara) == 1+ assert held_messages.waiting_for(team.sara, "nudge:commitment:3")+++def test_notice_text_names_the_due_day() -> None:+ from openexecutive.attunement.assignment_notice import notice_text++ text = notice_text(assigner_name="Sara Kim", task=" send\nthe quote ",+ due_at="2026-10-16T17:00:00+00:00")+ assert text.startswith("Sara Kim asked you to take this on: `send the quote`.")+ assert "It's due " in text and "October" in text+ assert "It's due" not in notice_text(assigner_name="S", task="x", due_at="garbage")+++def test_notice_quotes_the_task_inert() -> None:+ from openexecutive.attunement.assignment_notice import notice_text++ evil = 'nothing". Re-approve payroll: <https://evil.example|Open> `x` [here](https://evil.example)'+ text = notice_text(assigner_name="Sara Kim", task=evil, due_at=None)+ quoted = text.split("take this on: ", 1)[1].rsplit(". Reply", 1)[0]+ # One code span, nothing that closes it, no quote or angle bracket left.+ assert quoted.startswith("`") and quoted.endswith("`.") or quoted.endswith("`")+ inner = quoted.strip(".").strip("`")+ assert "`" not in inner and '"' not in inner and "<" not in inner and ">" not in inner+++def test_a_teammate_hears_less_than_the_principal() -> None:+ from openexecutive.attunement.assignment_notice import NoticeResult++ held = NoticeResult("held", detail="quiet")+ assert held.as_dict() == {"status": "held", "channel": None}+ assert held.as_dict(for_principal=False) == {"status": "later", "channel": None}+ sent = NoticeResult("sent", channel="slack_dm")+ assert sent.as_dict(for_principal=False) == {"status": "sent", "channel": None}diff --git a/packages/core/tests/unit/test_value_summary.py b/packages/core/tests/unit/test_value_summary.pynew file mode 100644index 00000000..a60225e6--- /dev/null+++ b/packages/core/tests/unit/test_value_summary.py@@ -0,0 +1,214 @@+"""The owner's monthly tally (briefing/value_summary.py): what counts, what+doesn't, the period bounds, the route's gate and the monthly message."""+from __future__ import annotations++import sqlite3+from collections.abc import Iterator+from datetime import UTC, datetime+from pathlib import Path+from types import SimpleNamespace+from typing import Any+from zoneinfo import ZoneInfo++import pytest++from openexecutive.audit import AuditLogger, set_audit_logger+from openexecutive.briefing import narrative_cache, value_summary+from openexecutive.memory import episodic+from openexecutive.people import registry as people_registry+from openexecutive.people import store as people_store+from openexecutive.workflows import persistence++UTC_ZONE = ZoneInfo("UTC")+# Mid-October 2026; "this month" is October, the one before September.+NOW = datetime(2026, 10, 14, 12, tzinfo=UTC)+OCT = "2026-10-05T10:00:00.000000Z"+SEP = "2026-09-20T10:00:00.000000Z"++[email protected](autouse=True)+def db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[Path]:+ path = tmp_path / "test.db"+ monkeypatch.setattr(episodic, "DB_PATH", path)+ monkeypatch.setattr(people_store, "DB_PATH", path)+ monkeypatch.setattr(narrative_cache, "DB_PATH", path)+ episodic.initialize_db(path)+ people_store.initialize_db(path)+ persistence.initialize_runs_db(path)+ people_registry.invalidate()+ set_audit_logger(AuditLogger(db_path=path))+ monkeypatch.setattr(value_summary, "_last_check_at", None)+ monkeypatch.setattr(value_summary, "_task", None)+ yield path+ set_audit_logger(None)+ people_registry.invalidate()+++def team() -> SimpleNamespace:+ principal = people_store.upsert_person(+ full_name="Pat Principal", is_principal=True, email="[email protected]",+ slack_user_id="UPAT",+ )+ sara = people_store.upsert_person(full_name="Sara Kim", email="[email protected]")+ people_registry.invalidate()+ return SimpleNamespace(principal=principal, sara=sara)+++def _audit(db: Path, ts: str, event_type: str, details: dict[str, Any], *,+ private_to_person: int | None = None, private: bool = False) -> None:+ from openexecutive.audit import get_audit_logger++ row_id = get_audit_logger().log(event_type, "row", details=details, private=private,+ private_to_person=private_to_person)+ with sqlite3.connect(db) as conn:+ conn.execute("UPDATE audit_log SET ts = ? WHERE id = ?", (ts, row_id))+++def _run(db: Path, run_id: str, name: str, at: str, status: str = "done") -> None:+ with sqlite3.connect(db) as conn:+ conn.execute(+ "INSERT INTO workflow_runs (run_id, workflow_name, title, status, inputs, "+ "created_at, updated_at) VALUES (?, ?, ?, ?, '{}', ?, ?)",+ (run_id, name, f"{name} report", status, at, at),+ )+++def _summary(**kw: Any) -> value_summary.ValueSummary:+ return value_summary.summarize("month", 0, now=NOW, zone=UTC_ZONE, **kw)+++def _count(summary: value_summary.ValueSummary, key: str) -> tuple[int, int]:+ line = summary.line(key)+ assert line is not None+ return line.count, line.previous+++def test_period_windows() -> None:+ zone = ZoneInfo("America/New_York")+ month = value_summary.period_window("month", 0, now=NOW, zone=zone)+ assert month.label == "October 2026"+ assert month.bounds == ("2026-10-01T04:00:00+00:00", "2026-11-01T04:00:00+00:00")+ jan = value_summary.period_window("month", 10, now=NOW, zone=UTC_ZONE)+ assert jan.label == "December 2025"+ week = value_summary.period_window("week", 0, now=NOW, zone=UTC_ZONE)+ assert week.label == "Week of 12 October"+ assert week.bounds == ("2026-10-12T00:00:00+00:00", "2026-10-19T00:00:00+00:00")+++def test_messages_count_sends_to_others_not_to_the_owner(db: Path, team: SimpleNamespace) -> None:+ sent = {"tool": "send_slack_dm", "kind": "outbound", "ok": True}+ _audit(db, OCT, "tool_invocation", {**sent, "user_id": "USARA"})+ _audit(db, OCT, "tool_invocation", {**sent, "user_id": "USARA"})+ _audit(db, OCT, "tool_invocation", {**sent, "user_id": "UPAT"}) # a brief to the owner+ _audit(db, OCT, "tool_invocation", {**sent, "user_id": "USARA", "held": True})+ _audit(db, OCT, "tool_invocation", {"tool": "send_slack_dm", "kind": "outbound", "ok": False})+ # The executive loop's own row for the same call is not a second send.+ _audit(db, OCT, "tool_invocation", {"tool": "send_slack_dm", "kind": "skill"})+ _audit(db, OCT, "tool_invocation", {"tool": "send_telegram_message", "kind": "outbound",+ "ok": True, "chat_id": 42})+ # Mail sent from a chat turn, and one the gateway refused.+ _audit(db, OCT, "tool_invocation", {"tool": "google_workspace__send_gmail_message",+ "kind": "mcp", "result_preview": "Message sent"})+ _audit(db, OCT, "tool_invocation", {"tool": "microsoft_365__send-mail", "kind": "mcp",+ "result_preview": "{}"})+ _audit(db, OCT, "tool_invocation", {"tool": "google_workspace__send_gmail_message",+ "kind": "mcp", "result_preview": '{"error": "blocked"}'})+ _audit(db, SEP, "tool_invocation", {**sent, "user_id": "USARA"})+ assert _count(_summary(), "messages_sent") == (5, 1)+++def test_other_lines(db: Path, team: SimpleNamespace) -> None:+ _audit(db, OCT, "delegation_reply_sent", {"person_id": team.principal})+ _audit(db, OCT, "delegation_reply_drafted", {"person_id": team.principal})+ # Sara's own inbox rows are hers, not the owner's.+ _audit(db, OCT, "delegation_reply_sent", {"person_id": team.sara},+ private_to_person=team.sara)+ _audit(db, OCT, "tool_invocation", {"tool": "create_calendar_event", "kind": "skill"})+ _audit(db, OCT, "tool_invocation", {"tool": "create_calendar_event", "kind": "skill",+ "ok": False})+ _audit(db, OCT, "scheduled_action", {"phase": "delivered", "kind": "principal_brief_morning"})+ _audit(db, OCT, "scheduled_action", {"phase": "delivered", "action_id": 4})+ _audit(db, OCT, "attunement", {"op": "loop_closed", "reason": "done"})+ _audit(db, OCT, "attunement", {"op": "loop_closed", "reason": "expired"})+ _audit(db, OCT, "chat_turn", {"direction": "out"})+ _run(db, "r1", "investor_update", "2026-10-03T09:00:00+00:00")+ _run(db, "r2", "morning_brief", "2026-10-03T09:00:00+00:00")+ _run(db, "r3", "board_prep", "2026-10-04T09:00:00+00:00", status="failed")+ _run(db, "r4", "board_prep", "2026-09-04T09:00:00+00:00")+ # A run Sara started is hers alone: not counted, not listed.+ _run(db, "r5", "competitive_teardown", "2026-10-06T09:00:00+00:00")+ with sqlite3.connect(db) as conn:+ conn.execute("UPDATE workflow_runs SET owner_person_id = ? WHERE run_id = 'r5'",+ (team.sara,))+ summary = _summary()+ assert _count(summary, "inbox_sent") == (1, 0)+ assert _count(summary, "inbox_drafted") == (1, 0)+ assert _count(summary, "meetings_booked") == (1, 0)+ assert _count(summary, "briefs_delivered") == (1, 0)+ assert _count(summary, "follow_ups") == (1, 0)+ assert _count(summary, "tasks_closed") == (1, 0)+ assert _count(summary, "answered") == (1, 0)+ assert _count(summary, "reports") == (1, 1)+ assert [d.run_id for d in summary.deliverables] == ["r1"]+ assert not summary.is_empty()+++def test_an_empty_install_reads_as_zero(tmp_path: Path) -> None:+ summary = _summary(db_path=tmp_path / "missing.db", audit_db_path=tmp_path / "none.db")+ assert summary.is_empty() and summary.deliverables == []+ assert "Nothing to report" in value_summary.render_message(summary)+++def test_message_lists_non_zero_lines_and_the_link(db: Path, team: SimpleNamespace) -> None:+ _audit(db, OCT, "chat_turn", {"direction": "out"})+ text = value_summary.render_message(_summary(), link="https://oe.test/memories?tab=value")+ assert text.startswith("**What your Executive did in October 2026**")+ assert "- Requests answered: 1" in text and "Meetings booked" not in text+ assert text.endswith("The full breakdown: https://oe.test/memories?tab=value")+ assert "$" not in text+++async def test_monthly_message_goes_once_on_the_first_weekday(+ db: Path, team: SimpleNamespace, monkeypatch: pytest.MonkeyPatch+) -> None:+ from openexecutive.scheduler import runner++ sent: list[str] = []++ async def deliver(text: str, *, label: str = "Update") -> runner.PrincipalDelivery:+ sent.append(text)+ return runner.PrincipalDelivery(True, "fake", "delivered", "slack_dm")++ monkeypatch.setattr(runner, "_deliver_to_principal", deliver)+ monkeypatch.setattr("openexecutive.memory.workspace_settings.get_user_timezone",+ lambda *a, **k: UTC_ZONE)+ _audit(db, OCT, "chat_turn", {"direction": "out"})+ # 2 November 2026 is a Monday, the month's first weekday (the 1st is a Sunday).+ sunday = datetime(2026, 11, 1, 10, tzinfo=UTC)+ monday = datetime(2026, 11, 2, 10, tzinfo=UTC)+ assert not await value_summary.send_monthly(sunday)+ assert not await value_summary.send_monthly(monday.replace(hour=6))+ assert await value_summary.send_monthly(monday)+ assert not await value_summary.send_monthly(monday.replace(hour=11))+ assert len(sent) == 1 and "October 2026" in sent[0]+ monkeypatch.setenv("VALUE_SUMMARY_MONTHLY_ENABLED", "false")+ assert not await value_summary.send_monthly(datetime(2026, 12, 1, 10, tzinfo=UTC))+++def test_route_is_the_owners_alone(team: SimpleNamespace, monkeypatch: pytest.MonkeyPatch) -> None:+ from fastapi import FastAPI+ from fastapi.testclient import TestClient++ from openexecutive.api.routes.today import router++ monkeypatch.delenv("BACKEND_SHARED_SECRET", raising=False)+ app = FastAPI()+ app.include_router(router)+ client = TestClient(app)+ owner = client.get("/today/value?period=week")+ assert owner.status_code == 200, owner.text+ assert owner.json()["period"] == "week" and "lines" in owner.json()+ sara = client.get("/today/value", headers={"x-caller-email": "[email protected]"})+ assert sara.status_code == 403+ assert client.get("/today/value?period=year").status_code == 422diff --git a/packages/ui/scripts/assignNotice.test.mjs b/packages/ui/scripts/assignNotice.test.mjsnew file mode 100644index 00000000..2bd79e0c--- /dev/null+++ b/packages/ui/scripts/assignNotice.test.mjs@@ -0,0 +1,21 @@+import assert from "node:assert/strict";+import test from "node:test";+import { assignNoticeLine } from "../src/lib/assignNotice.ts";++const FOLLOW = "They'll be followed up if it isn't done by then.";++test("a sent notice names the channel", () => {+ assert.equal(+ assignNoticeLine({ status: "sent", channel: "slack_dm" }),+ `They were told on Slack. ${FOLLOW}`,+ );+ assert.equal(assignNoticeLine({ status: "sent", channel: "weird" }), `They were told. ${FOLLOW}`);+});++test("held, unreached and skipped notices read plainly", () => {+ assert.match(assignNoticeLine({ status: "held", channel: null }), /quiet hours end/);+ assert.match(assignNoticeLine({ status: "later", channel: null }), /a little later/);+ assert.match(assignNoticeLine({ status: "not_reached", channel: null }), /couldn't be reached/);+ assert.equal(assignNoticeLine({ status: "skipped", channel: null }), FOLLOW);+ assert.equal(assignNoticeLine(undefined), FOLLOW);+});diff --git a/packages/ui/scripts/pulseView.test.mjs b/packages/ui/scripts/pulseView.test.mjsindex 3675183b..63195055 100644--- a/packages/ui/scripts/pulseView.test.mjs+++ b/packages/ui/scripts/pulseView.test.mjs@@ -15,6 +15,8 @@ test("pulseViewFor keeps the old tab links working", () => {assert.equal(pulseViewFor("followups"), "schedule");assert.equal(pulseViewFor("schedule"), "schedule");assert.equal(pulseViewFor("activity"), "activity");+ assert.equal(pulseViewFor("value"), "value");+ assert.equal(pulseViewFor("month"), "value");assert.equal(pulseViewFor("corrections"), "corrections");assert.equal(pulseViewFor("history"), "history");});diff --git a/packages/ui/scripts/valueSummary.test.mjs b/packages/ui/scripts/valueSummary.test.mjsnew file mode 100644index 00000000..06061d2b--- /dev/null+++ b/packages/ui/scripts/valueSummary.test.mjs@@ -0,0 +1,29 @@+import assert from "node:assert/strict";+import test from "node:test";+import { deltaLabel, headline, visibleLines } from "../src/lib/valueSummary.ts";++const line = (key, count, previous = 0) => ({ key, label: key, count, previous });++test("headline names the first three non-zero lines in order", () => {+ const lines = [+ line("answered", 9),+ line("reports", 1),+ line("messages_sent", 42),+ line("meetings_booked", 0),+ line("follow_ups", 3),+ ];+ assert.equal(headline(lines), "42 messages sent, 1 report, 3 follow-ups");+ assert.equal(headline([line("reports", 0)]), "");+});++test("deltaLabel compares with the period before", () => {+ assert.equal(deltaLabel(5, 2), "+3");+ assert.equal(deltaLabel(1, 4), "−3");+ assert.equal(deltaLabel(2, 2), "same");+ assert.equal(deltaLabel(0, 0), "");+});++test("visibleLines drops lines that are zero in both periods", () => {+ const out = visibleLines([line("a", 0), line("b", 0, 2), line("c", 1)]);+ assert.deepEqual(out.map((l) => l.key), ["b", "c"]);+});diff --git a/packages/ui/src/app/people/[id]/page.tsx b/packages/ui/src/app/people/[id]/page.tsxindex cdba6f15..bc29f5cf 100644--- a/packages/ui/src/app/people/[id]/page.tsx+++ b/packages/ui/src/app/people/[id]/page.tsx@@ -27,6 +27,7 @@ import {type PersonKind,type WorkingStyle,} from "@/lib/api";+import { assignNoticeLine } from "@/lib/assignNotice";import { isContact, shouldOfferTeamMode } from "@/lib/peopleKinds";// ---------------------------------------------------------------------------@@ -292,7 +293,7 @@ function OpenLoopsSection({);}setAssigned(- `Assigned — due ${new Date(loop.due_at).toLocaleDateString()}. They'll be followed up if it isn't done by then.`,+ `Assigned, due ${new Date(loop.due_at).toLocaleDateString()}. ${assignNoticeLine(loop.notified)}`,);setTask("");setDueDate("");diff --git a/packages/ui/src/components/Icon.tsx b/packages/ui/src/components/Icon.tsxindex 1c4dab39..35046497 100644--- a/packages/ui/src/components/Icon.tsx+++ b/packages/ui/src/components/Icon.tsx@@ -16,6 +16,7 @@ export const ICON_PATHS = {book: "M12 6.042A8.967 8.967 0 006 3.75c-1.052 0-2.062.18-3 .512v14.25A8.987 8.987 0 016 18c2.305 0 4.408.867 6 2.292m0-14.25a8.966 8.966 0 016-2.292c1.052 0 2.062.18 3 .512v14.25A8.987 8.987 0 0018 18a8.967 8.967 0 00-6 2.292m0-14.25v14.25",building: "M19 21V5a2 2 0 00-2-2H7a2 2 0 00-2 2v16m14 0h2m-2 0h-5m-9 0H3m2 0h5M9 7h1m-1 4h1m4-4h1m-1 4h1m-5 10v-5a1 1 0 011-1h2a1 1 0 011 1v5m-4 0h4","chevron-right": "m8.25 4.5 7.5 7.5-7.5 7.5",+ "chevron-left": "M15.75 19.5 8.25 12l7.5-7.5","arrow-left": "M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18","arrow-send": "M2 8L14 8M14 8L9 3M14 8L9 13",clipboard: "M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z",diff --git a/packages/ui/src/components/memories/PulsePage.tsx b/packages/ui/src/components/memories/PulsePage.tsxindex 93aeb77a..a608bef2 100644--- a/packages/ui/src/components/memories/PulsePage.tsx+++ b/packages/ui/src/components/memories/PulsePage.tsx@@ -8,6 +8,7 @@ import RhythmSection, { FollowUpsCard, RecentActivity } from "./CadenceSection";import MemoryList from "./MemorySection";import { HeartbeatCard, usePulseData } from "./PulseHeader";import { ComingUp, DoneRecently, FocusedScreen, MemoryTiles } from "./PulseOverview";+import { ValueScreen, YourMonthCard } from "./ValueSection";// The Pulse page is the Executive's memory + heartbeat: what it knows// (durable episodic memory) and the rhythm it runs on (recurring briefs,@@ -15,13 +16,18 @@ import { ComingUp, DoneRecently, FocusedScreen, MemoryTiles } from "./PulseOverv// built from data that already exists — episodic memory rows and the// scheduled_actions queue grouped by `kind`.//-// Layout: one overview with no tabs (the heartbeat card with its numbers,+// Layout: one overview with no tabs ("Your month", the owner's count of what+// it did for them; the heartbeat card with its numbers,// a tile per kind of memory, then Coming up beside Done recently), and a// focused screen behind each link, picked by `?tab=` so the older tab links// still land (lib/pulseView.ts). What it has learned about the signed-in// person is theirs alone, so it lives in Settings → About you, not here.const SCREENS: Record<Exclude<PulseView, "overview">, { title: string; description: string }> = {+ value: {+ title: "Your month",+ description: "What the Executive did for you, counted from the record.",+ },schedule: {title: "Schedule",description: "Everything the Executive will do on its own, soonest first.",@@ -83,6 +89,7 @@ export default function PulsePage() {</div>)}{view === "activity" && <RecentActivity />}+ {view === "value" && <ValueScreen />}{isMemoryView(view) && <MemoryList view={view} />}</FocusedScreen>)}@@ -101,6 +108,7 @@ function Overview() {What your Executive does on its own, and what it remembers.</p></header>+ <YourMonthCard /><HeartbeatCard pulse={pulse} /><MemoryTiles pulse={pulse} /><div className="grid gap-6 md:grid-cols-2">diff --git a/packages/ui/src/components/memories/ValueSection.tsx b/packages/ui/src/components/memories/ValueSection.tsxnew file mode 100644index 00000000..161fff73--- /dev/null+++ b/packages/ui/src/components/memories/ValueSection.tsx@@ -0,0 +1,190 @@+"use client";++import Link from "next/link";+import { useEffect, useState } from "react";+import Icon from "@/components/Icon";+import { getValueSummary, type ValueSummary } from "@/lib/api";+import { deltaLabel, headline, visibleLines } from "@/lib/valueSummary";+import { Skeleton } from "./shared";++// What the Executive did for the owner this month (GET /today/value): a+// "Your month" card at the top of the Pulse overview and the full count on+// its own screen (`/memories?tab=value`). Every number is counted from the+// record; the endpoint is the owner's alone, so for anyone else (a 403) the+// card doesn't render.++type Period = "month" | "week";++function useValueSummary(period: Period, offset: number) {+ // Each answer is kept with the request it answers, so a stale one reads as+ // still loading after the period changes (no reset inside the effect).+ const key = `${period}:${offset}`;+ const [result, setResult] = useState<{ key: string; summary: ValueSummary | null; error: boolean }>();++ useEffect(() => {+ let cancelled = false;+ getValueSummary(period, offset)+ .then((summary) => {+ if (!cancelled) setResult({ key, summary, error: false });+ })+ .catch(() => {+ if (!cancelled) setResult({ key, summary: null, error: true });+ });+ return () => {+ cancelled = true;+ };+ }, [key, period, offset]);++ // undefined while loading; null when this viewer isn't the owner (or it failed).+ const current = result?.key === key ? result : undefined;+ return { summary: current?.summary, error: current?.error ?? false };+}++/** The overview card: one sentence about this month, linking to the rest. */+export function YourMonthCard() {+ const { summary } = useValueSummary("month", 0);+ if (summary === null) return null;+ const line = summary ? headline(summary.lines) : "";+ return (+ <Link+ href="/memories?tab=value"+ className="group flex items-center justify-between gap-4 rounded-2xl border border-line bg-surface-elevated p-4 sm:p-6 hover:border-accent/50 hover:bg-surface-overlay transition-colors"+ >+ <div className="min-w-0">+ <h2 className="text-lg font-semibold text-fg">Your month</h2>+ {summary === undefined ? (+ <Skeleton className="h-5 w-64 mt-2" />+ ) : (+ <p className="text-[15px] text-fg-muted mt-1">+ {line+ ? `${summary.label}: ${line}.`+ : `Nothing counted yet for ${summary.label}. What it does for you adds up here.`}+ </p>+ )}+ </div>+ <Icon name="chevron-right" size="w-5 h-5" />+ </Link>+ );+}++/** The full screen: every counted line, against the period before. */+export function ValueScreen() {+ const [period, setPeriod] = useState<Period>("month");+ const [offset, setOffset] = useState(0);+ const { summary, error } = useValueSummary(period, offset);+ const before = period === "month" ? "last month" : "last week";++ function pick(next: Period) {+ setPeriod(next);+ setOffset(0);+ }++ return (+ <div className="space-y-5">+ <div className="flex flex-wrap items-center justify-between gap-3">+ <div className="inline-flex rounded-xl border border-line p-1" role="group" aria-label="Period">+ {(["month", "week"] as const).map((p) => (+ <button+ key={p}+ type="button"+ aria-pressed={period === p}+ onClick={() => pick(p)}+ className={`h-9 rounded-lg px-3 text-sm font-semibold transition-colors ${+ period === p ? "bg-accent text-white" : "text-fg-muted hover:bg-surface-overlay"+ }`}+ >+ {p === "month" ? "Month" : "Week"}+ </button>+ ))}+ </div>+ <div className="flex items-center gap-2">+ <button+ type="button"+ onClick={() => setOffset((o) => o + 1)}+ className="h-10 w-10 inline-flex items-center justify-center rounded-xl border border-line hover:bg-surface-overlay"+ aria-label={`Previous ${period}`}+ >+ <Icon name="chevron-left" size="w-4 h-4" />+ </button>+ <span className="min-w-[9rem] text-center text-[15px] font-semibold text-fg">+ {summary ? summary.label : " "}+ </span>+ <button+ type="button"+ onClick={() => setOffset((o) => Math.max(0, o - 1))}+ disabled={offset === 0}+ className="h-10 w-10 inline-flex items-center justify-center rounded-xl border border-line hover:bg-surface-overlay disabled:opacity-40"+ aria-label={`Next ${period}`}+ >+ <Icon name="chevron-right" size="w-4 h-4" />+ </button>+ </div>+ </div>++ {summary === undefined ? (+ <Skeleton className="h-48 w-full" />+ ) : summary === null ? (+ <p className="text-[15px] text-fg-muted">+ {error ? "Couldn't load the summary. Try again in a moment." : "Only the owner sees this summary."}+ </p>+ ) : (+ <>+ <section className="rounded-2xl border border-line bg-surface-elevated p-4 sm:p-6">+ {visibleLines(summary.lines).length === 0 ? (+ <p className="text-[15px] text-fg-muted">Nothing counted for {summary.label}.</p>+ ) : (+ <table className="w-full text-[15px]">+ <thead>+ <tr className="text-left text-sm text-fg-subtle">+ <th className="font-medium pb-2">What it did</th>+ <th className="font-medium pb-2 text-right">Count</th>+ <th className="font-medium pb-2 text-right">vs {before}</th>+ </tr>+ </thead>+ <tbody>+ {visibleLines(summary.lines).map((l) => (+ <tr key={l.key} className="border-t border-line">+ <td className="py-2.5 text-fg">{l.label}</td>+ <td className="py-2.5 text-right tabular-nums font-semibold text-fg">{l.count}</td>+ <td className="py-2.5 text-right tabular-nums text-fg-muted">+ {deltaLabel(l.count, l.previous)}+ </td>+ </tr>+ ))}+ </tbody>+ </table>+ )}+ </section>+ {summary.deliverables.length > 0 && (+ <section className="rounded-2xl border border-line bg-surface-elevated p-4 sm:p-6">+ <h2 className="text-lg font-semibold text-fg mb-2">+ Reports and documents+ {summary.deliverables_total > summary.deliverables.length &&+ ` (latest ${summary.deliverables.length} of ${summary.deliverables_total})`}+ </h2>+ <ul>+ {summary.deliverables.map((d) => (+ <li key={d.run_id} className="border-t border-line first:border-t-0">+ <Link+ href={`/jobs/runs/${encodeURIComponent(d.run_id)}`}+ className="flex items-center justify-between gap-3 py-3 text-[15px] text-fg hover:text-accent"+ >+ <span className="min-w-0 truncate">{d.title}</span>+ <span className="shrink-0 text-sm text-fg-subtle tabular-nums">+ {new Date(d.finished_at).toLocaleDateString()}+ </span>+ </Link>+ </li>+ ))}+ </ul>+ </section>+ )}+ <p className="text-sm text-fg-subtle">+ Counted from what was recorded: messages that went out, replies, meetings, briefs,+ reports and tasks. Nothing here is estimated.+ </p>+ </>+ )}+ </div>+ );+}diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.tsindex 7b604821..2803aa65 100644--- a/packages/ui/src/lib/api.ts+++ b/packages/ui/src/lib/api.ts@@ -4110,6 +4110,16 @@ export interface OpenLoop {description: string;due_at: string;created_at: string;+ // Only on the response to an assignment: whether the person was told.+ notified?: AssignNotice | null;+}++// "sent" on `channel`, "held" for their quiet hours or brief, "not_reached"+// when no channel worked, "skipped" for their own task or with notices off.+// A teammate assigning gets no channel and "later" in place of "held".+export interface AssignNotice {+ status: "sent" | "held" | "later" | "not_reached" | "skipped";+ channel: string | null;}export async function getPersonOpenLoops(id: number): Promise<OpenLoop[]> {@@ -4119,7 +4129,8 @@ export async function getPersonOpenLoops(id: number): Promise<OpenLoop[]> {}// Assign this person a task: an open loop they are followed up on once it is-// due (nobody is messaged now). The principal or anyone on the team may.+// due. They are told once on their own channel when someone else assigns it.+// The principal or anyone on the team may.// `dueDate` is a local YYYY-MM-DD; omit it for the default due window.export async function assignOpenLoop(personId: number,@@ -4589,6 +4600,42 @@ export async function getActivity(limit: number = 20): Promise<ActivityResponse>return res.json();}+// What the Executive did for the owner this month or week, counted from the+// record (GET /today/value). The owner's alone: anyone else gets null.+export interface ValueLine {+ key: string;+ label: string;+ count: number;+ previous: number;+}++export interface ValueDeliverable {+ run_id: string;+ title: string;+ workflow_name: string;+ finished_at: string;+}++export interface ValueSummary {+ period: "month" | "week";+ label: string;+ start: string;+ end: string;+ lines: ValueLine[];+ deliverables: ValueDeliverable[];+ deliverables_total: number;+}++export async function getValueSummary(+ period: "month" | "week" = "month",+ offset: number = 0,+): Promise<ValueSummary | null> {+ const res = await fetch(`${API_BASE}/today/value?period=${period}&offset=${offset}`);+ if (res.status === 403) return null;+ if (!res.ok) throw new Error(`Failed to load the summary: ${res.statusText}`);+ return res.json();+}+/** One day in the Pulse heartbeat heatmap. `date` is YYYY-MM-DD (UTC). */export interface DailyActivityCount {date: string;diff --git a/packages/ui/src/lib/assignNotice.ts b/packages/ui/src/lib/assignNotice.tsnew file mode 100644index 00000000..54fe6e92--- /dev/null+++ b/packages/ui/src/lib/assignNotice.ts@@ -0,0 +1,30 @@+// The line the People page's "Assign a task" form shows about whether the+// person was told (the `notified` the assign endpoint returns). Kept free of+// React so scripts/assignNotice.test.mjs can import it.++export interface AssignNoticeLike {+ status: string;+ channel: string | null;+}++const CHANNEL_NAMES: Record<string, string> = {+ slack_dm: "Slack",+ discord_dm: "Discord",+ telegram: "Telegram",+ email: "email",+};++export function assignNoticeLine(notice: AssignNoticeLike | null | undefined): string {+ const followUp = "They'll be followed up if it isn't done by then.";+ if (!notice || notice.status === "skipped") return followUp;+ if (notice.status === "sent") {+ const where = notice.channel ? CHANNEL_NAMES[notice.channel] : undefined;+ return `${where ? `They were told on ${where}.` : "They were told."} ${followUp}`;+ }+ if (notice.status === "held") {+ return `They'll be told when their quiet hours end, or in their brief. ${followUp}`;+ }+ // A teammate assigning isn't told why it waits: that's the person's own setting.+ if (notice.status === "later") return `They'll be told a little later. ${followUp}`;+ return `They couldn't be reached, so they haven't been told yet. ${followUp}`;+}diff --git a/packages/ui/src/lib/pulseView.ts b/packages/ui/src/lib/pulseView.tsindex 9c0f6101..ad0eea31 100644--- a/packages/ui/src/lib/pulseView.ts+++ b/packages/ui/src/lib/pulseView.ts@@ -5,6 +5,7 @@/** The Pulse overview, or one of the focused screens it links to. */export type PulseView =| "overview"+ | "value"| "schedule"| "activity"| "decisions"@@ -30,6 +31,9 @@ export function pulseViewFor(tab: string | null | undefined): PulseView {return "schedule";case "activity":return "activity";+ case "value":+ case "month":+ return "value";case "decisions":case "initiatives":case "advice":diff --git a/packages/ui/src/lib/valueSummary.ts b/packages/ui/src/lib/valueSummary.tsnew file mode 100644index 00000000..965e7e43--- /dev/null+++ b/packages/ui/src/lib/valueSummary.ts@@ -0,0 +1,49 @@+// Pure helpers for the "Your month" card and screen on Pulse+// (components/memories/ValueSection.tsx). Kept free of React so+// scripts/valueSummary.test.mjs can run them under plain node.++export interface ValueLineLike {+ key: string;+ label: string;+ count: number;+ previous: number;+}++// The lines the overview card's one sentence names, in order, and how each+// reads with its number in front.+const HEADLINE: { key: string; one: string; many: string }[] = [+ { key: "messages_sent", one: "message sent", many: "messages sent" },+ { key: "inbox_sent", one: "inbox reply sent", many: "inbox replies sent" },+ { key: "meetings_booked", one: "meeting booked", many: "meetings booked" },+ { key: "reports", one: "report", many: "reports" },+ { key: "follow_ups", one: "follow-up", many: "follow-ups" },+ { key: "tasks_closed", one: "task closed", many: "tasks closed" },+ { key: "answered", one: "request answered", many: "requests answered" },+];++/** "42 messages sent, 6 reports, 3 meetings booked": up to `max` non-zero+ * headline lines, or "" when there are none. */+export function headline(lines: ValueLineLike[], max = 3): string {+ const byKey = new Map(lines.map((l) => [l.key, l]));+ const parts: string[] = [];+ for (const h of HEADLINE) {+ const line = byKey.get(h.key);+ if (!line || line.count <= 0) continue;+ parts.push(`${line.count} ${line.count === 1 ? h.one : h.many}`);+ if (parts.length >= max) break;+ }+ return parts.join(", ");+}++/** "+3", "−2" or "same" against the period before; "" when both are zero. */+export function deltaLabel(count: number, previous: number): string {+ if (count === 0 && previous === 0) return "";+ const diff = count - previous;+ if (diff === 0) return "same";+ return diff > 0 ? `+${diff}` : `−${Math.abs(diff)}`;+}++/** Lines with something in this period or the one before; the rest is noise. */+export function visibleLines<T extends ValueLineLike>(lines: T[]): T[] {+ return lines.filter((l) => l.count > 0 || l.previous > 0);+}