AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
Resume a workflow run after its approval gate is answered
Rufus157ec1ab00ed
diff --git a/packages/core/openexecutive/api/routes/onboarding.py b/packages/core/openexecutive/api/routes/onboarding.pyindex 83f9ebfb..fed3a9c3 100644--- a/packages/core/openexecutive/api/routes/onboarding.py+++ b/packages/core/openexecutive/api/routes/onboarding.py@@ -46,6 +46,7 @@ from openexecutive.onboarding.wizard import (get_current_question,process_answer,)+from openexecutive.workflows.gate import ensure_workflow_eventlogger = logging.getLogger(__name__)@@ -207,6 +208,7 @@ async def _fire_post_onboarding_research(session_id: str) -> None:async def _run() -> str:captured = ""async for event in workflow.run(inputs=wf_inputs, store=store):+ event = ensure_workflow_event(event, site='onboarding.post_onboarding_research')if event.type == "artifact" and event.content:captured = event.contentelif event.type == "error" and event.message:diff --git a/packages/core/openexecutive/api/routes/workflows.py b/packages/core/openexecutive/api/routes/workflows.pyindex 6957c5e7..8b0b483d 100644--- a/packages/core/openexecutive/api/routes/workflows.py+++ b/packages/core/openexecutive/api/routes/workflows.py@@ -14,7 +14,6 @@ import jsonimport loggingimport timeimport uuid-from datetime import UTC, datetime, timedeltafrom typing import Anyfrom fastapi import APIRouter, HTTPException, Request@@ -36,7 +35,7 @@ from openexecutive.workflows.dynamic_store import (set_active,upsert_definition,)-from openexecutive.workflows.gate_delivery import deliver_gate_question+from openexecutive.workflows.gate import checkpoint_gatefrom openexecutive.workflows.persistence import (complete_run,create_run,@@ -45,7 +44,6 @@ from openexecutive.workflows.persistence import (get_run,initialize_runs_db,list_runs,- save_checkpoint,)from openexecutive.workflows.wait_for_human import WaitForHumanEvent@@ -68,10 +66,18 @@ async def list_workflow_runs(workflow: str | None = None, limit: int = 100) -> d@router.get("/workflows/runs/{run_id}")async def get_workflow_run(run_id: str) -> dict[str, Any]:- """Full record of one run, including the artifact if complete."""+ """Full record of one run, including the artifact if complete.++ `resume_state_json` is replaced by a small `resume_progress` summary. The+ payload holds the full text of every step completed before the gate, and+ the run-detail page POLLS this endpoint while a run is unfinished — so+ returning it would re-send the whole run body every few seconds to render+ a progress list that only needs the step ids.+ """run = get_run(run_id)if run is None:raise HTTPException(status_code=404, detail=f"Run {run_id} not found")+ run["resume_progress"] = _resume_progress(run.pop("resume_state_json", None))return run@@ -243,31 +249,32 @@ async def start_workflow_run(name: str, request: Request) -> StreamingResponse:# paused, and stop. The resumer applies the timeout policy;# the inbound resolver records the human's reply.if isinstance(event, WaitForHumanEvent):- until = datetime.now(UTC) + timedelta(hours=event.timeout_hours)- # Ask the approver before checkpointing, so state_json- # carries the channel / channel_ref / outbound_message_id- # the inbound resolver matches a reply against. Without it- # the gate was unanswerable on every channel (#136).- gate, delivery = await deliver_gate_question(- event, run_id=run_id, workflow_title=workflow.title- )- save_checkpoint(+ # Delivery + checkpoint live in `workflows.gate` so this+ # route, the chat tool and the resumer cannot drift apart.+ pause = await checkpoint_gate(run_id=run_id,- state_json=gate.model_dump_json(),- awaiting_person_id=gate.person_id,- awaiting_until=until,+ event=event,+ workflow_title=workflow.title,)paused = Trueyield _sse({"type": "awaiting_human","run_id": run_id,- "person_id": gate.person_id,- "question": gate.question,- "awaiting_until": until.isoformat(),+ "person_id": pause.person_id,+ "question": pause.question,+ "awaiting_until": pause.awaiting_until.isoformat(),# "sent" / "self" / "suppressed" / "alerted" / "failed" —# the client must not say "waiting on them" when the# question never reached them.- "delivery": delivery,+ "delivery": pause.delivery,+ # True when the run will continue by itself once the+ # answer lands; False for a pause-only gate.+ "resumable": pause.resumable,+ # No `done` or `error` follows a pause — this IS the+ # last frame. Without it a client waiting for a+ # terminal event just sees the connection close and+ # spins on the gate step forever.+ "terminal": True,})break@@ -277,7 +284,9 @@ async def start_workflow_run(name: str, request: Request) -> StreamingResponse:yield _sse(event_dict)if paused:- pass # run left in 'awaiting_human'; no done/error emitted+ # Run left in 'awaiting_human'; the awaiting_human frame above+ # was terminal, so nothing more is emitted.+ passelif artifact:complete_run(run_id=run_id, artifact=artifact)yield _sse({"type": "done", "run_id": run_id})@@ -290,7 +299,13 @@ async def start_workflow_run(name: str, request: Request) -> StreamingResponse:})except Exception as exc: # noqa: BLE001 — must report any failure to the clientlogger.exception("workflow.run_failed run_id=%s workflow=%s", run_id, workflow.name)- fail_run(run_id=run_id, error=str(exc))+ # NOT after a successful checkpoint. `fail_run` has no status+ # guard, so failing here would overwrite 'awaiting_human' with+ # 'error' and destroy the resume payload — for something as+ # ordinary as the client disconnecting while we yield the frame.+ # The run is safely parked; only the stream broke.+ if not paused:+ fail_run(run_id=run_id, error=str(exc))yield _sse({"type": "error", "run_id": run_id, "message": str(exc)})finally:logger.info(@@ -315,6 +330,27 @@ async def start_workflow_run(name: str, request: Request) -> StreamingResponse:# -----------------------------------------------------------------------------+def _resume_progress(resume_state_json: str | None) -> dict[str, Any] | None:+ """The client-safe digest of a paused run's resume payload.++ Enough for the UI to mark which steps are already done and which one is+ waiting; none of the step text itself.+ """+ if not resume_state_json:+ return None+ try:+ state = json.loads(resume_state_json)+ except (json.JSONDecodeError, TypeError):+ return None+ if not isinstance(state, dict):+ return None+ outputs = state.get("outputs")+ return {+ "gate_step_id": str(state.get("gate_step_id") or ""),+ "completed_step_ids": list(outputs) if isinstance(outputs, dict) else [],+ }++def _sse(payload: dict[str, Any]) -> str:return f"data: {json.dumps(payload)}\n\n"diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex 71499d48..1a98121a 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -2572,31 +2572,66 @@ workflows:Today dashboard for the founder to see.Every adapter replies with the one shared wording from- `resumer.resolution_acknowledgement`, which names the decision and- states that the sign-off is closed and the workflow does not continue- on its own. The previous "Got it — your response has been recorded."- implied work was now in flight.-- NOT YET SHIPPED — full generator resume: re-entering the paused async- generator to run the *next* workflow step automatically is deferred- to "Phase 7" (see the note in `resumer.py`). Today a paused multi-step- workflow captures the human's decision and stops there; it does not- continue its remaining steps on its own. `on_timeout='auto_proceed'`- does not proceed either — it synthesizes a resolution through the same- `apply_resolution` path, so `ApprovalGateStepSpec`'s suggestion to use- it as a workaround for the resume gap does not actually work. Single-step approval gates- (the common case) are fully served by the capture-and-surface path- above; multi-step auto-continuation is the gap.-- NO BUILT-IN workflow currently yields the gate — `offer_approval` did,- and it was removed with the talent vertical. (`exec_search_brief` survived- that removal — it is an advisory CHRO brief with no gate and no pipeline- dependency.) Only user-created dynamic- workflows pause today. A dynamic workflow that pauses must be designed- AROUND the resume gap: yield `result` + `artifact` BEFORE the gate (the- runner never reaches `complete_run` on a paused run) and persist anything- downstream code needs, so the gate's only job is to RECORD the decision and- an explicit follow-up action performs the real state transition.+ `resumer.resolution_acknowledgement`, which names the decision (via the+ shared `DECISION_VERBS` map in wait_for_human.py) and then says what+ actually happens next, keyed on whether the run carries a+ `resume_state_json`: resuming now, stopping here because the answer was+ a reject/defer, or — for a pause-only gate — closed out with nothing+ further. The original "Got it — your response has been recorded."+ implied work was in flight when none was; saying "the workflow does not+ continue on its own" for a resumable gate would now be the same error+ in the other direction.++ RESUME — a paused run continues on its own. Nothing serializes a+ generator frame; that assumption is what deferred this for so long. The+ only state alive across a dynamic workflow's steps is its inputs+ (already in `workflow_runs.inputs`), a recomputable company-profile+ block, the completed steps' string outputs, and the loop cursor — so the+ engine hands the checkpoint a small JSON `WorkflowResumeState`+ (workflow_name, gate_step_id, gate_step_index, next_step_index,+ outputs), stored in the new `workflow_runs.resume_state_json` column,+ and `DynamicWorkflow.resume` replays its step loop from+ `next_step_index`. `run()` and `resume()` share one loop (`_run_steps`),+ so a gate reached on a resumed run raises an identical pause and a+ second gate needs no special handling.++ The payload rides on `WaitForHumanEvent.resume_state`, a field declared+ `exclude=True` so it can never leak into `state_json` — the resolver+ branches on which keys are PRESENT there, so shape stability is a+ property of the type rather than a rule each call site must remember. A+ gate with no payload is pause-only: the decision is recorded and the run+ stops, which is what every caller got before resume existed.++ EXECUTION — `resumer._process_resumable` claims a `resolved` run+ carrying a payload with one guarded UPDATE (`claim_run_for_resume`:+ resolved -> running, stamping `resumed_at` and incrementing+ `resume_attempts`), then drives `workflow.resume(...)` to `complete_run`+ / `fail_run`. It is reached two ways: immediately, via a task+ `apply_resolution` kicks off so a Slack approval starts in seconds, and+ from `_tick` every 60s as the durable backstop. Both share the claim, so+ a run executes exactly once even with two resumers against one database.+ `_tick` runs the executor AFTER the timeout loop, which is what finally+ makes `on_timeout='auto_proceed'` do what its name says:+ `_handle_timeout` resolves the run and the same tick executes it. Crash+ recovery: a worker that dies mid-resume leaves the run in `running` with+ a `resumed_at`, which `list_stale_resuming_runs` finds after 30 minutes+ and requeues, bounded by `_MAX_RESUME_ATTEMPTS`.++ REJECT STOPS THE RUN — `reject` and `defer` (`STOP_DECISIONS`) end the+ run at `error` with the human's note; `approve` and the synthetic+ `auto_proceed` continue. The decision becomes the gate step's own output+ via `dynamic._format_resolution`, so it appears as a section IN the+ artifact, not only in a database column. A definition edited during the+ pause is caught before any of that: `resume` re-validates the payload's+ version/engine/workflow name and that `steps[gate_step_index]` is still+ the same gate, and refuses rather than resuming at a shifted index.++ NO BUILT-IN workflow yields the gate — `offer_approval` did, and it was+ removed with the talent vertical. (`exec_search_brief` survived that+ removal — it is an advisory CHRO brief with no gate and no pipeline+ dependency.) Only user-created dynamic workflows pause. Gates remain+ banned in cadence-enabled dynamic workflows (`validate_definition`): a+ cron fire has no interactive human to ask.dynamic_user_created: |Users create reusable workflows on the fly — from the executive chat or a@@ -2632,9 +2667,12 @@ workflows:`cadence_person_id`. `workflows.dynamic_cadence` enqueues a`dynamic_workflow` scheduled action; the scheduler runs the workflow andDMs the artifact to that person, then re-chains. See the `scheduler:` key.- Limitation: same wait_for_human resume gap as above — a gate followed by- more steps pauses at awaiting_human and does not auto-continue, so gates- belong immediately before synthesis (validation/UI steer toward this).+ A gate followed by more steps now resumes: the run pauses at+ awaiting_human and, once answered, the resumer executes the remaining+ steps and produces the artifact (see `human_in_the_loop` -> RESUME).+ Gates no longer have to sit immediately before synthesis. They remain+ forbidden in CADENCE-enabled definitions, though — a cron fire has no+ interactive human, so `validate_definition` rejects them there.chat_launch: |Any workflow — built-in or custom — is launchable from a chat turn, notonly the /jobs UI. `openexecutive.orchestrator.workflow_run_tools` wires two@@ -2646,13 +2684,20 @@ workflows:via `get_workflow`, validates `inputs` against the workflow'sinput_model, persists the run (`create_run` → `complete_run`/`fail_run`),and streams `workflow.run(...)` to completion. It mirrors the HTTP- route's WaitForHumanEvent handling: an approval-gate step is delivered- via `gate_delivery.deliver_gate_question`, checkpointed via- `save_checkpoint`, and returned as `status='awaiting_human'` with a- `delivery` field (self / sent / suppressed / alerted / failed) rather- than hanging — so the same resumer/inbound_resolver path applies.- `_AWAITING_HINTS` picks the presentation hint from that field, so an- undelivered question is never reported as "waiting on them".+ route's WaitForHumanEvent handling — literally, now: both go through+ `workflows.gate.checkpoint_gate`, which delivers the question and+ checkpoints the run in one place so the two copies cannot drift.+ It returns a `GatePause`, reported as `status='awaiting_human'`+ with a `delivery` field (self / sent / suppressed / alerted /+ failed) and a `resumable` flag, rather than hanging. `_awaiting_hint`+ combines the two: an undelivered question is never reported as+ "waiting on them", and a pause-only gate is never described as+ continuing by itself. The nine runners that CANNOT pause+ (schedulers, evals, client rotation, onboarding, research tools)+ call `gate.ensure_workflow_event`, which raises on a gate instead+ of letting it be swallowed — the scheduler's dynamic-workflow+ branch used to ignore one and store `complete_run(run_id, "(no+ artifact)")`, a phantom success every cadence period.Guardrail: `_CHAT_LAUNCH_BLOCKLIST` excludes `executive_research` (it has thededicated `run_executive_research` tool). Running a workflow from chatDELIVERS NOTHING — it renders the artifact into the conversation; thediff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.jsonindex 44291b22..01924734 100644--- a/packages/core/openexecutive/architecture/prebuilt/api.json+++ b/packages/core/openexecutive/architecture/prebuilt/api.json@@ -1,7 +1,7 @@{"section_id": "api","title": "API Reference",- "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the eight specialist domains or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived people with an email, offered to the UI's sign-in gate. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",+ "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the eight specialist domains or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`, so that `awaiting_human` frame carries `terminal: true` to say so explicitly, plus `resumable` — whether the run continues by itself once answered or stops at the gate. `GET /workflows/runs/{run_id}` returns the run row with the resume payload replaced by a small `resume_progress` summary (`gate_step_id`, `completed_step_ids`, or `null`): the payload holds every completed step's full text, and the run-detail page polls this endpoint while a run is unfinished. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived people with an email, offered to the UI's sign-in gate. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |","mermaid": null,- "generated_at": "2026-09-18T20:04:35.326569+00:00"+ "generated_at": "2026-09-18T22:32:15.703519+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/scheduler.json b/packages/core/openexecutive/architecture/prebuilt/scheduler.jsonindex 37a1884d..c74fe2ed 100644--- a/packages/core/openexecutive/architecture/prebuilt/scheduler.json+++ b/packages/core/openexecutive/architecture/prebuilt/scheduler.json@@ -1,7 +1,7 @@{"section_id": "scheduler","title": "Scheduler & Cadences",- "markdown": "The scheduler is an asyncio task started in the FastAPI lifespan (`openexecutive.scheduler.runner.run_scheduler`). It polls every 30s and reads due rows from `scheduled_actions` (in `episodic_memory.db`). The due query uses `claim_due_actions`, an UPDATE…RETURNING claim, so each row fires at most once per process — this assumes a single scheduler instance per database. Polls are gated on an active company profile via `_company_profile_active()`; before onboarding, due rows stay `pending`.\n\n### Cadence DSL\n\n`openexecutive.departments.cadence` supports, all in UTC:\n\n- `daily@HH:MM`\n- `weekly@DOW@HH:MM` or `weekly@DOW-HH:MM` (DOW is a 3-letter day, e.g. `weekly@thu@09:00`)\n- `quarterly@DD-HH:MM`\n\nWhen a department cadence is due, the runner invokes the `department_check_in` workflow and chains the following occurrence via `cadence.enqueue_next()`. Deleting a department cancels its pending `dept_cadence` rows, and `cancel_orphaned_cadences()` sweeps orphans on boot.\n\nUser-created (dynamic) workflows can carry the same cadence DSL. A cadence-enabled definition enqueues a `dynamic_workflow` action (`workflows.dynamic_cadence`); when due, the runner runs the stored `DynamicWorkflow`, DMs the artifact to the definition's `cadence_person_id`, and re-chains the next occurrence. Saving/updating/deleting the definition reconciles its pending `dynamic_workflow` rows.\n\n### Channel routing & nudges\n\nThe delivery channel lives on the `scheduled_actions` row (`channel` / `channel_ref`); the runner dispatches through whichever was set at enqueue time — `telegram`, `slack_dm`, `discord_dm`, `email`, or `__internal__` (workflow steps and heartbeats bypass outbound dispatch). 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\n### Alert lifecycle: expiry sweep and the review heartbeat\n\nTwo alert-maintenance jobs live here. The **expiry sweep** is loop-level, not a heartbeat row: `_maybe_sweep_alerts` runs `alerts.lifecycle.expire_stale_alerts` (and, on the same 15-minute throttle, `monitoring.research.watch_policy.sweep` — expiring unreviewed research watch suggestions, auto-disabling research-added watches that proved noisy or dead, and filing one `watchlist_suggestions` nudge when ≥3 suggestions have waited ≥7 days; see External monitoring) once at boot and every 15 minutes at the top of the tick — before the company-profile and rotation gates, so an old backlog expires even before onboarding completes, flipping `unread` alerts past their category TTL to `expired` and auditing `alert_sweep`. Pure DB hygiene, no model call, reversible via `POST /alerts/{id}/reopen`.\n\nThe **Executive alert review** is a real heartbeat — kind `alert_review_scan`, `__internal__` channel, bootstrapped idempotently at startup when `ALERT_REVIEW_ENABLED` and chained every `ALERT_REVIEW_INTERVAL_HOURS` (6) with the same crash-resilient run → mark-done → chain shape as `nudge_scan`. `_run_principal_brief` also runs a `pre_brief` pass right before the morning brief (a review failure never blocks the brief). Each pass re-examines open alerts with evidence and, within department authority and the privacy rule, routes, nudges, escalates, drafts, merges or resolves them — see the Today section for the policy. The moves go through the real handlers (`message_person`, `draft_artifact`), so the outbound anti-spam guard applies, and `ALERT_REVIEW_MAX_MOVES_PER_SCAN` bounds side effects per pass.\n\n## Client rotation claim pause\n\nThe `client_rotation` kind (multi-client practice mode, opt-in via `CLIENT_ROTATION_ENABLED`) adds one loop-level behavior: while a rotation's `.rotation_in_progress` marker exists, the scheduler **skips claiming entirely** for that tick. Rotation switches the live company context between parked clients; claiming during the window would fire the just-activated client's overdue outbound follow-ups from a context nobody is watching. Everything due fires on the first tick after the original client is restored. Stale markers (crash mid-rotation) are reconciled at scheduler startup, and the rotation row is idempotently re-seeded both at boot and after every slot activation (scheduled rows swap with the client). See the Client Companies section for the rotation's full design.\n\nAn optional `notion_sync_scan` heartbeat (`NOTION_SYNC_ENABLED`, off by default) incrementally re-indexes Notion pages the workspace integration can see into the isolated `notion_wiki` collection (not COMPANY), reconciles un-shared pages, then chains the next tick.",+ "markdown": "The scheduler is an asyncio task started in the FastAPI lifespan (`openexecutive.scheduler.runner.run_scheduler`). It polls every 30s and reads due rows from `scheduled_actions` (in `episodic_memory.db`). The due query uses `claim_due_actions`, an UPDATE…RETURNING claim, so each row fires at most once per process — this assumes a single scheduler instance per database. Polls are gated on an active company profile via `_company_profile_active()`; before onboarding, due rows stay `pending`.\n\n### Cadence DSL\n\n`openexecutive.departments.cadence` supports, all in UTC:\n\n- `daily@HH:MM`\n- `weekly@DOW@HH:MM` or `weekly@DOW-HH:MM` (DOW is a 3-letter day, e.g. `weekly@thu@09:00`)\n- `quarterly@DD-HH:MM`\n\nWhen a department cadence is due, the runner invokes the `department_check_in` workflow and chains the following occurrence via `cadence.enqueue_next()`. Deleting a department cancels its pending `dept_cadence` rows, and `cancel_orphaned_cadences()` sweeps orphans on boot.\n\nUser-created (dynamic) workflows can carry the same cadence DSL. A cadence-enabled definition enqueues a `dynamic_workflow` action (`workflows.dynamic_cadence`); when due, the runner runs the stored `DynamicWorkflow`, DMs the artifact to the definition's `cadence_person_id`, and re-chains the next occurrence. Saving/updating/deleting the definition reconciles its pending `dynamic_workflow` rows. A cadence definition may not contain an approval gate — a cron fire has no human to ask — and the runner now enforces that at execution too: it calls `workflows.gate.ensure_workflow_event`, which raises on a gate so the run is recorded as failed. It previously ignored the gate and stored a completed run with `\"(no artifact)\"` as its body, which looked like a success every period.\n\n### Channel routing & nudges\n\nThe delivery channel lives on the `scheduled_actions` row (`channel` / `channel_ref`); the runner dispatches through whichever was set at enqueue time — `telegram`, `slack_dm`, `discord_dm`, `email`, or `__internal__` (workflow steps and heartbeats bypass outbound dispatch). Rows left pending by the removed staff-onboarding kinds drain through that same `__internal__` short-circuit (marked done, no dispatch); the removed talent workflows' *ad-hoc* reminders sat on the principal's real DM channel instead, so a one-shot startup sweep (`memory.episodic.cancel_orphaned_talent_reminders`) cancels them — `ad_hoc`, no department, `pending` or `running`, matching the five generated reminder shapes (outreach, interview coordination, reference checks, onboarding check-in, offer expiry) — and clears the awaiting-reply flag on delivered ones so the nudge engine stops chasing them. The marker row in `app_migrations` is claimed first with `INSERT OR IGNORE` in the same transaction, so concurrent boots cannot double-run or crash. The nudge engine (`scheduler.nudge_engine`, default 15 min) scans stalled `awaiting_human` runs, stale commitments, and idle initiatives, then emits `proactive_nudge` rows routed via `people.channel.prefer_channel_for` — honouring each Person's preferred (last-used) channel and availability windows, deferring those outside their window and skipping those with no reachable channel. Emission is capped per `scope_key` (`NUDGE_MAX_PER_SCOPE`, default 3 delivered nudges) so a parked item is not chased forever.\n\n### Alert lifecycle: expiry sweep and the review heartbeat\n\nTwo alert-maintenance jobs live here. The **expiry sweep** is loop-level, not a heartbeat row: `_maybe_sweep_alerts` runs `alerts.lifecycle.expire_stale_alerts` (and, on the same 15-minute throttle, `monitoring.research.watch_policy.sweep` — expiring unreviewed research watch suggestions, auto-disabling research-added watches that proved noisy or dead, and filing one `watchlist_suggestions` nudge when ≥3 suggestions have waited ≥7 days; see External monitoring) once at boot and every 15 minutes at the top of the tick — before the company-profile and rotation gates, so an old backlog expires even before onboarding completes, flipping `unread` alerts past their category TTL to `expired` and auditing `alert_sweep`. Pure DB hygiene, no model call, reversible via `POST /alerts/{id}/reopen`.\n\nThe **Executive alert review** is a real heartbeat — kind `alert_review_scan`, `__internal__` channel, bootstrapped idempotently at startup when `ALERT_REVIEW_ENABLED` and chained every `ALERT_REVIEW_INTERVAL_HOURS` (6) with the same crash-resilient run → mark-done → chain shape as `nudge_scan`. `_run_principal_brief` also runs a `pre_brief` pass right before the morning brief (a review failure never blocks the brief). Each pass re-examines open alerts with evidence and, within department authority and the privacy rule, routes, nudges, escalates, drafts, merges or resolves them — see the Today section for the policy. The moves go through the real handlers (`message_person`, `draft_artifact`), so the outbound anti-spam guard applies, and `ALERT_REVIEW_MAX_MOVES_PER_SCAN` bounds side effects per pass.\n\n## Client rotation claim pause\n\nThe `client_rotation` kind (multi-client practice mode, opt-in via `CLIENT_ROTATION_ENABLED`) adds one loop-level behavior: while a rotation's `.rotation_in_progress` marker exists, the scheduler **skips claiming entirely** for that tick. Rotation switches the live company context between parked clients; claiming during the window would fire the just-activated client's overdue outbound follow-ups from a context nobody is watching. Everything due fires on the first tick after the original client is restored. Stale markers (crash mid-rotation) are reconciled at scheduler startup, and the rotation row is idempotently re-seeded both at boot and after every slot activation (scheduled rows swap with the client). See the Client Companies section for the rotation's full design.\n\nAn optional `notion_sync_scan` heartbeat (`NOTION_SYNC_ENABLED`, off by default) incrementally re-indexes Notion pages the workspace integration can see into the isolated `notion_wiki` collection (not COMPANY), reconciles un-shared pages, then chains the next tick.","mermaid": "flowchart TD\n Loop[\"run_scheduler<br/>poll every 30s\"]\n Claim[\"claim_due_actions<br/>(status=pending, by kind)\"]\n Table[(\"scheduled_actions\")]\n Dispatch[\"dispatch via row channel<br/>(ad_hoc / proactive_nudge)\"]\n Dept[\"dept_cadence →<br/>department_check_in\"]\n Nudge[\"nudge_scan →<br/>nudge_engine scan\"]\n Brief[\"principal_brief_morning / _eod →<br/>morning_brief / end_of_day_digest\"]\n Reflect[\"executive_reflection →<br/>reflection (artifact only)\"]\n ExtMon[\"external_monitor_scan →<br/>monitoring pipeline\"]\n Research[\"watchlist_research_scan →<br/>executive_research (skip-if-unchanged)\"]\n Notion[\"notion_sync_scan →<br/>isolated wiki ingest\"]\n Chain[\"enqueue_next<br/>(re-arm recurring tick)\"]\n Prefer[\"prefer_channel_for<br/>(availability + last-used)\"]\n Channels[\"Slack / Discord<br/>Telegram / Email\"]\n Principal[\"DM principal\"]\n Alerts[\"alerts pipeline → /today\"]\n Loop --> Claim\n Claim -- \"claim due rows\" --> Table\n Claim -- \"ad_hoc / proactive_nudge\" --> Dispatch\n Claim -- \"dept_cadence\" --> Dept\n Claim -- \"nudge_scan\" --> Nudge\n Claim -- \"principal_brief_*\" --> Brief\n Claim -- \"executive_reflection\" --> Reflect\n Claim -- \"external_monitor_scan\" --> ExtMon\n Claim -- \"watchlist_research_scan\" --> Research\n Claim -- \"notion_sync_scan\" --> Notion\n Nudge -- \"prefer_channel_for\" --> Prefer\n Prefer -- \"emits proactive_nudge\" --> Table\n Dispatch --> Channels\n Brief --> Principal\n ExtMon --> Alerts\n Dept --> Chain\n Nudge --> Chain\n Brief --> Chain\n Reflect --> Chain\n ExtMon --> Chain\n Research --> Chain\n Notion --> Chain\n Chain --> Table\n class Loop entry\n class Claim compute\n class Table storage\n class Dispatch compute\n class Dept compute\n class Nudge compute\n class Brief compute\n class Reflect compute\n class ExtMon compute\n class Research compute\n class Notion compute\n class Chain compute\n class Prefer compute\n class Channels external\n class Principal external\n class Alerts hot",- "generated_at": "2026-09-17T14:24:32.137561+00:00"+ "generated_at": "2026-09-18T22:32:15.703997+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/workflows.json b/packages/core/openexecutive/architecture/prebuilt/workflows.jsonindex 0a42bf91..6c7e7115 100644--- a/packages/core/openexecutive/architecture/prebuilt/workflows.json+++ b/packages/core/openexecutive/architecture/prebuilt/workflows.json@@ -1,7 +1,7 @@{"section_id": "workflows","title": "Workflows",- "markdown": "Workflows are deterministic, multi-step orchestrations. The built-ins are registered in `openexecutive.workflows.WORKFLOW_REGISTRY`; user-created (dynamic) workflows are stored as data (see below). Each follows the same contract: structured input feeds an ordered list of named steps that render a Markdown artifact, persisted via `complete_run` into `workflow_runs.artifact`. Every step emits a `WorkflowEvent` (start/progress/complete) streamed over SSE at `/workflows/{name}/runs`.\n\nThe registry holds 24 built-in workflows, plus any number of user-created ones. Representative built-ins:\n\n- `board_prep`, `quarterly_plan`, `annual_plan` — planning and governance deliverables.\n- `performance_review`, `comp_refresh`, `org_design`, `exec_search_brief` — people and org artifacts (the last is an advisory hiring brief / scorecard from the CHRO, kept when the recruiting pipeline was removed).\n- `crisis_comms`, `churn_deep_dive`, `competitive_teardown` — situational analyses.\n- `department_check_in` — runs on department cadence; its `goal_status` step returns structured verdicts persisted back to `department_goals.status`.\n\n### Change-aware principal briefs\n\n`morning_brief` and `end_of_day_digest` are the two recurring briefs the scheduler DMs to the principal. Both are now a *delta*, not a re-list: the window is \"since the last **delivered** brief\" (`briefing.brief_state.since_for`; 24 h on a cold store, clamped to 7 days), activity comes from `_build_activity(limit, since=…)`, proposals (action category only) split into *new since last brief* — enumerated, with each item's why-now and next move — versus a one-line carried-over count, a *rewritten* block lists carried items the review rewrote inside the window (`brief_state.rewritten_since`: verdict `changed`, still open — the brief reports them under \"what changed\", never as done), and a *handled overnight* block lists what the Executive's alert review **completed** on its own (`brief_state.handled_since`; the `changed` verdict is excluded because the alert is still open). Section order: top call → what changed → handled overnight → needs you (new only) → waiting on → at risk. A date-free fingerprint of the inputs is compared to the last delivered one; if unchanged the artifact is the one-liner \"Nothing new since yesterday's brief — N items still waiting on you.\" and no model call is made (`PRINCIPAL_BRIEF_SUPPRESS_UNCHANGED`; `force_full=true` on a manual run bypasses it). The workflow yields a `result` event with the fingerprint; only the scheduler records it, after a successful delivery, in `briefing_narrative` under scope `brief:<kind>` — so manual runs never advance the window.\n\nNeither the nightly reflection nor the research synthesis can call `ack_alert`: both run unattended with open alerts rendered into their context, and those headlines are minted from inbound mail and chat, so an injected \"the principal already dismissed 13\" would be acted on with nobody watching. Closing an alert is the alert review's job, with evidence.\n\n`executive_reflection` now carries memory: yesterday's standup (the previous completed run's artifact) is rendered into the context and the prompt forbids re-acting on anything listed there unless it changed; open alerts render with their id, review verdict and recommended move. Reflection never closes alerts — the alert review does, with evidence.\n\n### Wait-for-human pause\n\n`wait_for_human` (`openexecutive/workflows/wait_for_human.py`) is a first-class step primitive that pauses a run: the runner calls `save_checkpoint`, the `workflow_runs` row moves to `status='awaiting_human'`, and the serialized `WaitForHumanEvent` is stored in `state_json`. (Department authority is a *separate* mechanism — `propose_only` departments file a briefing alert via `departments.authority.propose_via_alert` and mark the scheduled action done; they do not route through this gate.)\n\n**Delivery.** Both checkpoint sites — the SSE route and the `run_workflow` chat tool — call `workflows.gate_delivery.deliver_gate_question` immediately *before* checkpointing, so `state_json` carries the routing fields a reply is matched against. Two modes. When the approver is the person already in the conversation (the chat session's `origin_channel` is set and its `caller_person_id` is the gate's `person_id`), nothing is sent — the question rides in the Executive's own reply — and the gate records `origin_session_id` plus the session's channel. Otherwise the question is delivered through `schedule_tools.handle_message_person`, which picks the person's preferred channel, falls through on a failed send, and falls back to a briefing alert; the gate then records the channel, address and provider message id that send returned, plus the id of the DM session it landed in — that send is always 1:1, so the answer belongs in that conversation and nowhere else. Without it the gate matched on person and channel alone, so an unrelated @mention in a public channel resolved it and had the acknowledgement, run title included, posted where everyone could read it. Delivery is not guaranteed: the outbound guard can suppress it (duplicate, rate cap, quiet hours) and an unreachable person gets the alert fallback. Both cases leave the routing fields empty and report `delivery` as `suppressed` / `alerted` rather than claiming someone was asked, and the chat tool's presentation hint changes accordingly.\n\n**Matching a reply.** Each inbound adapter passes the message to `inbound_resolver.resolve_inbound_message` with its `session_id`. Matching is three-tier: an explicit `in_reply_to` against a stored `outbound_message_id`; otherwise a single open run on that channel; otherwise one utility-fast disambiguation call gated at 0.85 confidence. An unmatched explicit reference rules out only the candidates that carry a stored outbound id — the ones it could have matched — and the rest continue; rejecting outright meant an adapter that passes a thread id on every message (Slack's `thread_ts`) short-circuited the later tiers forever, and a global test let one delivered gate's id block an unrelated self-approval gate. Channel names are normalized (`slack_dm` ≡ `slack`), the delivered address is compared when both sides know it, a row whose `state_json` will not parse is refused (a corrupt row otherwise presents as a legacy one), and an empty stored channel is treated as a wildcard only for rows checkpointed before gate delivery existed. Two guards keep an open gate from swallowing unrelated traffic: a gate carrying an `origin_session_id` matches replies only from the conversations the adapter names (a Slack or Discord thread offers its parent channel session too, mirroring the history double-write, since a gate raised on a mention recorded that session while the answer arrives under the thread's — on Slack only when that person rooted the thread, or the alias would reach into a colleague's), and the parser can return `unrelated`, which declines to resolve and lets the message reach the normal chat path. The parser is handed the gate's own question, so a bare \"yes\" is judged against something. Its fallback is flagged by a key the model cannot emit rather than by a magic note string it could, and a fallback declines to resolve on *every* reply shape — recording the empty string a `free_text` fallback fabricates would close a sign-off on a parser outage. Every shape can answer `unrelated`, not just `approve_reject`: without it an open `free_text` gate turned the person's next message into its answer verbatim, and a `numeric` one swallowed any message containing a number. `resumer.apply_resolution` then records the decision, marks the run `resolved`, and writes an audit row. A timeout applies the step's `on_timeout` policy (escalate / auto_proceed / fail). The outcome surfaces on the Today dashboard.\n\nFull generator resume is **not yet implemented**: a resolved run records the human's decision and stops — it does not re-enter the generator to run its remaining steps, and `on_timeout='auto_proceed'` does not proceed either (it synthesizes a resolution through the same path). `resumer.resolution_acknowledgement` is the single wording every adapter replies with, and it says exactly that: the decision is recorded and the sign-off closed, the workflow does not continue on its own. No built-in workflow yields the gate; only user-created dynamic workflows do, and a dynamic workflow that pauses must be designed around the gap — emit the `result` and `artifact` events *before* the gate and persist anything downstream code needs, so the gate's only job is to record the decision.\n\n### Launching from chat\n\nWorkflows are not only reachable from the `/jobs` UI — the Executive can list and run any of them mid-conversation. `openexecutive.orchestrator.workflow_run_tools` wires two tools into the main chat loop: `list_workflows` (the launchable catalog, with each workflow's input fields) and `run_workflow` (runs one to completion and returns its Markdown artifact, using the same engine as `POST /workflows/{name}/runs`). `run_workflow` resolves both built-ins and custom workflows via `get_workflow`, validates `inputs` against the workflow's input model, persists the run (`create_run` → `complete_run` / `fail_run`), and on an approval-gate step checkpoints the run as `awaiting_human` exactly as the HTTP route does — it never hangs waiting on a human. `executive_research` is excluded (it has the dedicated `run_executive_research` tool). Running a workflow from chat delivers nothing on its own — it renders the artifact into the conversation, and the recurring principal briefs (`morning_brief`, `end_of_day_digest`) reach anyone only via the scheduler's own `_deliver_to_principal`. The tool description used to claim those two DM the principal when run and to confirm before firing them, which had the model soliciting a confirmation on a false premise; it now names `executive_reflection` as the one workflow that really does execute tool calls of its own (DMs to heads, broadcasts, alerts). A successful run surfaces an `action_taken` chip linking to `/jobs/runs/{run_id}`.\n\n### Dynamic (user-created) workflows\n\nUsers create reusable workflows on the fly — from the executive chat or a builder UI on `/jobs` — without shipping code. A dynamic workflow is a stored JSON definition (the `dynamic_workflows` table) interpreted at runtime by one generic `DynamicWorkflow` engine (`openexecutive/workflows/dynamic.py`) that implements the same `Workflow` ABC as the built-ins, so the run path, SSE streaming, run persistence, and `/jobs/[name]` form rendering are unchanged. `get_workflow` / `list_workflows` fall through to the dynamic store after the static registry (built-ins win on a name collision).\n\nA definition declares free-text input fields and an ordered step list of three kinds: **specialist** (consult a specialist with a goal prompt, optionally grounded by RAG), **approval_gate** (a `wait_for_human` pause), and a terminal **synthesis** step that assembles the artifact. `validate_definition` enforces the structural rules: exactly one terminal synthesis step, valid specialists, `{placeholder}` tokens that reference declared input fields, rostered approval/cadence people, and a parseable cadence.\n\nAuthoring from chat uses a **draft → confirm** handshake: the Executive calls `draft_workflow` (validate; return a `confirm_token` plus a plan summary), shows the user the plan, then calls `save_workflow` with the same definition and token — a token mismatch is rejected, so the saved workflow is exactly what the user approved. The builder UI drives the `/workflows/custom` CRUD endpoints directly. An optional cadence (`daily@` / `weekly@` / `quarterly@`) re-uses the scheduler via the `dynamic_workflow` action kind, which runs the workflow on schedule and DMs the artifact to a rostered recipient. Limitation: a gate followed by further steps pauses at `awaiting_human` and does not auto-continue (generator resume is deferred upstream), so gates belong immediately before synthesis.\n\nCompleted artifacts are discoverable in the unified Artifacts section (`/artifacts`) alongside their run-detail page at `/jobs/runs/{run_id}`.\n\n## Data-driven retrospectives\n\n`engagement_value_report` introduces a new workflow pattern: instead of the user typing the substance into a form (the `investor_update` / `mbr` shape), the workflow **reads its substance from the database**. A deterministic gatherer (`clients/engagement_activity.py`) pulls the period's decisions, initiatives, advisory consultations, delivered workflow artifacts (excluding prior value reports), follow-through counts, and alerts handled — from the live DB for the active client, or a parked client slot's `state.db` opened read-only. A single board-comms call narrates those facts (the prompt forbids inventing anything not in them; an empty period skips the LLM entirely), and the artifact's lists are assembled deterministically. Built for renewal conversations — the engagement record is the evidence.",- "mermaid": "flowchart TD\n Input[\"Structured input\"]\n Steps[\"Ordered named steps\"]\n Wait[\"wait_for_human pause\"]\n Sched[\"scheduled_actions<br/>(awaiting_human)\"]\n Resolver[\"inbound_resolver<br/>+ resumer\"]\n Artifact[\"Markdown artifact<br/>(workflow_runs.artifact)\"]\n Today[\"Today / Artifacts\"]\n Input --> Steps\n Steps --> Wait\n Wait --> Sched\n Sched -- \"human reply\" --> Resolver\n Resolver -- \"resolved\" --> Steps\n Steps -- \"complete_run\" --> Artifact\n Artifact --> Today\n class Input entry\n class Steps compute\n class Wait compute\n class Sched storage\n class Resolver compute\n class Artifact storage\n class Today external",- "generated_at": "2026-09-18T20:53:36.068425+00:00"+ "markdown": "Workflows are deterministic, multi-step orchestrations. The built-ins are registered in `openexecutive.workflows.WORKFLOW_REGISTRY`; user-created (dynamic) workflows are stored as data (see below). Each follows the same contract: structured input feeds an ordered list of named steps that render a Markdown artifact, persisted via `complete_run` into `workflow_runs.artifact`. Every step emits a `WorkflowEvent` (start/progress/complete) streamed over SSE at `/workflows/{name}/runs`.\n\nThe registry holds 24 built-in workflows, plus any number of user-created ones. Representative built-ins:\n\n- `board_prep`, `quarterly_plan`, `annual_plan` — planning and governance deliverables.\n- `performance_review`, `comp_refresh`, `org_design`, `exec_search_brief` — people and org artifacts (the last is an advisory hiring brief / scorecard from the CHRO, kept when the recruiting pipeline was removed).\n- `crisis_comms`, `churn_deep_dive`, `competitive_teardown` — situational analyses.\n- `department_check_in` — runs on department cadence; its `goal_status` step returns structured verdicts persisted back to `department_goals.status`.\n\n### Change-aware principal briefs\n\n`morning_brief` and `end_of_day_digest` are the two recurring briefs the scheduler DMs to the principal. Both are now a *delta*, not a re-list: the window is \"since the last **delivered** brief\" (`briefing.brief_state.since_for`; 24 h on a cold store, clamped to 7 days), activity comes from `_build_activity(limit, since=…)`, proposals (action category only) split into *new since last brief* — enumerated, with each item's why-now and next move — versus a one-line carried-over count, a *rewritten* block lists carried items the review rewrote inside the window (`brief_state.rewritten_since`: verdict `changed`, still open — the brief reports them under \"what changed\", never as done), and a *handled overnight* block lists what the Executive's alert review **completed** on its own (`brief_state.handled_since`; the `changed` verdict is excluded because the alert is still open). Section order: top call → what changed → handled overnight → needs you (new only) → waiting on → at risk. A date-free fingerprint of the inputs is compared to the last delivered one; if unchanged the artifact is the one-liner \"Nothing new since yesterday's brief — N items still waiting on you.\" and no model call is made (`PRINCIPAL_BRIEF_SUPPRESS_UNCHANGED`; `force_full=true` on a manual run bypasses it). The workflow yields a `result` event with the fingerprint; only the scheduler records it, after a successful delivery, in `briefing_narrative` under scope `brief:<kind>` — so manual runs never advance the window.\n\nNeither the nightly reflection nor the research synthesis can call `ack_alert`: both run unattended with open alerts rendered into their context, and those headlines are minted from inbound mail and chat, so an injected \"the principal already dismissed 13\" would be acted on with nobody watching. Closing an alert is the alert review's job, with evidence.\n\n`executive_reflection` now carries memory: yesterday's standup (the previous completed run's artifact) is rendered into the context and the prompt forbids re-acting on anything listed there unless it changed; open alerts render with their id, review verdict and recommended move. Reflection never closes alerts — the alert review does, with evidence.\n\n### Wait-for-human pause\n\n`wait_for_human` (`openexecutive/workflows/wait_for_human.py`) is a first-class step primitive that pauses a run: the runner calls `save_checkpoint`, the `workflow_runs` row moves to `status='awaiting_human'`, and the serialized `WaitForHumanEvent` is stored in `state_json`. (Department authority is a *separate* mechanism — `propose_only` departments file a briefing alert via `departments.authority.propose_via_alert` and mark the scheduled action done; they do not route through this gate.)\n\n**Delivery.** Both checkpoint sites — the SSE route and the `run_workflow` chat tool — call `workflows.gate_delivery.deliver_gate_question` immediately *before* checkpointing, so `state_json` carries the routing fields a reply is matched against. Two modes. When the approver is the person already in the conversation (the chat session's `origin_channel` is set and its `caller_person_id` is the gate's `person_id`), nothing is sent — the question rides in the Executive's own reply — and the gate records `origin_session_id` plus the session's channel. Otherwise the question is delivered through `schedule_tools.handle_message_person`, which picks the person's preferred channel, falls through on a failed send, and falls back to a briefing alert; the gate then records the channel, address and provider message id that send returned, plus the id of the DM session it landed in — that send is always 1:1, so the answer belongs in that conversation and nowhere else. Without it the gate matched on person and channel alone, so an unrelated @mention in a public channel resolved it and had the acknowledgement, run title included, posted where everyone could read it. Delivery is not guaranteed: the outbound guard can suppress it (duplicate, rate cap, quiet hours) and an unreachable person gets the alert fallback. Both cases leave the routing fields empty and report `delivery` as `suppressed` / `alerted` rather than claiming someone was asked, and the chat tool's presentation hint changes accordingly.\n\n**Matching a reply.** Each inbound adapter passes the message to `inbound_resolver.resolve_inbound_message` with its `session_id`. Matching is three-tier: an explicit `in_reply_to` against a stored `outbound_message_id`; otherwise a single open run on that channel; otherwise one utility-fast disambiguation call gated at 0.85 confidence. An unmatched explicit reference rules out only the candidates that carry a stored outbound id — the ones it could have matched — and the rest continue; rejecting outright meant an adapter that passes a thread id on every message (Slack's `thread_ts`) short-circuited the later tiers forever, and a global test let one delivered gate's id block an unrelated self-approval gate. Channel names are normalized (`slack_dm` ≡ `slack`), the delivered address is compared when both sides know it, a row whose `state_json` will not parse is refused (a corrupt row otherwise presents as a legacy one), and an empty stored channel is treated as a wildcard only for rows checkpointed before gate delivery existed. Two guards keep an open gate from swallowing unrelated traffic: a gate carrying an `origin_session_id` matches replies only from the conversations the adapter names (a Slack or Discord thread offers its parent channel session too, mirroring the history double-write, since a gate raised on a mention recorded that session while the answer arrives under the thread's — on Slack only when that person rooted the thread, or the alias would reach into a colleague's), and the parser can return `unrelated`, which declines to resolve and lets the message reach the normal chat path. The parser is handed the gate's own question, so a bare \"yes\" is judged against something. Its fallback is flagged by a key the model cannot emit rather than by a magic note string it could, and a fallback declines to resolve on *every* reply shape — recording the empty string a `free_text` fallback fabricates would close a sign-off on a parser outage. Every shape can answer `unrelated`, not just `approve_reject`: without it an open `free_text` gate turned the person's next message into its answer verbatim, and a `numeric` one swallowed any message containing a number. `resumer.apply_resolution` then records the decision, marks the run `resolved`, and writes an audit row. A timeout applies the step's `on_timeout` policy (escalate / auto_proceed / fail). The outcome surfaces on the Today dashboard.\n\n**Resuming past the gate.** A paused run continues on its own. Re-entering it was long assumed to mean serializing a Python generator frame; it does not. The only state alive across a dynamic workflow's steps is its inputs (already persisted), a company-profile block that is recomputed, the completed steps' output strings, and the loop cursor — so the engine hands the checkpoint a small JSON `WorkflowResumeState` (workflow name, the gate's id and index, the next index, the outputs so far), stored in `workflow_runs.resume_state_json`, and `DynamicWorkflow.resume` replays its step loop from the recorded index. `run()` and `resume()` share that one loop, which is why a second gate needs no special handling — it is simply another pause raised from the same place. The payload rides on a `WaitForHumanEvent` field declared `exclude=True`, so it can never leak into `state_json`, whose exact key set the resolver branches on. A gate with no payload is *pause-only*: the decision is recorded and the run stops, which is what every caller got before resume existed.\n\n`resumer._process_resumable` claims a resolved run with one guarded UPDATE — `resolved` → `running`, stamping `resumed_at` — and drives it to `complete_run` or `fail_run`. It runs two ways: immediately, via a task `apply_resolution` kicks off so a Slack approval starts moving in seconds, and every 60s from the poll loop as the durable backstop. Both share the claim, so a run executes exactly once even with two resumers against one database. The poll runs the executor *after* the timeout loop, which is what finally makes `on_timeout='auto_proceed'` do what its name says: the timeout resolves the run and the same tick executes it. A worker that dies mid-resume leaves the run in `running` with a `resumed_at`, which a stale sweep requeues after 30 minutes, bounded by an attempt cap.\n\n**A decline stops the run.** `reject` and `defer` end it at `error` with the human's note; `approve` and the synthetic `auto_proceed` continue. Either way the decision becomes the gate step's own output, so it reads as a section *in* the artifact rather than living only in a database column, and `resumer.resolution_acknowledgement` tells the approver which of the three happened. A definition edited during the pause is caught first: resume re-validates the payload's version and that the recorded index still holds the same gate, and refuses rather than continuing at a shifted step. No built-in workflow yields the gate; only user-created dynamic workflows do.\n\n### Launching from chat\n\nWorkflows are not only reachable from the `/jobs` UI — the Executive can list and run any of them mid-conversation. `openexecutive.orchestrator.workflow_run_tools` wires two tools into the main chat loop: `list_workflows` (the launchable catalog, with each workflow's input fields) and `run_workflow` (runs one to completion and returns its Markdown artifact, using the same engine as `POST /workflows/{name}/runs`). `run_workflow` resolves both built-ins and custom workflows via `get_workflow`, validates `inputs` against the workflow's input model, persists the run (`create_run` → `complete_run` / `fail_run`), and on an approval-gate step checkpoints the run as `awaiting_human` exactly as the HTTP route does — literally the same code, since both call `workflows.gate.checkpoint_gate`, which delivers the question and writes the checkpoint in one place. It never hangs waiting on a human, and it reports both whether the question reached them and whether the run will continue by itself once answered. The runners that *cannot* pause — the schedulers, evals, client rotation, onboarding, the research tools — call `gate.ensure_workflow_event`, which raises on a gate rather than letting one be swallowed; the scheduler's dynamic-workflow branch used to ignore it and record a successful run containing nothing. `executive_research` is excluded (it has the dedicated `run_executive_research` tool). Running a workflow from chat delivers nothing on its own — it renders the artifact into the conversation, and the recurring principal briefs (`morning_brief`, `end_of_day_digest`) reach anyone only via the scheduler's own `_deliver_to_principal`. The tool description used to claim those two DM the principal when run and to confirm before firing them, which had the model soliciting a confirmation on a false premise; it now names `executive_reflection` as the one workflow that really does execute tool calls of its own (DMs to heads, broadcasts, alerts). A successful run surfaces an `action_taken` chip linking to `/jobs/runs/{run_id}`.\n\n### Dynamic (user-created) workflows\n\nUsers create reusable workflows on the fly — from the executive chat or a builder UI on `/jobs` — without shipping code. A dynamic workflow is a stored JSON definition (the `dynamic_workflows` table) interpreted at runtime by one generic `DynamicWorkflow` engine (`openexecutive/workflows/dynamic.py`) that implements the same `Workflow` ABC as the built-ins, so the run path, SSE streaming, run persistence, and `/jobs/[name]` form rendering are unchanged. `get_workflow` / `list_workflows` fall through to the dynamic store after the static registry (built-ins win on a name collision).\n\nA definition declares free-text input fields and an ordered step list of three kinds: **specialist** (consult a specialist with a goal prompt, optionally grounded by RAG), **approval_gate** (a `wait_for_human` pause), and a terminal **synthesis** step that assembles the artifact. `validate_definition` enforces the structural rules: exactly one terminal synthesis step, valid specialists, `{placeholder}` tokens that reference declared input fields, rostered approval/cadence people, and a parseable cadence.\n\nAuthoring from chat uses a **draft → confirm** handshake: the Executive calls `draft_workflow` (validate; return a `confirm_token` plus a plan summary), shows the user the plan, then calls `save_workflow` with the same definition and token — a token mismatch is rejected, so the saved workflow is exactly what the user approved. The builder UI drives the `/workflows/custom` CRUD endpoints directly. An optional cadence (`daily@` / `weekly@` / `quarterly@`) re-uses the scheduler via the `dynamic_workflow` action kind, which runs the workflow on schedule and DMs the artifact to a rostered recipient. A gate followed by further steps pauses at `awaiting_human` and then resumes once answered, so gates no longer have to sit immediately before synthesis. They remain forbidden in cadence-enabled definitions: a scheduled fire has no interactive human to ask.\n\nCompleted artifacts are discoverable in the unified Artifacts section (`/artifacts`) alongside their run-detail page at `/jobs/runs/{run_id}`.\n\n## Data-driven retrospectives\n\n`engagement_value_report` introduces a new workflow pattern: instead of the user typing the substance into a form (the `investor_update` / `mbr` shape), the workflow **reads its substance from the database**. A deterministic gatherer (`clients/engagement_activity.py`) pulls the period's decisions, initiatives, advisory consultations, delivered workflow artifacts (excluding prior value reports), follow-through counts, and alerts handled — from the live DB for the active client, or a parked client slot's `state.db` opened read-only. A single board-comms call narrates those facts (the prompt forbids inventing anything not in them; an empty period skips the LLM entirely), and the artifact's lists are assembled deterministically. Built for renewal conversations — the engagement record is the evidence.",+ "mermaid": "flowchart TD\n Input[\"Structured input\"]\n Steps[\"Ordered named steps\"]\n Wait[\"wait_for_human pause\"]\n Sched[\"workflow_runs<br/>(awaiting_human)\"]\n Resolver[\"inbound_resolver<br/>+ resumer\"]\n Artifact[\"Markdown artifact<br/>(workflow_runs.artifact)\"]\n Today[\"Today / Artifacts\"]\n Input --> Steps\n Steps --> Wait\n Wait --> Sched\n Sched -- \"human reply\" --> Resolver\n Resolver -- \"resolved → claim\" --> Steps\n Steps -- \"complete_run\" --> Artifact\n Artifact --> Today\n class Input entry\n class Steps compute\n class Wait compute\n class Sched storage\n class Resolver compute\n class Artifact storage\n class Today external",+ "generated_at": "2026-09-18T22:18:56.918523+00:00"}diff --git a/packages/core/openexecutive/clients/rotation.py b/packages/core/openexecutive/clients/rotation.pyindex 7f27e56c..1ca812ee 100644--- a/packages/core/openexecutive/clients/rotation.py+++ b/packages/core/openexecutive/clients/rotation.py@@ -48,6 +48,7 @@ from openexecutive.clients.slots import (get_active_client,list_client_slots,)+from openexecutive.workflows.gate import ensure_workflow_eventlogger = logging.getLogger(__name__)@@ -245,6 +246,7 @@ async def _run_quiet_work_for_live_client(settings: Any, slug: str) -> None:artifact = ""try:async for event in workflow.run(inputs, store):+ event = ensure_workflow_event(event, site='clients.rotation.quiet_work')if event.type == "artifact" and event.content:artifact = event.contentelif event.type == "error":diff --git a/packages/core/openexecutive/evals/runner.py b/packages/core/openexecutive/evals/runner.pyindex 258e6b65..bc20fd95 100644--- a/packages/core/openexecutive/evals/runner.py+++ b/packages/core/openexecutive/evals/runner.py@@ -28,6 +28,7 @@ from typing import Anyfrom openexecutive.evals.judges import judge_chat, judge_triage, judge_workflowfrom openexecutive.evals.scenarios import load_scenarios+from openexecutive.workflows.gate import ensure_workflow_eventlogger = logging.getLogger(__name__)@@ -252,6 +253,7 @@ def _make_workflow_runner(inputs = workflow.input_model()(**workflow_inputs)artifact = ""async for ev in workflow.run(inputs, store):+ ev = ensure_workflow_event(ev, site='evals.runner')if ev.type == "artifact":artifact = ev.content or ""elif ev.type == "error":diff --git a/packages/core/openexecutive/monitoring/research/scheduler.py b/packages/core/openexecutive/monitoring/research/scheduler.pyindex f9844b4c..7a6d4f2b 100644--- a/packages/core/openexecutive/monitoring/research/scheduler.py+++ b/packages/core/openexecutive/monitoring/research/scheduler.py@@ -47,6 +47,8 @@ from datetime import UTC, datetime, timedeltafrom pathlib import Pathfrom typing import Any+from openexecutive.workflows.gate import ensure_workflow_event+logger = logging.getLogger(__name__)# Heartbeat identity. Mirrors the constants in monitoring.pipeline and@@ -494,6 +496,7 @@ async def run_watchlist_research_scan(async for event in workflow.run(inputs=wf_inputs, store=effective_store,):+ event = ensure_workflow_event(event, site='research.scheduler')if event.type == "result" and event.data:raw_findings = event.data.get("findings")if isinstance(raw_findings, list):diff --git a/packages/core/openexecutive/orchestrator/research_tools.py b/packages/core/openexecutive/orchestrator/research_tools.pyindex e3330a35..3cc99bbd 100644--- a/packages/core/openexecutive/orchestrator/research_tools.py+++ b/packages/core/openexecutive/orchestrator/research_tools.py@@ -19,6 +19,7 @@ from collections.abc import Awaitable, Callablefrom typing import Anyfrom openexecutive.audit import log_event as audit_log+from openexecutive.workflows.gate import ensure_workflow_eventlogger = logging.getLogger(__name__)@@ -93,6 +94,7 @@ async def handle_run_executive_research(store = ChromaDBStore(persist_directory=get_settings().vector_store_path)try:async for event in workflow.run(inputs=wf_inputs, store=store):+ event = ensure_workflow_event(event, site='research_tools.run_executive_research')if event.type == "result" and event.data:result_data = event.dataelif event.type == "artifact" and event.content:diff --git a/packages/core/openexecutive/orchestrator/workflow_run_tools.py b/packages/core/openexecutive/orchestrator/workflow_run_tools.pyindex 7802cf82..8598fdef 100644--- a/packages/core/openexecutive/orchestrator/workflow_run_tools.py+++ b/packages/core/openexecutive/orchestrator/workflow_run_tools.py@@ -13,7 +13,7 @@ any workflow conversationally and get the artifact back in the same turn.validate inputs, ``create_run``, stream events,``complete_run`` / ``fail_run``. It also handles the approval-gate case — aworkflow that yields a ``WaitForHumanEvent`` is checkpointed- (``save_checkpoint``) and reported as ``awaiting_human`` (exactly as the route+ (``gate.checkpoint_gate``) and reported as ``awaiting_human`` (exactly as the routedoes, ``api/routes/workflows.py``), rather than hanging or erroring.JSON-in / JSON-out, audited, matching the other orchestrator tools.@@ -25,7 +25,6 @@ import jsonimport loggingimport uuidfrom collections.abc import Awaitable, Callable-from datetime import UTC, datetime, timedeltafrom typing import Anyfrom openexecutive.audit import log_event as audit_log@@ -103,6 +102,26 @@ def _assert_hints_cover_every_delivery_status() -> None:)+# Whether the run carries on by itself once answered. Kept separate from+# _AWAITING_HINTS because delivery and resumability are independent: a+# question can be delivered to a pause-only gate, and a resumable gate's+# question can fail to send.+_RESUMABLE_CLAUSE = (+ " Once they answer, the workflow picks up where it left off and finishes "+ "on its own — you do not need to do anything further."+)+_PAUSE_ONLY_CLAUSE = (+ " Their answer will be recorded, but this workflow does not continue past "+ "the gate on its own, so say so rather than implying more will happen."+)+++def _awaiting_hint(delivery: str, *, resumable: bool) -> str:+ """How the Executive should present a paused run to the principal."""+ base = _AWAITING_HINTS.get(delivery, _AWAITING_HINTS["failed"])+ return base + (_RESUMABLE_CLAUSE if resumable else _PAUSE_ONLY_CLAUSE)++# The exception snippet surfaced back to the model when a workflow crashes# mid-run. Shorter than ERROR_DETAIL_LEN because it is quoted inside a longer# sentence; audit-detail truncation uses the shared cap.@@ -150,9 +169,10 @@ RUN_WORKFLOW_TOOL: dict[str, Any] = {"broadcasts, and create alerts). Confirm the principal wants an ""ad-hoc run of THAT one before firing it.\n""- If a workflow pauses for a human sign-off, this returns "- "status='awaiting_human' with who it's waiting on and whether the "- "question was actually delivered to them; relay that and do not "- "re-run it."+ "status='awaiting_human' with who it's waiting on, whether the "+ "question was actually delivered to them, and whether the run "+ "continues by itself once answered (`resumable`); relay that and do "+ "not re-run it."),"input_schema": {"type": "object",@@ -255,12 +275,11 @@ async def handle_run_workflow(tool_input: dict[str, Any]) -> str:from openexecutive.config import get_settingsfrom openexecutive.knowledge.store import ChromaDBStorefrom openexecutive.workflows import get_workflow- from openexecutive.workflows.gate_delivery import deliver_gate_question+ from openexecutive.workflows.gate import checkpoint_gatefrom openexecutive.workflows.persistence import (complete_run,create_run,fail_run,- save_checkpoint,)from openexecutive.workflows.wait_for_human import WaitForHumanEvent@@ -333,31 +352,24 @@ async def handle_run_workflow(tool_input: dict[str, Any]) -> str:# api/routes/workflows.py — the resumer applies the timeout policy# and the inbound resolver records the human's reply.if isinstance(event, WaitForHumanEvent):- until = datetime.now(UTC) + timedelta(hours=event.timeout_hours)- # Ask the approver (or, when they are the person already in- # this conversation, record that their next reply here answers- # it) BEFORE checkpointing, so state_json carries the routing- # fields the inbound resolver matches on. Without this the gate- # was unanswerable on every channel (#136).- gate, delivery = await deliver_gate_question(- event, run_id=run_id, workflow_title=workflow.title- )- # Deliberately NOT suppressed: if the checkpoint can't be- # written the run must NOT be reported as awaiting_human — a- # silently-dropped checkpoint would orphan the run in 'running'- # where the resumer/inbound resolver can never find it. Let the- # failure fall through to the outer handler, which fails the run.- save_checkpoint(+ # Delivery + checkpoint live in `workflows.gate`, shared with+ # the HTTP route and the resumer. Deliberately NOT suppressed:+ # if the checkpoint can't be written the run must NOT be+ # reported as awaiting_human — a silently-dropped checkpoint+ # would orphan the run in 'running' where the resumer and the+ # inbound resolver can never find it. Let the failure fall+ # through to the outer handler, which fails the run.+ pause = await checkpoint_gate(run_id=run_id,- state_json=gate.model_dump_json(),- awaiting_person_id=gate.person_id,- awaiting_until=until,+ event=event,+ workflow_title=workflow.title,)awaiting = {- "person_id": gate.person_id,- "question": gate.question,- "awaiting_until": until.isoformat(),- "delivery": delivery,+ "person_id": pause.person_id,+ "question": pause.question,+ "awaiting_until": pause.awaiting_until.isoformat(),+ "delivery": pause.delivery,+ "resumable": pause.resumable,}breakif event.type == "artifact" and event.content:@@ -385,8 +397,9 @@ async def handle_run_workflow(tool_input: dict[str, Any]) -> str:"workflow": name,"run_id": run_id,**awaiting,- "presentation_hint": _AWAITING_HINTS.get(- str(awaiting.get("delivery", "")), _AWAITING_HINTS["failed"]+ "presentation_hint": _awaiting_hint(+ str(awaiting.get("delivery", "")),+ resumable=bool(awaiting.get("resumable")),),})diff --git a/packages/core/openexecutive/scheduler/runner.py b/packages/core/openexecutive/scheduler/runner.pyindex c844f8a8..1f970c5b 100644--- a/packages/core/openexecutive/scheduler/runner.py+++ b/packages/core/openexecutive/scheduler/runner.py@@ -21,6 +21,7 @@ from openexecutive.memory.episodic import (reschedule_action,)from openexecutive.orchestrator.mcp_gateway import MCPGateway+from openexecutive.workflows.gate import ensure_workflow_eventlogger = logging.getLogger(__name__)@@ -348,6 +349,7 @@ async def _execute_action(workflow = DepartmentCheckInWorkflow()artifact = ""async for event in workflow.run(inputs=wf_inputs, store=store):+ event = ensure_workflow_event(event, site="scheduler.dept_cadence")if event.type == "artifact" and event.content:artifact = event.contentelif event.type == "error" and event.message:@@ -1132,17 +1134,20 @@ async def _run_dynamic_workflow(action: ScheduledAction, now: datetime) -> None:store = ChromaDBStore(persist_directory=get_settings().vector_store_path)artifact = ""async for event in workflow.run(inputs=wf_inputs, store=store):- etype = getattr(event, "type", None)- content = getattr(event, "content", None)- if etype == "artifact" and content:- artifact = content- elif etype == "error":- message = getattr(event, "message", None)- if message:- raise RuntimeError(message)- # A WaitForHumanEvent (approval gate) has no `type`; a cadence run- # can't pause for a human, so we ignore the gate and finish with- # whatever was assembled.+ # The only scheduler branch that can receive a DYNAMIC workflow, so+ # the only one that can be handed an approval gate. A cadence fire+ # has no human in the loop, and `validate_definition` forbids gates+ # in cadence-enabled workflows for exactly that reason — but a+ # definition saved before that rule, or edited while a scheduled+ # row was pending, still lands here. This used to ignore the gate+ # and store `complete_run(run_id, "(no artifact)")`: a phantom+ # successful run, every period, with nothing in it. Raising instead+ # lets the handler below record a real failure.+ event = ensure_workflow_event(event, site="scheduler.dynamic_workflow")+ if event.type == "artifact" and event.content:+ artifact = event.content+ elif event.type == "error" and event.message:+ raise RuntimeError(event.message)complete_run(run_id, artifact or "(no artifact)")except Exception as exc:logger.exception("scheduler: dynamic_workflow %r (action %d) failed", name, action.id)@@ -1222,6 +1227,7 @@ async def _run_principal_brief(action: ScheduledAction, now: datetime) -> None:fingerprint: str | None = Nonesuppressed = Falseasync for event in workflow.run(inputs=wf_inputs, store=store):+ event = ensure_workflow_event(event, site="scheduler.principal_brief")if event.type == "artifact" and event.content:artifact = event.contentelif event.type == "result" and event.data and event.data.get("brief_fingerprint"):@@ -1317,6 +1323,7 @@ async def _run_executive_reflection(store = ChromaDBStore(persist_directory=get_settings().vector_store_path)artifact = ""async for event in workflow.run(inputs=wf_inputs, store=store):+ event = ensure_workflow_event(event, site="scheduler.executive_reflection")if event.type == "artifact" and event.content:artifact = event.contentelif event.type == "error" and event.message:diff --git a/packages/core/openexecutive/workflows/dynamic.py b/packages/core/openexecutive/workflows/dynamic.pyindex 58cc3886..5d19f5f1 100644--- a/packages/core/openexecutive/workflows/dynamic.py+++ b/packages/core/openexecutive/workflows/dynamic.py@@ -10,11 +10,25 @@ SSE events, same artifact shape, same run persistence.Step interpretation:- ``specialist`` → consult the named specialist with the rendered goal(and optional RAG), store the output.-- ``approval_gate`` → yield a ``WaitForHumanEvent`` (the HTTP runner- checkpoints and pauses; see the resume limitation note on- ``ApprovalGateStepSpec``).+- ``approval_gate`` → yield a ``WaitForHumanEvent`` carrying a+ ``WorkflowResumeState``. The caller checkpoints and pauses;+ once the human answers, ``resume()`` re-enters at the next+ step (see "Pause and resume" below).- ``synthesis`` → assemble prior outputs into the final Markdown artifact,either by concatenation or via one synthesis consult.++Pause and resume+----------------+``run()`` and ``resume()`` share one step loop, ``_run_steps``, which takes+the index to start at and the outputs accumulated so far. That is the whole+mechanism: nothing serialises a generator frame. At a gate the engine hands+the caller a ``WorkflowResumeState`` (workflow name, gate id and index, next+index, completed outputs); on resume the caller hands it back, the engine+re-validates it against the live definition, records the human's decision as+the gate step's own output, and runs the loop from the next index.++A second gate needs no special handling — it is simply another pause raised+from the same loop, with a fresh payload."""from __future__ import annotations@@ -41,7 +55,13 @@ from openexecutive.workflows.dynamic_models import (SpecialistStepSpec,SynthesisStepSpec,)-from openexecutive.workflows.wait_for_human import WaitForHumanEvent+from openexecutive.workflows.wait_for_human import (+ DECISION_VERBS,+ STOP_DECISIONS,+ WaitForHumanEvent,+ WaitForHumanResolution,+ WorkflowResumeState,+)# Synthetic first step every dynamic workflow runs — loads the company profile# and surfaces a "Load context" row in the UI, mirroring the built-ins.@@ -152,19 +172,77 @@ class DynamicWorkflow(Workflow):# before any approval gate is raised or any specialist call is paid for.stale = _stale_specialist_steps(self._defn)if stale:+ yield _stale_error(stale)+ return++ # --- context ---+ yield WorkflowEvent(+ type="step_start", step_id=_CONTEXT_STEP_ID, step_title="Load context"+ )+ profile = load_or_create_profile()+ company_block = _company_context_block(profile)+ yield WorkflowEvent(+ type="step_done",+ step_id=_CONTEXT_STEP_ID,+ summary=f"Loaded profile for {profile.name or 'company'}.",+ )++ async for event in self._run_steps(+ start_index=0,+ values=values,+ company_block=company_block,+ outputs={},+ store=store,+ ):+ yield event++ async def resume(+ self,+ *,+ inputs: BaseModel,+ state: WorkflowResumeState,+ resolution: WaitForHumanResolution,+ store: ChromaDBStore,+ ) -> AsyncIterator[WorkflowEvent]:+ """Continue a run that paused at an approval gate, now answered.++ Called by ``resumer._execute_resume`` in a background task, long after+ the HTTP request that started the run is gone. Yields the same event+ types ``run()`` does, so every consumer of a workflow stream works+ unchanged — including a second ``WaitForHumanEvent`` if the definition+ has another gate further on.+ """+ values = inputs.model_dump()++ # Same pre-flight as run(): the pause may have outlived a specialist.+ # A resumed run has already been paid for up to the gate, but finishing+ # it with "Unknown specialist: …" as a section is worse than failing.+ stale = _stale_specialist_steps(self._defn)+ if stale:+ yield _stale_error(stale)+ return++ gate = self._gate_for_resume(state)+ if gate is None:+ # `upsert_definition` overwrites by name, so the definition can+ # have been edited while the run sat at the gate — which silently+ # re-points the stored index at a different step. Resuming anyway+ # would skip or repeat work and produce a plausible-looking wrong+ # artifact, so refuse and say why.yield WorkflowEvent(type="error",message=(- "workflow names a specialist that no longer exists — "- + "; ".join(- f"step {sid!r} uses {name!r}" for sid, name in stale- )- + " — edit the workflow to use a current specialist"+ "the workflow definition changed while this run was "+ "awaiting approval, so it can no longer be resumed safely "+ f"(expected an approval gate {state.gate_step_id!r} at "+ f"step {state.gate_step_index}) — re-run the workflow"),)return- # --- context ---+ # Re-derive the company block rather than persisting it: it is a pure+ # function of the profile, and a profile edited during the pause should+ # be the one the remaining steps see.yield WorkflowEvent(type="step_start", step_id=_CONTEXT_STEP_ID, step_title="Load context")@@ -173,12 +251,86 @@ class DynamicWorkflow(Workflow):yield WorkflowEvent(type="step_done",step_id=_CONTEXT_STEP_ID,- summary=f"Loaded profile for {profile.name or 'company'}.",+ summary=f"Reloaded profile for {profile.name or 'company'}.",+ )++ decision = str(resolution.parsed_decision.get("decision") or "")+ if decision in STOP_DECISIONS:+ # The human said no (or not yet). Everything after the gate exists+ # to act on a yes, so stop rather than produce the deliverable they+ # just declined. The full decision stays in `resolution_json`.+ note = str(resolution.parsed_decision.get("note") or "").strip()+ verb = DECISION_VERBS.get(decision, decision or "declined")+ yield WorkflowEvent(+ type="error",+ message=(+ f"{verb} at the {gate.title!r} approval gate"+ + (f": {note}" if note else "")+ ),+ )+ return++ # Close the `step_start` the original run emitted for this gate, and+ # give the synthesis step the decision as a readable section.+ outputs: dict[str, tuple[str, str]] = dict(state.outputs)+ outputs[gate.id] = (gate.title, _format_resolution(gate, resolution))+ yield WorkflowEvent(+ type="step_done",+ step_id=gate.id,+ summary=_first_line(outputs[gate.id][1]),)- outputs: dict[str, tuple[str, str]] = {} # step_id -> (title, output)+ async for event in self._run_steps(+ start_index=state.next_step_index,+ values=values,+ company_block=company_block,+ outputs=outputs,+ store=store,+ ):+ yield event++ # -- step loop ---------------------------------------------------------++ def _gate_for_resume(+ self, state: WorkflowResumeState+ ) -> ApprovalGateStepSpec | None:+ """The gate this payload paused at, or None if it no longer matches.++ Every field is checked against the LIVE definition because all of them+ can go stale during a pause: the payload may predate this build+ (`version`/`engine`), name a workflow this object isn't, or point at an+ index the definition no longer has — or has, but now holds a different+ step.+ """+ if state.version != 1 or state.engine != "dynamic":+ return None+ if state.workflow_name != self.name:+ return None+ if not 0 <= state.gate_step_index < len(self._defn.steps):+ return None+ step = self._defn.steps[state.gate_step_index]+ if not isinstance(step, ApprovalGateStepSpec) or step.id != state.gate_step_id:+ return None+ return step++ async def _run_steps(+ self,+ *,+ start_index: int,+ values: dict[str, Any],+ company_block: str,+ outputs: dict[str, tuple[str, str]],+ store: ChromaDBStore,+ ) -> AsyncIterator[WorkflowEvent]:+ """Interpret steps from ``start_index`` on.++ The single place step semantics live, so ``run()`` and ``resume()``+ cannot drift apart — and so a gate reached on a resumed run raises the+ same pause, with the same payload shape, as one reached on a fresh run.+ """+ for index in range(start_index, len(self._defn.steps)):+ step = self._defn.steps[index]- for step in self._defn.steps:if isinstance(step, SpecialistStepSpec):yield WorkflowEvent(type="step_start", step_id=step.id, step_title=step.title@@ -223,10 +375,11 @@ class DynamicWorkflow(Workflow):message=f"step {step.id!r} placeholder error: {exc}",)return- # The HTTP runner persists this as a checkpoint and pauses the- # run (status='awaiting_human'). The generator does not- # auto-resume past the gate (deferred upstream).- # WaitForHumanEvent is a sentinel the runner isinstance-checks;+ # The caller delivers the question, checkpoints the run+ # (status='awaiting_human') and stops. `resume_state` is what+ # lets it be picked up again — without it the gate is+ # pause-only and the steps below never run.+ # WaitForHumanEvent is a sentinel the caller isinstance-checks;# it isn't a WorkflowEvent, hence the typed-yield ignore.gate = WaitForHumanEvent(person_id=step.person_id,@@ -235,6 +388,16 @@ class DynamicWorkflow(Workflow):on_timeout=step.on_timeout,expected_reply_shape=step.expected_reply_shape,context_summary=f"Approval gate in workflow {self.title!r}",+ resume_state=WorkflowResumeState(+ workflow_name=self.name,+ gate_step_id=step.id,+ gate_step_index=index,+ next_step_index=index + 1,+ # Copy: the caller serialises this after we return, and+ # a live reference would keep mutating under it if the+ # loop ever continued.+ outputs=dict(outputs),+ ),)yield gate # type: ignore[misc]return@@ -258,6 +421,72 @@ class DynamicWorkflow(Workflow):# ---------------------------------------------------------------------------+def _stale_error(stale: list[tuple[str, str]]) -> WorkflowEvent:+ """The error a run (or resume) fails with when a specialist has gone.++ Shared by both entry points so the message a resumed run dies with is the+ same one a fresh run would have shown.+ """+ return WorkflowEvent(+ type="error",+ message=(+ "workflow names a specialist that no longer exists — "+ + "; ".join(f"step {sid!r} uses {name!r}" for sid, name in stale)+ + " — edit the workflow to use a current specialist"+ ),+ )+++def _format_resolution(+ step: ApprovalGateStepSpec, resolution: WaitForHumanResolution+) -> str:+ """Render the human's answer as the gate step's Markdown output.++ The gate is a step, so on resume it gets an output like any other and+ flows into synthesis — which is how the decision ends up IN the artifact+ rather than only in a database column. Shape-aware, because a `numeric`+ gate's answer is a number and rendering it as an approval would be a lie.+ """+ parsed = resolution.parsed_decision or {}+ shape = step.expected_reply_shape+ lines: list[str] = []++ if shape == "numeric":+ value = parsed.get("value")+ unit = str(parsed.get("unit") or "").strip()+ rendered = "no value given" if value is None else f"{value}{' ' + unit if unit else ''}"+ lines.append(f"**Answer:** {rendered}")+ elif shape == "free_text":+ lines.append(str(parsed.get("text") or resolution.reply_text or "").strip())+ elif shape == "document":+ preview = str(parsed.get("text_preview") or "").strip()+ lines.append("**Document received.**" if parsed.get("received") else "**No document received.**")+ if preview:+ lines.append(f"\n{preview}")+ else: # approve_reject+ decision = str(parsed.get("decision") or "")+ lines.append(f"**{DECISION_VERBS.get(decision, 'Recorded')}**")+ note = str(parsed.get("note") or "").strip()+ if note:+ lines.append(f"\n{note}")++ if str(parsed.get("decision") or "") == "auto_proceed":+ lines.append(+ "\n_No human reply arrived before the deadline; the workflow's "+ "`on_timeout` policy auto-proceeded._"+ )++ provenance = f"person {resolution.person_id}"+ if resolution.source_channel:+ provenance += f" via {resolution.source_channel}"+ if resolution.resolved_at:+ provenance += f" at {resolution.resolved_at}"+ lines.append(f"\n_Recorded from {provenance}._")++ body = "\n".join(part for part in lines if part).strip()+ return f"## {step.title}\n\n{body}\n"++def _stale_specialist_steps(defn: DynamicWorkflowDef) -> list[tuple[str, str]]:"""(step_id, specialist) for every step that would consult a specialistmissing from the live registry. A synthesis step only consults one when itdiff --git a/packages/core/openexecutive/workflows/dynamic_models.py b/packages/core/openexecutive/workflows/dynamic_models.pyindex 9d798927..d8c7a728 100644--- a/packages/core/openexecutive/workflows/dynamic_models.py+++ b/packages/core/openexecutive/workflows/dynamic_models.py@@ -89,10 +89,25 @@ class SpecialistStepSpec(BaseModel):class ApprovalGateStepSpec(BaseModel):"""Pause the run for a human decision (the wait_for_human primitive).- NOTE: full generator-resume after the human replies is a deferred upstream- capability. A gate followed by further steps will pause at- ``awaiting_human`` and not auto-continue; place gates immediately before- the synthesis step (or use ``on_timeout='auto_proceed'``).+ The question is delivered to ``person_id`` on their preferred channel and+ the run parks at ``awaiting_human``. When they answer, the run CONTINUES+ from the next step — a gate may sit anywhere in the sequence, and a+ definition may have more than one.++ What the answer does:+ - ``approve`` (and the ``auto_proceed`` a timeout synthesises) → the+ remaining steps run, and the decision is recorded as this step's own+ output, so it appears as a section in the artifact.+ - ``reject`` / ``defer`` → the run ends at ``error`` with the person's+ note. Everything after a sign-off exists to act on a yes.++ ``on_timeout`` applies when nobody answers within ``timeout_hours``:+ ``escalate`` files a briefing alert and ends the run at ``timed_out``,+ ``auto_proceed`` continues as though approved, ``fail`` ends it at+ ``error``.++ Not allowed in a cadence-enabled workflow: a scheduled fire has no+ interactive human to ask (``validate_definition`` rejects it)."""kind: Literal["approval_gate"] = "approval_gate"diff --git a/packages/core/openexecutive/workflows/gate.py b/packages/core/openexecutive/workflows/gate.pynew file mode 100644index 00000000..dabf8d2e--- /dev/null+++ b/packages/core/openexecutive/workflows/gate.py@@ -0,0 +1,142 @@+"""The one place an approval gate is turned into a persisted pause.++Three runners can receive a ``WaitForHumanEvent``: the HTTP/SSE route, the+chat tool, and — once a run can be resumed — the resumer itself when a+workflow hits a *second* gate. Each needs the identical sequence (deliver the+question, checkpoint the run, report what happened), and before this module+each carried its own copy. The copies had already started to differ, and the+sequence is not forgiving: get the order wrong and the run is either+advertised as awaiting a reply nobody was asked for, or checkpointed without+the routing fields the inbound resolver matches against.++``ensure_workflow_event`` is the other half. Nine more sites iterate a+workflow's event stream and cannot pause. None can reach a dynamic workflow+today, so none can see a gate — but that is a property of today's registry,+not of their code, and the failure mode if it ever changes is a run that+silently drops every step after the gate (or an opaque ``AttributeError`` on+``event.type``). The guard makes that a loud, named failure instead.+"""+from __future__ import annotations++import logging+from datetime import UTC, datetime, timedelta+from pathlib import Path+from typing import cast++from pydantic import BaseModel++import openexecutive.workflows.gate_delivery as _gate_delivery+from openexecutive.workflows.base import WorkflowEvent+from openexecutive.workflows.gate_delivery import DeliveryStatus+from openexecutive.workflows.persistence import save_checkpoint+from openexecutive.workflows.wait_for_human import WaitForHumanEvent++logger = logging.getLogger(__name__)+++class UnsupportedGateError(RuntimeError):+ """A workflow raised an approval gate at a runner that cannot pause."""+++class GatePause(BaseModel):+ """What a caller needs to report a pause. Plain data, no engine state."""++ run_id: str+ person_id: int+ question: str+ awaiting_until: datetime+ expected_reply_shape: str+ # How the question reached the approver: self / sent / suppressed /+ # alerted / failed. Anything but `sent` or `self` means nobody was+ # actually asked, and the caller must not imply otherwise.+ delivery: DeliveryStatus+ # True when the engine supplied a resume payload, so the run will continue+ # on its own once answered. False means pause-only: the decision is+ # recorded and the run stops there.+ resumable: bool+++async def checkpoint_gate(+ *,+ run_id: str,+ event: WaitForHumanEvent,+ workflow_title: str = "",+ now: datetime | None = None,+ db_path: Path | None = None,+) -> GatePause:+ """Deliver an approval gate's question and persist the pause.++ Order matters and is not incidental: delivery runs FIRST so the routing+ fields it discovers (channel, channel_ref, outbound_message_id) are part+ of the `state_json` we write. Checkpointing first and delivering after+ would leave a window where a reply could arrive against a checkpoint that+ cannot match it.++ Raises if the checkpoint cannot be written — a caller must NOT report+ `awaiting_human` when this raises, because a run that was never+ checkpointed is invisible to the resumer and the inbound resolver, and+ would sit in `running` forever. Delivery failures do not raise (see+ `gate_delivery`); they come back as `delivery` for the caller to relay.+ """+ until = (now or datetime.now(UTC)) + timedelta(hours=event.timeout_hours)+ # Module-qualified, not a from-import: tests patch+ # `gate_delivery.deliver_gate_question` at its source, and a name bound+ # here at import time would silently ignore that.+ gate, delivery = await _gate_delivery.deliver_gate_question(+ event, run_id=run_id, workflow_title=workflow_title+ )+ # `deliver_gate_question` returns a model_copy, which preserves fields it+ # does not update — `resume_state` among them. Read the payload off the+ # RETURNED gate, not the original, so a future delivery path that rebuilt+ # the event would surface here rather than silently dropping resume.+ resume_state_json = (+ gate.resume_state.model_dump_json() if gate.resume_state is not None else None+ )+ save_checkpoint(+ run_id=run_id,+ # `resume_state` is excluded at the field level, so this is exactly the+ # checkpoint shape the inbound resolver reads.+ state_json=gate.model_dump_json(),+ awaiting_person_id=gate.person_id,+ awaiting_until=until,+ db_path=db_path,+ resume_state_json=resume_state_json,+ )+ logger.info(+ "gate: run %s paused for person %s (delivery=%s, resumable=%s)",+ run_id, gate.person_id, delivery, resume_state_json is not None,+ )+ return GatePause(+ run_id=run_id,+ person_id=gate.person_id,+ question=gate.question,+ awaiting_until=until,+ expected_reply_shape=gate.expected_reply_shape,+ delivery=delivery,+ resumable=resume_state_json is not None,+ )+++def ensure_workflow_event(event: object, *, site: str) -> WorkflowEvent:+ """Pass a WorkflowEvent through; raise on an approval gate.++ For the runners that have no human to ask and no way to pause. Raising is+ the point: these sites all treat an exception as a run failure, so a gate+ that reaches one becomes a failed run naming the site, instead of a run+ that reports success having quietly skipped everything after the gate.+ """+ if isinstance(event, WaitForHumanEvent):+ raise UnsupportedGateError(+ f"{site}: workflow yielded an approval gate, but this runner "+ "cannot pause for a human — every step after the gate would be "+ "dropped. Run this workflow from the /jobs page or the chat tool."+ )+ return cast(WorkflowEvent, event)+++__all__ = [+ "GatePause",+ "UnsupportedGateError",+ "checkpoint_gate",+ "ensure_workflow_event",+]diff --git a/packages/core/openexecutive/workflows/persistence.py b/packages/core/openexecutive/workflows/persistence.pyindex 3334b122..1298edb0 100644--- a/packages/core/openexecutive/workflows/persistence.py+++ b/packages/core/openexecutive/workflows/persistence.py@@ -11,9 +11,21 @@ Four columns added via idempotent ALTER:awaiting_until TEXT — ISO timestamp for timeoutresolution_json TEXT — serialized WaitForHumanResolution on match+Resume additions+----------------+Three more columns, same idempotent ALTER:+ resume_state_json TEXT — serialized WorkflowResumeState; NULL means the+ gate is pause-only and nothing will continue it+ resumed_at TEXT — ISO timestamp a resume was claimed at, so a+ worker that dies mid-resume can be found again+ resume_attempts INTEGER — bounded retries for that requeue+New status values beyond running/done/error:awaiting_human — paused, waiting for a human reply- resolved — human replied, resolution stored in resolution_json+ resolved — human replied, resolution stored in resolution_json.+ NOT terminal when resume_state_json is set: the resumer+ claims such a row (resolved -> running) and executes the+ steps after the gate.timed_out — awaiting_until passed, timeout policy applied"""from __future__ import annotations@@ -63,6 +75,11 @@ def initialize_runs_db(db_path: Path | None = None) -> None:("resolution_json", "TEXT"),# Artifacts gallery soft-delete: NULL = active, ISO ts = archived.("archived_at", "TEXT"),+ # Resume: the engine payload, plus the claim bookkeeping that lets+ # a run stranded in 'running' by a crashed worker be requeued.+ ("resume_state_json", "TEXT"),+ ("resumed_at", "TEXT"),+ ("resume_attempts", "INTEGER NOT NULL DEFAULT 0"),):if col not in existing:try:@@ -243,8 +260,19 @@ def save_checkpoint(awaiting_person_id: int | None,awaiting_until: datetime | None,db_path: Path | None = None,+ *,+ resume_state_json: str | None = None,) -> None:- """Persist a WaitForHuman pause point and mark the run awaiting_human."""+ """Persist a WaitForHuman pause point and mark the run awaiting_human.++ ``resume_state_json`` is keyword-only and defaulted so every existing+ positional caller keeps working; NULL leaves the gate pause-only.++ ``resolution_json`` and ``resumed_at`` are CLEARED here, which is what+ makes a *second* gate correct: a run resumed past gate 1 still carries+ gate 1's resolution and claim timestamp, and leaving them would let the+ stale-resume sweep and the executor act on gate 1's answer at gate 2.+ """initialize_runs_db(db_path) # _resolve happens insidenow = datetime.now(UTC).isoformat()until_str = awaiting_until.isoformat() if awaiting_until else None@@ -256,10 +284,20 @@ def save_checkpoint(state_json = ?,awaiting_person_id = ?,awaiting_until = ?,+ resume_state_json = ?,+ resolution_json = NULL,+ resumed_at = NULL,updated_at = ?WHERE run_id = ?""",- (state_json, awaiting_person_id, until_str, now, run_id),+ (+ state_json,+ awaiting_person_id,+ until_str,+ resume_state_json,+ now,+ run_id,+ ),)@@ -331,6 +369,141 @@ def store_resolution(return cur.rowcount > 0+# ---------------------------------------------------------------------------+# Resume — claim/execute helpers for the background executor+# ---------------------------------------------------------------------------++def list_resumable_runs(+ limit: int = 50,+ db_path: Path | None = None,+) -> list[dict[str, Any]]:+ """Resolved runs that carry a resume payload, oldest-updated first.++ A `resolved` row WITHOUT `resume_state_json` is a pause-only gate and is+ deliberately excluded — its decision was the whole point, and claiming it+ would flip a finished run back to `running` forever.+ """+ if not _resolve(db_path).exists():+ return []+ cols = (+ "run_id", "workflow_name", "title", "inputs",+ "resume_state_json", "resolution_json", "updated_at",+ )+ with _get_conn(_resolve(db_path)) as conn:+ rows = conn.execute(+ f"SELECT {', '.join(cols)} FROM workflow_runs "+ "WHERE status = 'resolved' AND resume_state_json IS NOT NULL "+ "ORDER BY updated_at LIMIT ?",+ (limit,),+ ).fetchall()+ out: list[dict[str, Any]] = []+ for r in rows:+ d = dict(zip(cols, r, strict=False))+ try:+ d["inputs"] = json.loads(d["inputs"]) if d["inputs"] else {}+ except json.JSONDecodeError:+ d["inputs"] = {}+ out.append(d)+ return out+++def claim_run_for_resume(run_id: str, db_path: Path | None = None) -> bool:+ """Atomically take ownership of a resolved run: resolved -> running.++ This single guarded UPDATE is what prevents double execution. The resumer+ poll and the immediate post-resolution kick both call it, and whichever+ loses the race sees rowcount 0 and does nothing. `resumed_at` stamps the+ claim so a worker that dies mid-resume leaves a findable row rather than+ an orphan stuck in `running` forever.+ """+ if not _resolve(db_path).exists():+ return False+ now = datetime.now(UTC).isoformat()+ with _get_conn(_resolve(db_path)) as conn:+ cur = conn.execute(+ """+ UPDATE workflow_runs+ SET status = 'running',+ resumed_at = ?,+ resume_attempts = resume_attempts + 1,+ updated_at = ?+ WHERE run_id = ?+ AND status = 'resolved'+ AND resume_state_json IS NOT NULL+ """,+ (now, now, run_id),+ )+ return cur.rowcount > 0+++def clear_resume_state(run_id: str, db_path: Path | None = None) -> None:+ """Drop the resume payload once a run reaches a terminal state.++ Keeps a finished run from being re-claimed, and keeps the (potentially+ large) completed-step text out of rows nothing will replay.+ """+ if not _resolve(db_path).exists():+ return+ with _get_conn(_resolve(db_path)) as conn:+ conn.execute(+ "UPDATE workflow_runs SET resume_state_json = NULL, resumed_at = NULL "+ "WHERE run_id = ?",+ (run_id,),+ )+++def list_stale_resuming_runs(+ older_than: datetime,+ max_attempts: int = 3,+ db_path: Path | None = None,+) -> list[str]:+ """Run ids whose resume was claimed but never finished.++ Crash recovery. `sweep_stale_awaiting` only looks at `awaiting_human`, so+ without this a process killed between the claim and the terminal write+ would leave the run in `running` with nobody coming back for it.++ A run legitimately in `running` has no `resume_state_json`, and a run+ parked at a later gate is `awaiting_human`, so neither is ever matched.+ """+ if not _resolve(db_path).exists():+ return []+ with _get_conn(_resolve(db_path)) as conn:+ rows = conn.execute(+ """+ SELECT run_id FROM workflow_runs+ WHERE status = 'running'+ AND resume_state_json IS NOT NULL+ AND resumed_at IS NOT NULL+ AND resumed_at < ?+ AND resume_attempts < ?+ ORDER BY resumed_at+ """,+ (older_than.isoformat(), max_attempts),+ ).fetchall()+ return [r[0] for r in rows]+++def requeue_run_for_resume(run_id: str, db_path: Path | None = None) -> bool:+ """running -> resolved, so the next tick re-claims it. Guarded, idempotent.++ `resume_attempts` is NOT reset — it is the bound that stops a run which+ reliably kills its worker from being retried forever.+ """+ if not _resolve(db_path).exists():+ return False+ now = datetime.now(UTC).isoformat()+ with _get_conn(_resolve(db_path)) as conn:+ cur = conn.execute(+ "UPDATE workflow_runs SET status = 'resolved', resumed_at = NULL, "+ "updated_at = ? "+ "WHERE run_id = ? AND status = 'running' "+ "AND resume_state_json IS NOT NULL",+ (now, run_id),+ )+ return cur.rowcount > 0++def mark_timed_out(run_id: str, db_path: Path | None = None) -> bool:"""Transition awaiting_human → timed_out. Returns True if updated."""now = datetime.now(UTC).isoformat()diff --git a/packages/core/openexecutive/workflows/resumer.py b/packages/core/openexecutive/workflows/resumer.pyindex 84682ab8..4746794f 100644--- a/packages/core/openexecutive/workflows/resumer.py+++ b/packages/core/openexecutive/workflows/resumer.py@@ -1,32 +1,68 @@-"""Background resumer loop — handles timeouts for WaitForHuman pauses.+"""Background resumer loop — timeouts, and continuing runs past their gate.-Mirrors ``scheduler/runner.py``'s polling pattern. Single-worker assumption:-do not run more than one resumer against the same database.+Mirrors ``scheduler/runner.py``'s polling pattern.-Phase 6 scope---------------* Timeout handling: when ``awaiting_until <= now``, apply the ``on_timeout``+What it does+------------+* **Timeouts**: when ``awaiting_until <= now``, apply the ``on_timeout``policy (escalate / auto_proceed / fail).-* ``apply_resolution``: called by integration hooks (Slack / Telegram / email)- when a human replies. Stores the resolution, marks the run ``resolved``,- and writes an audit entry. Idempotent — a second call on the same run_id- is a no-op (returns False).--Full generator resume (re-entering a paused async generator) is deferred to-Phase 7 — the complexity of serialising Python generator frames outweighs the-benefit for the initial ship. ``resolved`` runs surface in the Today-dashboard so the founder can see the outcome.+* ``apply_resolution``: called by the inbound resolver (Slack / Discord /+ Telegram) when a human replies. Stores the resolution, marks the run+ ``resolved``, writes an audit entry. Idempotent — a second call on the+ same run_id is a no-op (returns False).+* **Resume**: a ``resolved`` run carrying a ``resume_state_json`` payload is+ claimed (``resolved`` -> ``running``) and driven to completion — the steps+ after the gate actually execute and produce the artifact.++How resume works+----------------+Nothing serialises a Python generator frame; that assumption is what deferred+this for so long. The engine hands out a small JSON payload at the gate (see+``WorkflowResumeState``) and ``DynamicWorkflow.resume`` replays its step loop+from the recorded index. This module supplies the missing half: the human+replies hours later in a different process, with the original SSE connection+long gone, so *something* has to pick the run back up. That something is+``_process_resumable``, reached two ways:++1. Immediately, via a task ``apply_resolution`` kicks off — so a Slack+ approval starts work in seconds rather than at the next poll.+2. From ``_tick``, 60s at a time — the durable backstop for a kick that never+ ran (process restart) or crashed.++Both go through ``claim_run_for_resume``, one guarded UPDATE, so whichever+gets there first wins and the other does nothing.++Concurrency+-----------+Single-worker *by intent*, not by safety: ``api/main.py`` starts this loop+unconditionally, so two API replicas means two resumers. The atomic claim+makes that safe — a run executes once — but the loop now does real, billable+specialist work rather than flipping statuses, so running one per database is+still the deployment contract."""from __future__ import annotationsimport asyncioimport jsonimport logging-from datetime import UTC, datetime+from datetime import UTC, datetime, timedeltafrom pathlib import Pathimport openexecutive.workflows.persistence as _wf_persistence-from openexecutive.workflows.wait_for_human import WaitForHumanResolution+from openexecutive.workflows.wait_for_human import (+ DECISION_VERBS,+ STOP_DECISIONS,+ WaitForHumanResolution,+ WorkflowResumeState,+)++# How long a claimed resume may sit unfinished before we assume its worker+# died and requeue it. Generously longer than any real run: a workflow that+# consults several specialists can legitimately take minutes.+_RESUME_STALE_AFTER = timedelta(minutes=30)+# Bound on those requeues, so a run that reliably kills its worker stops+# rather than looping forever.+_MAX_RESUME_ATTEMPTS = 3logger = logging.getLogger(__name__)@@ -71,22 +107,40 @@ async def apply_resolution("resumer.apply_resolution: run %s resolved by person %d",run_id, resolution.person_id,)++ # A resumable gate should not wait up to a poll interval to start moving —+ # someone is sitting in Slack having just approved it. The kick shares the+ # atomic claim with the poll loop, so this is a latency optimisation, not+ # a second execution path: if it never runs, `_tick` picks the run up.+ run = _wf_persistence.get_run(run_id, db_path=db_path)+ if run and run.get("resume_state_json"):+ _kick_resume(run_id, db_path=db_path)+return True-# How a recorded decision reads back to the person. Deliberately NOT-# "your response has been recorded" full stop: resolving a gate stores the-# decision and releases the run from awaiting_human, but the workflow does NOT-# continue from the step after the gate — generator resume is not implemented-# (see the module docstring and wait_for_human.py). Telling someone their-# approval is in flight when nothing further will run is the same class of lie-# that #136 was reported for.-_DECISION_VERBS = {- "approve": "Approved",- "reject": "Declined",- "defer": "Deferred",- "auto_proceed": "Auto-approved on timeout",-}+# How a recorded decision reads back to the person. What follows the verb+# depends on whether the run can actually continue, because saying the wrong+# one is the same class of lie #136 was reported for — in either direction.+# A pause-only gate that claims the workflow is resuming is as wrong as a+# resumable one that tells the approver to come back and ask for the next+# step themselves.+#+# Vocabulary lives in wait_for_human so the acknowledgement and the artifact+# section a resumed run writes cannot disagree about what the human said.+_ACK_RESUMING = (+ "That's recorded, and the workflow is picking up from there now — "+ "I'll bring you the finished result."+)+_ACK_STOPPED = (+ "That's recorded, and the run stops there — nothing after the sign-off "+ "will be produced. Tell me if you'd rather I take it forward anyway."+)+_ACK_PAUSE_ONLY = (+ "That's recorded against the sign-off and closes it out. The workflow "+ "doesn't pick up from here on its own, so tell me if you want me to take "+ "the next step."+)def resolution_acknowledgement(@@ -96,21 +150,288 @@ def resolution_acknowledgement() -> str:"""The reply a person gets after their answer resolves a gate."""decision = str(resolution.parsed_decision.get("decision") or "")- verb = _DECISION_VERBS.get(decision, "Recorded")+ verb = DECISION_VERBS.get(decision, "Recorded")title = ""+ resumable = Falsetry:run = _wf_persistence.get_run(run_id, db_path=db_path)if run:title = str(run.get("title") or run.get("workflow_name") or "")+ resumable = bool(run.get("resume_state_json"))except Exception:logger.exception("resumer: could not read run %s for acknowledgement", run_id)+ if not resumable:+ tail = _ACK_PAUSE_ONLY+ elif decision in STOP_DECISIONS:+ tail = _ACK_STOPPED+ else:+ tail = _ACK_RESUMING+subject = f" — {title}" if title else ""- return (- f"{verb}{subject}. That's recorded against the sign-off and closes it "- "out. The workflow doesn't pick up from here on its own, so tell me if "- "you want me to take the next step."+ return f"{verb}{subject}. {tail}"+++# Strong refs to in-flight kick tasks. asyncio only holds a weak reference to+# a task, so without this the garbage collector can cancel a resume mid-run.+_KICK_TASKS: set[asyncio.Task[None]] = set()+++def _abandon_resume(run_id: str, reason: str, db_path: Path | None = None) -> None:+ """End a run whose resume crashed, and take it off the resumable queue.++ Both entry points use this so they cannot diverge. Failing fast rather+ than retrying is deliberate: the run has already paid for its pre-gate+ specialist calls, a retry re-pays for every step after the gate with no+ guarantee of a different outcome, and a silent 30-minute retry loop hides+ a broken workflow from the person who approved it. The stale-resume sweep+ is left for the one case it was built for — the worker DIED, so no handler+ ran at all.+ """+ import contextlib++ with contextlib.suppress(Exception):+ _wf_persistence.fail_run(run_id, reason)+ with contextlib.suppress(Exception):+ _wf_persistence.clear_resume_state(run_id, db_path=db_path)+++def _kick_resume(run_id: str, db_path: Path | None = None) -> None:+ """Start executing a just-resolved run now, instead of at the next poll.++ Fire-and-forget by design: the caller is an inbound chat handler that must+ answer the human promptly, not wait on specialist calls. If the task never+ runs or dies, `_process_resumable` picks the run up within a tick — the+ claim is shared, so the two can never both execute it.+ """+ try:+ loop = asyncio.get_running_loop()+ except RuntimeError: # pragma: no cover - no loop in a sync caller+ logger.debug("resumer: no running loop, leaving run %s to the poll", run_id)+ return++ async def _run() -> None:+ try:+ if not _wf_persistence.claim_run_for_resume(run_id, db_path=db_path):+ return+ row = _load_resumable_row(run_id, db_path=db_path)+ if row is not None:+ await _execute_resume(row, db_path=db_path)+ except Exception:+ logger.exception("resumer: kicked resume failed for run_id=%s", run_id)+ _abandon_resume(run_id, "resume failed unexpectedly", db_path=db_path)++ task = loop.create_task(_run())+ _KICK_TASKS.add(task)+ task.add_done_callback(_KICK_TASKS.discard)+++def _load_resumable_row(run_id: str, db_path: Path | None = None) -> dict | None:+ """The row shape `_execute_resume` expects, for a single claimed run."""+ run = _wf_persistence.get_run(run_id, db_path=db_path)+ if run is None or not run.get("resume_state_json"):+ return None+ return {+ "run_id": run_id,+ "workflow_name": run.get("workflow_name") or "",+ "title": run.get("title") or "",+ "inputs": run.get("inputs") or {},+ "resume_state_json": run["resume_state_json"],+ "resolution_json": run.get("resolution_json"),+ }+++async def _process_resumable(now: datetime, db_path: Path | None = None) -> int:+ """Claim and execute every resolved run that carries a resume payload.++ Returns how many runs were executed. Per-run exception isolation, matching+ `_handle_timeout`: one bad run must never stop the sweep.+ """+ import sqlite3++ # Crash recovery first, so a run stranded by a dead worker is back in the+ # queue before we read it.+ for stale_id in _wf_persistence.list_stale_resuming_runs(+ now - _RESUME_STALE_AFTER, _MAX_RESUME_ATTEMPTS, db_path=db_path+ ):+ if _wf_persistence.requeue_run_for_resume(stale_id, db_path=db_path):+ logger.warning(+ "resumer: run %s was claimed for resume but never finished — requeued",+ stale_id,+ )++ executed = 0+ for row in _wf_persistence.list_resumable_runs(db_path=db_path):+ run_id = row["run_id"]+ try:+ claimed = _wf_persistence.claim_run_for_resume(run_id, db_path=db_path)+ except sqlite3.OperationalError:+ # The DB is shared with the scheduler, the API and the chat bots.+ # A lock here means "someone else is writing", not "this run is+ # broken" — leave it for the next tick rather than failing it.+ logger.warning("resumer: database busy claiming run %s — next tick", run_id)+ continue+ if not claimed:+ continue # a kick, or another worker, got there first+ try:+ await _execute_resume(row, db_path=db_path)+ executed += 1+ except Exception:+ logger.exception("resumer: resume failed for run_id=%s", run_id)+ _abandon_resume(run_id, "resume failed unexpectedly", db_path=db_path)+ if executed:+ logger.info("resumer: executed %d resumed run(s)", executed)+ return executed+++async def _execute_resume(row: dict, db_path: Path | None = None) -> None:+ """Drive one claimed run's remaining steps to a terminal state.++ Assumes the caller already won `claim_run_for_resume`, so the row is ours+ and sits in `running`.+ """+ import contextlib++ from openexecutive.audit import log_event as audit_log+ from openexecutive.config import get_settings+ from openexecutive.knowledge.store import ChromaDBStore+ from openexecutive.workflows import get_workflow+ from openexecutive.workflows.dynamic import DynamicWorkflow+ from openexecutive.workflows.dynamic_store import get_definition+ from openexecutive.workflows.gate import checkpoint_gate+ from openexecutive.workflows.wait_for_human import WaitForHumanEvent++ run_id = row["run_id"]+ name = row["workflow_name"]++ def _abort(reason: str) -> None:+ logger.warning("resumer: cannot resume run %s — %s", run_id, reason)+ _abandon_resume(run_id, reason, db_path=db_path)++ try:+ state = WorkflowResumeState.model_validate_json(row["resume_state_json"])+ except Exception:+ logger.exception("resumer: unreadable resume payload for run %s", run_id)+ _abort("the stored resume payload could not be read")+ return++ resolution = _resolution_from_row(row, run_id)++ try:+ workflow = get_workflow(name)+ except KeyError:+ # Tell the two cases apart — "you deleted it" and "you switched it+ # off" need different things from the reader.+ definition = None+ with contextlib.suppress(Exception):+ definition = get_definition(name)+ _abort(+ f"the custom workflow {name!r} was "+ + ("deactivated" if definition is not None else "deleted")+ + " while this run was awaiting approval"+ )+ return++ if not isinstance(workflow, DynamicWorkflow):+ # `get_workflow` checks the built-in registry first, so a dynamic+ # workflow's name can be shadowed by a built-in added later.+ _abort(+ f"{name!r} is no longer a custom workflow, so this run cannot be resumed"+ )+ return++ try:+ inputs = workflow.input_model().model_validate(row["inputs"])+ except Exception as exc:+ _abort(f"the workflow's inputs no longer validate: {exc}")+ return++ store = ChromaDBStore(persist_directory=get_settings().vector_store_path)+ artifact = ""+ last_error = ""+ # No handler here: a crash propagates to the caller, which routes it+ # through `_abandon_resume` — the one failure path both entry points share.+ async for event in workflow.resume(+ inputs=inputs, state=state, resolution=resolution, store=store+ ):+ if isinstance(event, WaitForHumanEvent):+ # A SECOND gate. Re-checkpoint through the same helper the+ # other runners use: that flips running -> awaiting_human,+ # stores the fresh payload, and clears gate 1's resolution so+ # this run is not immediately re-claimed on its old answer.+ await checkpoint_gate(+ run_id=run_id,+ event=event,+ workflow_title=workflow.title,+ db_path=db_path,+ )+ audit_log(+ "workflow_resume",+ f"run {run_id} resumed and paused again at a later gate",+ actor="resumer",+ details={+ "run_id": run_id,+ "workflow": name,+ "gate_step_id": state.gate_step_id,+ "outcome": "awaiting_human",+ },+ )+ return+ if event.type == "artifact" and event.content:+ artifact = event.content+ elif event.type == "error" and event.message:+ last_error = event.message++ decision = str(resolution.parsed_decision.get("decision") or "")+ if artifact:+ with contextlib.suppress(Exception):+ _wf_persistence.complete_run(run_id, artifact)+ outcome = "done"+ else:+ message = last_error or "resume finished without producing an artifact"+ with contextlib.suppress(Exception):+ _wf_persistence.fail_run(run_id, message)+ outcome = "error"+ with contextlib.suppress(Exception):+ _wf_persistence.clear_resume_state(run_id, db_path=db_path)++ audit_log(+ "workflow_resume",+ f"run {run_id} resumed after {decision or 'a'} decision -> {outcome}",+ actor="resumer",+ details={+ "run_id": run_id,+ "workflow": name,+ "gate_step_id": state.gate_step_id,+ "decision": decision,+ "outcome": outcome,+ "artifact_chars": len(artifact),+ },+ )+ logger.info("resumer: run %s resumed -> %s", run_id, outcome)+++def _resolution_from_row(row: dict, run_id: str) -> WaitForHumanResolution:+ """The stored resolution, or a neutral stand-in if it cannot be read.++ A missing or corrupt `resolution_json` must not strand a run that has+ already paid for its pre-gate steps: continue with an explicit "unknown"+ decision, which is neither an approval nor a rejection, so the run+ completes and the ambiguity is visible in the artifact.+ """+ raw = row.get("resolution_json")+ if raw:+ try:+ return WaitForHumanResolution.model_validate_json(raw)+ except Exception:+ logger.exception("resumer: unreadable resolution for run %s", run_id)+ return WaitForHumanResolution(+ run_id=run_id,+ reply_text="",+ source_channel="system",+ parsed_decision={"decision": "unknown", "note": "resolution unreadable"},+ person_id=0,)@@ -160,6 +481,10 @@ async def _handle_timeout(run: dict, now: datetime) -> None:run_id,)_wf_persistence.mark_timed_out(run_id)+ # `timed_out` is terminal: nobody answered, so the payload will never+ # be replayed. Dropping it keeps the completed-step text out of a row+ # nothing will read, and keeps the run off the resumable queue.+ _wf_persistence.clear_resume_state(run_id)elif on_timeout == "auto_proceed":auto_resolution = WaitForHumanResolution(@@ -237,6 +562,14 @@ async def run_resumer(poll_interval_seconds: int = 60) -> None:swept = await sweep_stale_awaiting()if swept:logger.info("resumer: startup sweep processed %d stale run(s)", swept)+ # Replies that landed while the server was down are already `resolved`;+ # execute them now rather than after a first full poll interval.+ try:+ resumed = await _process_resumable(datetime.now(UTC))+ if resumed:+ logger.info("resumer: startup resumed %d run(s)", resumed)+ except Exception:+ logger.exception("resumer: startup resume sweep failed")while True:try:now = datetime.now(UTC)@@ -278,3 +611,10 @@ async def _tick(now: datetime) -> None:await _handle_timeout(run, now)except Exception:logger.exception("resumer: _handle_timeout failed for run_id=%s", run.get("run_id"))++ # AFTER the timeout loop, deliberately: `_handle_timeout`'s auto_proceed+ # branch resolves a run, and running the executor second means that run+ # executes in the SAME tick. That ordering is the whole reason+ # `on_timeout='auto_proceed'` now does what its name says, with no+ # special-casing anywhere.+ await _process_resumable(now)diff --git a/packages/core/openexecutive/workflows/wait_for_human.py b/packages/core/openexecutive/workflows/wait_for_human.pyindex bf68a38c..de20e061 100644--- a/packages/core/openexecutive/workflows/wait_for_human.py+++ b/packages/core/openexecutive/workflows/wait_for_human.py@@ -9,9 +9,17 @@ resolver (Slack / Telegram / email hooks) calls ``apply_resolution`` whena human replies, which stores the ``WaitForHumanResolution`` and advancesthe run to ``status='resolved'``.-Phase 6 note: full generator resume (deserialising the execution frame) is-deferred to Phase 7. This module ships the data model and ``parse_decision``-— the pieces needed for timeout handling and resolution recording.+Resume+------+A gate that carries a :class:`WorkflowResumeState` is *resumable*: once the+decision is recorded, ``resumer._execute_resume`` re-enters the workflow at+the step after the gate and drives it to an artifact. Nothing serialises a+Python generator frame — the state is the small, plain-JSON payload below,+and the engine replays its step loop from an index.++A gate with no resume state is *pause-only*: the decision is recorded and+the run stops there. That is what every caller got before resume existed,+and it is still what a workflow yielding a bare ``WaitForHumanEvent`` gets."""from __future__ import annotations@@ -25,6 +33,33 @@ logger = logging.getLogger(__name__)_CONFIDENCE_THRESHOLD = 0.85+class WorkflowResumeState(BaseModel):+ """Everything needed to restart a paused workflow at the step after its gate.++ Deliberately NOT a serialised generator frame. The only values alive+ across a dynamic workflow's steps are its inputs (already persisted in+ ``workflow_runs.inputs``), a company-profile block that is recomputed on+ resume, the completed steps' outputs, and the loop cursor — all plain+ JSON, which is why re-entering a paused run needs no frame surgery.++ ``version`` and ``engine`` are checked on load so a payload written by an+ older build, or by a different engine, is REJECTED rather than+ misinterpreted into resuming at the wrong step.+ """++ version: Literal[1] = 1+ engine: str = "dynamic"+ workflow_name: str+ gate_step_id: str+ # Index of the gate itself, re-checked against the live definition on+ # resume — a definition edited during the pause can move it.+ gate_step_index: int+ next_step_index: int+ # step_id -> (step title, output text) for every step completed before the+ # gate. Round-trips through JSON as a 2-array and back to a tuple.+ outputs: dict[str, tuple[str, str]] = Field(default_factory=dict)++class WaitForHumanEvent(BaseModel):"""Yielded by a workflow step that requires human approval or input.@@ -63,6 +98,17 @@ class WaitForHumanEvent(BaseModel):# another thread. Empty for web/scheduler-originated runs, which fall back# to channel matching.origin_session_id: str = ""+ # Engine payload for continuing the run after the gate is answered.+ # `exclude=True` is load-bearing: `state_json` is the checkpoint the+ # inbound resolver reads, and it branches on which keys are PRESENT (a row+ # with no `delivery` key is a pre-delivery legacy row). Excluding at the+ # FIELD level rather than per-call means no serialisation site can leak+ # the payload into that JSON by forgetting to. The payload has its own+ # column, `workflow_runs.resume_state_json`.+ # None means pause-only: the decision is recorded and the run stops.+ resume_state: WorkflowResumeState | None = Field(+ default=None, exclude=True, repr=False+ )# Outbound channel vocabulary (`slack_dm`, `discord_dm`) differs from the@@ -82,6 +128,30 @@ def normalize_channel(channel: str) -> str:return _CHANNEL_ALIASES.get(key, key)+# The decision vocabulary, owned here because three places render it: the+# acknowledgement the approver gets back (`resumer.resolution_acknowledgement`),+# the section a resumed run writes into its artifact+# (`dynamic._format_resolution`), and the branch that decides whether the run+# continues. Two copies would drift, and a run whose artifact says "Approved"+# while its acknowledgement says "Declined" is worse than either alone.+DECISION_VERBS: dict[str, str] = {+ "approve": "Approved",+ "reject": "Declined",+ "defer": "Deferred",+ "auto_proceed": "Auto-approved on timeout",+}++# Decisions that STOP a resumable run rather than continuing it. A human who+# declined or deferred did not ask for the remaining steps to be paid for and+# delivered, so the run ends at `error` with their note.+#+# Note this is only reachable for a REAL verdict: `inbound_resolver` drops+# `unrelated` replies and parser fallbacks before `apply_resolution`, so a+# `defer` arriving here is a person deferring, never a parse failure wearing+# a defer's clothes.+STOP_DECISIONS = frozenset({"reject", "defer"})++class WaitForHumanResolution(BaseModel):"""Recorded when a human successfully replies to a WaitForHumanEvent."""diff --git a/packages/core/tests/unit/test_doc_code_consistency.py b/packages/core/tests/unit/test_doc_code_consistency.pyindex 267ae4d1..121d05bf 100644--- a/packages/core/tests/unit/test_doc_code_consistency.py+++ b/packages/core/tests/unit/test_doc_code_consistency.py@@ -6,9 +6,10 @@ actually does — the failure mode the ``/architecture`` page is most prone toBOTH the YAML and the code, so changing one without the other breaks CI.Current coverage: the ``wait_for_human`` resume invariant (the canonical drift-example — docs once claimed paused workflows auto-continue while the code-defers full generator resume to "Phase 7"). Add further invariants here as-they are identified.+example — the docs and the code have now disagreed in BOTH directions, first+claiming paused workflows auto-continued when they did not, and later still+calling resume deferred after it shipped). Add further invariants here as they+are identified."""from __future__ import annotations@@ -30,45 +31,69 @@ def _resumer_source() -> str:return Path(resumer.__file__).read_text()-def test_resumer_still_defers_full_generator_resume() -> None:- """Pins the code reality the docs describe: full generator resume is NOT- implemented (deferred to "Phase 7"). If someone implements it and removes- the marker, this fails — prompting them to update both the code note and- the architecture facts (see the doc test below)."""- src = _resumer_source()- assert "Phase 7" in src, (- "resumer.py no longer marks full generator resume as deferred. If "- "resume was implemented, update architecture-facts.yaml "- "(workflows.human_in_the_loop) and this test together."+def _code_resumes() -> bool:+ """Whether the code can actually continue a run past its gate.++ Structural, not textual: the executor and the engine entry point must both+ exist. A comment can be edited to say anything; these cannot.+ """+ from openexecutive.workflows.dynamic import DynamicWorkflow++ return (+ hasattr(resumer, "_execute_resume")+ and hasattr(resumer, "_process_resumable")+ and hasattr(DynamicWorkflow, "resume")+ )+++def test_resumer_implements_generator_resume() -> None:+ """Pins the shipped reality: a resolved run with a resume payload is+ claimed and executed. Previously this guard pinned the OPPOSITE — that+ resume was deferred to "Phase 7" — and it fired when resume landed, which+ is exactly what it was for. It now guards the other direction: if the+ executor is removed or renamed, update the facts and this test together."""+ assert _code_resumes(), (+ "resumer no longer exposes the resume executor. If resume was removed, "+ "update architecture-facts.yaml (workflows.human_in_the_loop) and this "+ "test together.")- # The capture path that IS shipped must still exist...+ # The capture path resume builds on must still exist.assert hasattr(resumer, "apply_resolution")- # ...and no public auto-continue entry point should exist yet.- assert not hasattr(resumer, "resume_run")- assert not hasattr(resumer, "continue_run")+ # The deferral marker must be gone from the source, or the module is+ # describing behaviour it no longer has.+ assert "Phase 7" not in _resumer_source(), (+ "resumer.py still marks full generator resume as deferred to Phase 7, "+ "but the executor exists. Remove the stale note."+ )-def test_hitl_doc_does_not_overclaim_resume() -> None:- """The facts must not claim paused workflows auto-continue while the code- defers that — the exact drift this guard exists to catch."""+def test_hitl_doc_does_not_understate_resume() -> None:+ """The facts must not still describe resume as unshipped now that it is.++ The mirror of the original guard: that one caught the docs overclaiming,+ this one catches them underclaiming. Both are the same failure — the page+ saying something the code does not do."""hitl = _load_facts()["workflows"]["human_in_the_loop"]- # The retired overclaim: resumer "continues the next step".- assert "continues the next step" not in hitl, (- "architecture-facts.yaml claims wait_for_human continues the next "- "step, but resumer.py defers full generator resume to Phase 7."+ assert "NOT YET SHIPPED" not in hitl, (+ "architecture-facts.yaml still lists a NOT YET SHIPPED resume gap, but "+ "resumer executes resolved runs."+ )+ assert "Phase 7" not in hitl+ # And it must positively describe the mechanism, so the doc is useful and+ # not merely silent about it.+ assert "resume_state_json" in hitl, (+ "workflows.human_in_the_loop should name the column the resume payload "+ "is stored in, so the page explains HOW a run continues.")- # And it must positively signal the deferral so the doc stays honest.- assert ("Phase 7" in hitl) or ("NOT YET SHIPPED" in hitl)def test_hitl_doc_and_code_agree_on_resume() -> None:- """Couple the two directly: if the code defers resume, the doc must say so- (and vice versa). The one assertion that ties code reality to the page."""- code_defers = "Phase 7" in _resumer_source()+ """Couple the two directly: the doc admits a resume gap if and only if the+ code has one. The one assertion that ties code reality to the page."""hitl = _load_facts()["workflows"]["human_in_the_loop"]doc_admits_gap = ("Phase 7" in hitl) or ("NOT YET SHIPPED" in hitl)- assert code_defers == doc_admits_gap, (+ assert _code_resumes() != doc_admits_gap, ("Resume status disagrees between resumer.py and architecture-facts.yaml ""(workflows.human_in_the_loop). Update both.")diff --git a/packages/core/tests/unit/test_dynamic_workflow_resume.py b/packages/core/tests/unit/test_dynamic_workflow_resume.pynew file mode 100644index 00000000..3b4c39d3--- /dev/null+++ b/packages/core/tests/unit/test_dynamic_workflow_resume.py@@ -0,0 +1,361 @@+"""DynamicWorkflow.resume — continuing a run past an answered approval gate.++The engine half of resume. `test_resumer.py` covers the background executor+that calls into this; here the question is only whether the step loop picks up+at the right place, with the right state, and refuses when it cannot.+"""+from __future__ import annotations++import os+from typing import Any+from unittest.mock import MagicMock++import pytest++os.environ.setdefault("ANTHROPIC_API_KEY", "sk-test-not-used")++from openexecutive.workflows import dynamic as dyn # noqa: E402+from openexecutive.workflows.dynamic import DynamicWorkflow # noqa: E402+from openexecutive.workflows.dynamic_models import DynamicWorkflowDef # noqa: E402+from openexecutive.workflows.wait_for_human import ( # noqa: E402+ WaitForHumanEvent,+ WaitForHumanResolution,+ WorkflowResumeState,+)++[email protected](autouse=True)+def _stub_context(monkeypatch: pytest.MonkeyPatch) -> None:+ """No real profile / RAG / specialist calls."""+ fake_profile = MagicMock()+ fake_profile.name = "Acme"+ fake_profile.is_empty.return_value = True+ monkeypatch.setattr(dyn, "load_or_create_profile", lambda: fake_profile)+ monkeypatch.setattr(dyn, "retrieve", lambda **kw: "")+++def _def(steps: list[dict[str, Any]] | None = None, **overrides: Any) -> DynamicWorkflowDef:+ base: dict[str, Any] = {+ "name": "weekly_watch",+ "title": "Weekly Watch",+ "input_fields": [{"name": "topic", "label": "Topic", "required": True}],+ "steps": steps+ or [+ {"kind": "specialist", "id": "research", "title": "Research",+ "specialist": "cso", "goal": "Analyze {topic}."},+ {"kind": "approval_gate", "id": "gate", "title": "Approve",+ "person_id": 7, "question": "OK to proceed on {topic}?"},+ {"kind": "specialist", "id": "plan", "title": "Plan",+ "specialist": "coo", "goal": "Plan for {topic}."},+ {"kind": "synthesis", "id": "assemble", "title": "Assemble"},+ ],+ }+ base.update(overrides)+ return DynamicWorkflowDef.model_validate(base)+++def _route(calls: list[dict[str, Any]], monkeypatch: pytest.MonkeyPatch) -> None:+ async def fake_route(**kwargs: Any) -> str:+ calls.append(kwargs)+ return f"output for {kwargs.get('specialist_name')}"++ monkeypatch.setattr(dyn, "route_to_specialist", fake_route)+++def _state(**overrides: Any) -> WorkflowResumeState:+ base: dict[str, Any] = {+ "workflow_name": "weekly_watch",+ "gate_step_id": "gate",+ "gate_step_index": 1,+ "next_step_index": 2,+ "outputs": {"research": ("Research", "the research output")},+ }+ base.update(overrides)+ return WorkflowResumeState.model_validate(base)+++def _resolution(decision: str = "approve", **overrides: Any) -> WaitForHumanResolution:+ base: dict[str, Any] = {+ "run_id": "r1",+ "reply_text": "yes go ahead",+ "source_channel": "slack",+ "parsed_decision": {"decision": decision, "note": "looks good"},+ "person_id": 7,+ "resolved_at": "2026-09-18T10:00:00+00:00",+ }+ base.update(overrides)+ return WaitForHumanResolution.model_validate(base)+++async def _resume(wf: DynamicWorkflow, state: WorkflowResumeState,+ resolution: WaitForHumanResolution) -> list[Any]:+ inputs = wf.input_model()(topic="pricing")+ return [+ e+ async for e in wf.resume(+ inputs=inputs, state=state, resolution=resolution, store=MagicMock()+ )+ ]+++def _artifact(events: list[Any]) -> str:+ for e in events:+ if getattr(e, "type", None) == "artifact":+ return e.content or ""+ return ""+++def _errors(events: list[Any]) -> list[str]:+ return [e.message or "" for e in events if getattr(e, "type", None) == "error"]+++# ---------------------------------------------------------------------------+# The happy path+# ---------------------------------------------------------------------------++async def test_resume_runs_the_steps_after_the_gate(monkeypatch: pytest.MonkeyPatch) -> None:+ """The whole point: the step after the gate executes and an artifact+ appears. Before resume existed, both were silently dropped."""+ calls: list[dict[str, Any]] = []+ _route(calls, monkeypatch)++ events = await _resume(DynamicWorkflow(_def()), _state(), _resolution())++ # Only the post-gate specialist runs — the pre-gate one is NOT re-paid for.+ assert [c["specialist_name"] for c in calls] == ["coo"]+ artifact = _artifact(events)+ assert artifact, "resume must produce the artifact the paused run never reached"+ assert "the research output" in artifact, "pre-gate work must survive the pause"+ assert "output for coo" in artifact+++async def test_resume_records_the_decision_in_the_artifact(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The gate is a step, so it gets an output like any other — which is how+ the decision reaches the artifact instead of only a database column."""+ _route([], monkeypatch)+ artifact = _artifact(await _resume(DynamicWorkflow(_def()), _state(), _resolution()))+ assert "Approved" in artifact+ assert "looks good" in artifact+ assert "person 7" in artifact and "slack" in artifact+++async def test_resume_closes_the_gate_step_for_the_client(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The original run emitted `step_start` for the gate and never closed it;+ a re-attached client would show it running forever."""+ _route([], monkeypatch)+ events = await _resume(DynamicWorkflow(_def()), _state(), _resolution())+ done = [e.step_id for e in events if getattr(e, "type", None) == "step_done"]+ assert "gate" in done+ assert done[0] == "context", "resume reloads context first, like a fresh run"+++async def test_synthesis_sees_the_decision(monkeypatch: pytest.MonkeyPatch) -> None:+ """A synthesis step with instructions consults a specialist over the+ drafts; the human's answer must be among them, or the artifact can+ contradict the sign-off it was gated on."""+ calls: list[dict[str, Any]] = []+ _route(calls, monkeypatch)+ defn = _def(steps=[+ {"kind": "specialist", "id": "research", "title": "Research",+ "specialist": "cso", "goal": "Analyze {topic}."},+ {"kind": "approval_gate", "id": "gate", "title": "Approve",+ "person_id": 7, "question": "OK?"},+ {"kind": "synthesis", "id": "assemble", "title": "Assemble",+ "instructions": "Write it up.", "specialist": "cso"},+ ])+ await _resume(DynamicWorkflow(defn), _state(next_step_index=2), _resolution())+ assert any("Approved" in str(c.get("query", "")) for c in calls)+++async def test_auto_proceed_is_labelled_as_unanswered(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A timeout auto-approval must not read as a human saying yes."""+ _route([], monkeypatch)+ resolution = _resolution(+ "auto_proceed",+ source_channel="system",+ parsed_decision={"decision": "auto_proceed", "note": "timeout"},+ )+ artifact = _artifact(await _resume(DynamicWorkflow(_def()), _state(), resolution))+ assert "No human reply" in artifact+++# ---------------------------------------------------------------------------+# Declining+# ---------------------------------------------------------------------------+[email protected]("decision", ["reject", "defer"])+async def test_a_decline_stops_the_run(+ decision: str, monkeypatch: pytest.MonkeyPatch+) -> None:+ """Everything after a sign-off exists to act on a yes. Producing the+ deliverable anyway would hand back the thing they just declined."""+ calls: list[dict[str, Any]] = []+ _route(calls, monkeypatch)++ events = await _resume(+ DynamicWorkflow(_def()),+ _state(),+ _resolution(decision, parsed_decision={"decision": decision, "note": "too risky"}),+ )++ assert calls == [], "no further specialist may be paid for after a decline"+ assert _artifact(events) == ""+ assert _errors(events), "the run must fail, not end silently"+ assert "too risky" in _errors(events)[0]+++# ---------------------------------------------------------------------------+# Refusing to resume+# ---------------------------------------------------------------------------++async def test_resume_refuses_when_the_gate_moved(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """`upsert_definition` overwrites by name, so a definition edited during+ the pause can re-point the stored index at a different step. Resuming+ anyway would skip or repeat work and produce a plausible wrong artifact."""+ calls: list[dict[str, Any]] = []+ _route(calls, monkeypatch)+ # A step inserted before the gate shifts it from index 1 to index 2.+ edited = _def(steps=[+ {"kind": "specialist", "id": "research", "title": "Research",+ "specialist": "cso", "goal": "Analyze {topic}."},+ {"kind": "specialist", "id": "inserted", "title": "Inserted",+ "specialist": "cfo", "goal": "Cost {topic}."},+ {"kind": "approval_gate", "id": "gate", "title": "Approve",+ "person_id": 7, "question": "OK?"},+ {"kind": "synthesis", "id": "assemble", "title": "Assemble"},+ ])++ events = await _resume(DynamicWorkflow(edited), _state(), _resolution())++ assert calls == []+ assert _artifact(events) == ""+ assert "definition changed" in _errors(events)[0]+++async def test_resume_refuses_an_index_pointing_at_a_non_gate(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The index can still be in range and still be wrong."""+ _route([], monkeypatch)+ events = await _resume(+ DynamicWorkflow(_def()), _state(gate_step_index=0, gate_step_id="research"),+ _resolution(),+ )+ assert "definition changed" in _errors(events)[0]+++async def test_resume_refuses_an_out_of_range_index(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _route([], monkeypatch)+ events = await _resume(DynamicWorkflow(_def()), _state(gate_step_index=99), _resolution())+ assert "definition changed" in _errors(events)[0]+++async def test_resume_refuses_a_payload_for_another_workflow(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _route([], monkeypatch)+ events = await _resume(+ DynamicWorkflow(_def()), _state(workflow_name="something_else"), _resolution()+ )+ assert "definition changed" in _errors(events)[0]+++async def test_resume_refuses_a_payload_from_another_engine(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """`engine` exists so a future non-dynamic payload is rejected rather than+ interpreted as step indices into a definition it never described."""+ _route([], monkeypatch)+ events = await _resume(DynamicWorkflow(_def()), _state(engine="something_new"), _resolution())+ assert "definition changed" in _errors(events)[0]+++async def test_resume_reruns_the_stale_specialist_preflight(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A specialist can be removed while the run sits at the gate. Finishing+ with 'Unknown specialist: …' as a section is worse than failing."""+ calls: list[dict[str, Any]] = []+ _route(calls, monkeypatch)+ monkeypatch.setattr(dyn, "SPECIALIST_REGISTRY", {"cso": object()})++ events = await _resume(DynamicWorkflow(_def()), _state(), _resolution())++ assert calls == []+ assert "no longer exists" in _errors(events)[0]+++# ---------------------------------------------------------------------------+# Two gates+# ---------------------------------------------------------------------------++async def test_a_second_gate_pauses_again_with_a_fresh_payload(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """`run()` and `resume()` share one step loop, so a later gate needs no+ special handling — it raises an identical pause, carrying everything+ accumulated across BOTH legs of the run."""+ _route([], monkeypatch)+ defn = _def(steps=[+ {"kind": "specialist", "id": "research", "title": "Research",+ "specialist": "cso", "goal": "Analyze {topic}."},+ {"kind": "approval_gate", "id": "gate", "title": "Approve",+ "person_id": 7, "question": "OK?"},+ {"kind": "specialist", "id": "plan", "title": "Plan",+ "specialist": "coo", "goal": "Plan {topic}."},+ {"kind": "approval_gate", "id": "gate2", "title": "Final sign-off",+ "person_id": 7, "question": "Ship it?"},+ {"kind": "synthesis", "id": "assemble", "title": "Assemble"},+ ])++ events = await _resume(DynamicWorkflow(defn), _state(), _resolution())++ gates = [e for e in events if isinstance(e, WaitForHumanEvent)]+ assert len(gates) == 1+ assert gates[0].question == "Ship it?"+ second = gates[0].resume_state+ assert second is not None+ assert second.gate_step_id == "gate2"+ assert second.gate_step_index == 3+ assert second.next_step_index == 4+ # Everything so far: the pre-gate step, the recorded decision, and the+ # step the resumed leg just ran.+ assert set(second.outputs) == {"research", "gate", "plan"}+ assert _artifact(events) == ""+++# ---------------------------------------------------------------------------+# state_json shape+# ---------------------------------------------------------------------------++def test_resume_state_never_reaches_state_json() -> None:+ """`state_json` is what the inbound resolver reads, and it branches on+ which keys are PRESENT. The payload is excluded at the field level so no+ serialization site can leak it by forgetting to."""+ bare = WaitForHumanEvent(person_id=1, question="q")+ loaded = WaitForHumanEvent(person_id=1, question="q", resume_state=_state())+ assert loaded.model_dump_json() == bare.model_dump_json()+ assert "resume_state" not in loaded.model_dump()diff --git a/packages/core/tests/unit/test_dynamic_workflow_run.py b/packages/core/tests/unit/test_dynamic_workflow_run.pyindex 563d670c..4571d514 100644--- a/packages/core/tests/unit/test_dynamic_workflow_run.py+++ b/packages/core/tests/unit/test_dynamic_workflow_run.py@@ -116,6 +116,16 @@ async def test_run_pauses_at_approval_gate(monkeypatch: pytest.MonkeyPatch) -> N# Run stops at the gate — no artifact emitted.assert not any(getattr(e, "type", None) == "artifact" for e in events)+ # The gate carries everything needed to pick the run back up: which step+ # it stopped at, where to continue, and what the earlier steps produced.+ state = gates[0].resume_state+ assert state is not None+ assert state.workflow_name == "weekly_watch"+ assert state.gate_step_id == "gate"+ assert state.gate_step_index == 1+ assert state.next_step_index == 2+ assert state.outputs == {"research": ("Research", "section")}+@pytest.mark.asyncioasync def test_run_synthesis_with_instructions_calls_specialist(diff --git a/packages/core/tests/unit/test_gate_delivery.py b/packages/core/tests/unit/test_gate_delivery.pyindex eeba9ff1..49d5c660 100644--- a/packages/core/tests/unit/test_gate_delivery.py+++ b/packages/core/tests/unit/test_gate_delivery.py@@ -350,3 +350,30 @@ def test_an_unknown_channel_leaves_the_gate_unscoped() -> None:routed, _ = _deliver(_gate())assert routed.origin_session_id == ""+++def test_delivery_preserves_the_resume_payload() -> None:+ """`deliver_gate_question` returns a `model_copy`, and that it carries+ unlisted fields through is load-bearing: the engine attaches the resume+ payload BEFORE delivery, so a delivery path that rebuilt the event instead+ would silently turn every gate pause-only — the run would park forever and+ nothing would ever continue it.+ """+ from openexecutive.workflows.wait_for_human import WorkflowResumeState++ state = WorkflowResumeState(+ workflow_name="weekly_watch",+ gate_step_id="gate",+ gate_step_index=1,+ next_step_index=2,+ outputs={"research": ("Research", "body")},+ )+ event = WaitForHumanEvent(person_id=7, question="OK?", resume_state=state)++ # The self-approval path returns early via model_copy; any mode would do.+ copied = event.model_copy(update={"delivery": "sent", "channel": "slack"})++ assert copied.resume_state is not None+ assert copied.resume_state.gate_step_id == "gate"+ # ...and it still never reaches the checkpoint JSON the resolver reads.+ assert "resume_state" not in copied.model_dump_json()diff --git a/packages/core/tests/unit/test_gate_helper.py b/packages/core/tests/unit/test_gate_helper.pynew file mode 100644index 00000000..9b710c51--- /dev/null+++ b/packages/core/tests/unit/test_gate_helper.py@@ -0,0 +1,237 @@+"""`workflows.gate` — the one place a gate becomes a persisted pause.++Three runners can pause (the SSE route, the chat tool, the resumer at a second+gate) and nine cannot. This module covers the shared helper both halves go+through, so the invariants live in one place instead of being re-proved at+each call site.+"""+from __future__ import annotations++import json+from datetime import UTC, datetime, timedelta+from pathlib import Path+from typing import Any++import pytest++from openexecutive.workflows import persistence as wf_persistence+from openexecutive.workflows.base import WorkflowEvent+from openexecutive.workflows.gate import (+ UnsupportedGateError,+ checkpoint_gate,+ ensure_workflow_event,+)+from openexecutive.workflows.wait_for_human import (+ WaitForHumanEvent,+ WorkflowResumeState,+)++[email protected](autouse=True)+def _isolate_audit(monkeypatch: pytest.MonkeyPatch) -> None:+ """Keep audit writes out of the default ./episodic_memory.db.++ `audit.log_event` writes to the module default unless patched, and the+ leaked rows only break *other* modules' assertions in a full-suite run.+ """+ import openexecutive.audit as audit+ monkeypatch.setattr(audit, "log_event", lambda *a, **k: None)+++def db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ path = tmp_path / "wf.db"+ monkeypatch.setattr(wf_persistence, "DB_PATH", path)+ import openexecutive.memory.episodic as ep+ monkeypatch.setattr(ep, "DB_PATH", path)+ ep.initialize_db(path)+ wf_persistence.initialize_runs_db(path)+ wf_persistence.create_run("r1", "weekly_watch", "Weekly Watch", {"topic": "x"},+ db_path=path)+ return path+++def _stub_delivery(+ monkeypatch: pytest.MonkeyPatch,+ status: str = "sent",+ **updates: Any,+) -> None:+ """Stand in for gate_delivery, which is covered by its own module."""+ async def _deliver(event: WaitForHumanEvent, **_: Any) -> tuple[WaitForHumanEvent, str]:+ return event.model_copy(update={"delivery": status, **updates}), status++ monkeypatch.setattr(+ "openexecutive.workflows.gate_delivery.deliver_gate_question", _deliver+ )+++def _gate(**overrides: Any) -> WaitForHumanEvent:+ base: dict[str, Any] = {"person_id": 7, "question": "Approve?", "timeout_hours": 24}+ base.update(overrides)+ return WaitForHumanEvent.model_validate(base)+++def _resume_state() -> WorkflowResumeState:+ return WorkflowResumeState(+ workflow_name="weekly_watch",+ gate_step_id="gate",+ gate_step_index=1,+ next_step_index=2,+ outputs={"research": ("Research", "body")},+ )+++def _row(db: Path) -> dict:+ import sqlite3+ conn = sqlite3.connect(str(db))+ conn.row_factory = sqlite3.Row+ row = conn.execute("SELECT * FROM workflow_runs WHERE run_id = 'r1'").fetchone()+ conn.close()+ return dict(row)+++# ---------------------------------------------------------------------------+# checkpoint_gate+# ---------------------------------------------------------------------------++async def test_checkpoint_gate_parks_the_run(db: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ _stub_delivery(monkeypatch, channel="slack", channel_ref="U1", outbound_message_id="m1")++ pause = await checkpoint_gate(+ run_id="r1", event=_gate(resume_state=_resume_state()),+ workflow_title="Weekly Watch", db_path=db,+ )++ row = _row(db)+ assert row["status"] == "awaiting_human"+ assert row["awaiting_person_id"] == 7+ assert pause.delivery == "sent"+ assert pause.resumable is True+ assert pause.question == "Approve?"+++async def test_routing_fields_are_persisted_not_the_pre_delivery_event(+ db: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """Delivery runs BEFORE the checkpoint so `state_json` carries what a reply+ is matched against. Persisting the original event would leave the gate+ unanswerable on every channel — the #136 failure."""+ _stub_delivery(monkeypatch, channel="slack", channel_ref="U1", outbound_message_id="m1")++ await checkpoint_gate(run_id="r1", event=_gate(), db_path=db)++ state = json.loads(_row(db)["state_json"])+ assert state["channel"] == "slack"+ assert state["channel_ref"] == "U1"+ assert state["outbound_message_id"] == "m1"+++async def test_resume_payload_goes_to_its_own_column_not_state_json(+ db: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """The resolver branches on which keys `state_json` holds, so the payload+ must not appear there — and it must not be lost either."""+ _stub_delivery(monkeypatch)++ await checkpoint_gate(run_id="r1", event=_gate(resume_state=_resume_state()), db_path=db)++ row = _row(db)+ assert "resume_state" not in json.loads(row["state_json"])+ stored = json.loads(row["resume_state_json"])+ assert stored["gate_step_id"] == "gate"+ assert stored["next_step_index"] == 2+++async def test_payload_survives_the_delivery_copy(+ db: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """`deliver_gate_question` returns a `model_copy`. That it preserves+ unlisted fields is load-bearing and easy to break — a delivery path that+ rebuilt the event instead would silently make every gate pause-only."""+ _stub_delivery(monkeypatch, channel="slack", channel_ref="U1")++ pause = await checkpoint_gate(+ run_id="r1", event=_gate(resume_state=_resume_state()), db_path=db+ )++ assert pause.resumable is True+ assert _row(db)["resume_state_json"] is not None+++async def test_a_gate_without_a_payload_is_pause_only(+ db: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ _stub_delivery(monkeypatch)+ pause = await checkpoint_gate(run_id="r1", event=_gate(), db_path=db)+ assert pause.resumable is False+ assert _row(db)["resume_state_json"] is None+++async def test_undelivered_gate_still_checkpoints(+ db: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """A delivery failure must not lose the run — it is still parked, still+ times out, and the caller is told nobody was asked."""+ _stub_delivery(monkeypatch, status="failed")++ pause = await checkpoint_gate(run_id="r1", event=_gate(), db_path=db)++ assert pause.delivery == "failed"+ assert _row(db)["status"] == "awaiting_human"+++async def test_awaiting_until_follows_the_step_timeout(+ db: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ _stub_delivery(monkeypatch)+ now = datetime(2026, 1, 1, tzinfo=UTC)++ pause = await checkpoint_gate(+ run_id="r1", event=_gate(timeout_hours=6), now=now, db_path=db+ )++ assert pause.awaiting_until == now + timedelta(hours=6)+++async def test_a_persistence_failure_propagates(+ db: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """A caller must never report `awaiting_human` for a run that was not+ checkpointed: the resumer and the inbound resolver would both be unable to+ find it, and it would sit in `running` forever."""+ _stub_delivery(monkeypatch)++ def _boom(*a: Any, **k: Any) -> None:+ raise RuntimeError("disk on fire")++ monkeypatch.setattr("openexecutive.workflows.gate.save_checkpoint", _boom)++ with pytest.raises(RuntimeError, match="disk on fire"):+ await checkpoint_gate(run_id="r1", event=_gate(), db_path=db)+++# ---------------------------------------------------------------------------+# ensure_workflow_event+# ---------------------------------------------------------------------------++def test_ensure_workflow_event_passes_ordinary_events_through() -> None:+ event = WorkflowEvent(type="step_done", step_id="s1")+ assert ensure_workflow_event(event, site="test") is event+++def test_ensure_workflow_event_raises_on_a_gate() -> None:+ """These runners have no human to ask. Raising turns a gate into a named+ failure instead of a run that reports success having dropped every step+ after it."""+ with pytest.raises(UnsupportedGateError) as exc:+ ensure_workflow_event(_gate(), site="scheduler.dynamic_workflow")+ assert "scheduler.dynamic_workflow" in str(exc.value)+ assert "cannot pause" in str(exc.value)diff --git a/packages/core/tests/unit/test_resumer.py b/packages/core/tests/unit/test_resumer.pyindex 80ad2b72..b19f9da8 100644--- a/packages/core/tests/unit/test_resumer.py+++ b/packages/core/tests/unit/test_resumer.py@@ -41,8 +41,11 @@ def _seed_awaiting(awaiting_until: datetime | None = None,*,department: str = "",+ resume_state: str | None = None,+ workflow_name: str = "test_wf",+ inputs: dict | None = None,) -> None:- wf_persistence.create_run(run_id, "test_wf", "Test run", {})+ wf_persistence.create_run(run_id, workflow_name, "Test run", inputs or {})state = json.dumps({"on_timeout": on_timeout,"channel": "slack",@@ -52,7 +55,9 @@ def _seed_awaiting("department": department,})until = awaiting_until or datetime.now(UTC) - timedelta(minutes=1) # already expired- wf_persistence.save_checkpoint(run_id, state, person_id, until)+ wf_persistence.save_checkpoint(+ run_id, state, person_id, until, resume_state_json=resume_state+ )# ---------------------------------------------------------------------------@@ -247,3 +252,440 @@ def test_acknowledgement_survives_a_missing_run(tmp_path: Path) -> None:)assert text.startswith("Approved")+++# ---------------------------------------------------------------------------+# Resume — the background executor+# ---------------------------------------------------------------------------++_RESUME_STATE = json.dumps({+ "version": 1,+ "engine": "dynamic",+ "workflow_name": "weekly_watch",+ "gate_step_id": "gate",+ "gate_step_index": 1,+ "next_step_index": 2,+ "outputs": {"research": ["Research", "prior output"]},+})+++def _resolved(+ run_id: str = "res-1",+ decision: str = "approve",+ *,+ resume_state: str | None = _RESUME_STATE,+ workflow_name: str = "weekly_watch",+ inputs: dict | None = None,+) -> None:+ """A run sitting at `resolved` with (by default) a resume payload."""+ _seed_awaiting(+ run_id, 7, awaiting_until=datetime.now(UTC) + timedelta(hours=24),+ resume_state=resume_state, workflow_name=workflow_name,+ inputs=inputs if inputs is not None else {"topic": "pricing"},+ )+ wf_persistence.store_resolution(+ run_id,+ json.dumps({+ "run_id": run_id, "reply_text": "yes", "source_channel": "slack",+ "parsed_decision": {"decision": decision, "note": "fine"},+ "person_id": 7,+ }),+ )+++def _real_workflow(events: list | None = None): # noqa: ANN201+ """A genuine DynamicWorkflow whose `resume` is replaced.++ Deliberately not a duck-typed stub: `_execute_resume` guards on+ `isinstance(workflow, DynamicWorkflow)` to catch a dynamic name later+ shadowed by a built-in, and a fake would have to neuter that guard to be+ accepted — testing a path production never takes. This keeps the real+ type, the real input model, and records what resume() was handed.+ """+ from openexecutive.workflows.base import WorkflowEvent+ from openexecutive.workflows.dynamic import DynamicWorkflow+ from openexecutive.workflows.dynamic_models import DynamicWorkflowDef++ defn = DynamicWorkflowDef.model_validate({+ "name": "weekly_watch",+ "title": "Weekly Watch",+ "input_fields": [{"name": "topic", "label": "Topic", "required": False}],+ "steps": [+ {"kind": "specialist", "id": "research", "title": "Research",+ "specialist": "cso", "goal": "Analyze."},+ {"kind": "approval_gate", "id": "gate", "title": "Approve",+ "person_id": 7, "question": "OK?"},+ {"kind": "synthesis", "id": "assemble", "title": "Assemble"},+ ],+ })+ wf = DynamicWorkflow(defn)+ calls: list[dict] = []++ async def _resume(*, inputs, state, resolution, store): # noqa: ANN001, ANN202+ calls.append({"state": state, "resolution": resolution, "inputs": inputs})+ for ev in (events if events is not None else [+ WorkflowEvent(type="artifact", content="# Final artifact")+ ]):+ yield ev++ wf.resume = _resume # type: ignore[method-assign]+ wf.calls = calls # type: ignore[attr-defined]+ return wf+++def _install_stub(monkeypatch: pytest.MonkeyPatch, stub) -> None: # noqa: ANN001+ """Point the executor at this workflow, with a no-op store and audit."""+ import openexecutive.audit as audit+ import openexecutive.knowledge.store as knowledge_store+ import openexecutive.workflows as wf_pkg++ monkeypatch.setattr(wf_pkg, "get_workflow", lambda name: stub)+ monkeypatch.setattr(knowledge_store, "ChromaDBStore", lambda *a, **k: object())+ monkeypatch.setattr(audit, "log_event", lambda *a, **k: None)+++def test_resume_executes_remaining_steps_and_completes(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The headline behaviour: a resolved run's remaining steps run and the+ artifact lands. Before this, the run simply stopped at `resolved`."""+ from openexecutive.workflows.resumer import _process_resumable++ _resolved()+ stub = _real_workflow()+ _install_stub(monkeypatch, stub)++ executed = asyncio.run(_process_resumable(datetime.now(UTC)))++ assert executed == 1+ run = wf_persistence.get_run("res-1")+ assert run["status"] == "done"+ assert run["artifact"] == "# Final artifact"+ # The payload is dropped so a finished run can never be re-claimed.+ assert run["resume_state_json"] is None+ # The engine was handed the recorded cursor and the human's decision.+ assert stub.calls[0]["state"].next_step_index == 2+ assert stub.calls[0]["resolution"].parsed_decision["decision"] == "approve"+++def test_resume_failure_is_recorded_as_a_failed_run(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A declined gate surfaces as an error event; the run must end at `error`+ rather than hanging in `running` with the claim still on it."""+ from openexecutive.workflows.base import WorkflowEvent+ from openexecutive.workflows.resumer import _process_resumable++ _resolved(decision="reject")+ _install_stub(monkeypatch, _real_workflow(+ [WorkflowEvent(type="error", message="Declined at the 'Approve' gate: fine")]+ ))++ asyncio.run(_process_resumable(datetime.now(UTC)))++ run = wf_persistence.get_run("res-1")+ assert run["status"] == "error"+ assert "Declined" in run["error"]+ assert run["resume_state_json"] is None+++def test_pause_only_runs_are_never_claimed(monkeypatch: pytest.MonkeyPatch) -> None:+ """A gate with no payload is finished at `resolved`. Claiming it would+ flip a completed run back to `running` with nothing to execute."""+ from openexecutive.workflows.resumer import _process_resumable++ _resolved(resume_state=None)+ _install_stub(monkeypatch, _real_workflow())++ assert asyncio.run(_process_resumable(datetime.now(UTC))) == 0+ assert wf_persistence.get_run("res-1")["status"] == "resolved"+++def test_a_claimed_run_is_not_executed_twice(monkeypatch: pytest.MonkeyPatch) -> None:+ """The immediate kick and the poll loop both reach the executor; the+ atomic claim is what stops a run being paid for twice."""+ from openexecutive.workflows.resumer import _process_resumable++ _resolved()+ stub = _real_workflow()+ _install_stub(monkeypatch, stub)++ asyncio.run(_process_resumable(datetime.now(UTC)))+ asyncio.run(_process_resumable(datetime.now(UTC)))++ assert len(stub.calls) == 1+++def test_second_gate_recheckpoints_instead_of_completing(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A workflow with two gates pauses again mid-resume. The run must go back+ to `awaiting_human` with the NEW payload and the OLD resolution cleared —+ otherwise the executor would re-claim it on gate 1's answer."""+ from openexecutive.workflows.resumer import _process_resumable+ from openexecutive.workflows.wait_for_human import (+ WaitForHumanEvent,+ WorkflowResumeState,+ )++ _resolved()+ second = WaitForHumanEvent(+ person_id=7, question="Ship it?",+ resume_state=WorkflowResumeState(+ workflow_name="weekly_watch", gate_step_id="gate2",+ gate_step_index=3, next_step_index=4, outputs={},+ ),+ )+ _install_stub(monkeypatch, _real_workflow([second]))++ async def _deliver(event, **_): # noqa: ANN001, ANN202+ return event.model_copy(update={"delivery": "sent"}), "sent"++ monkeypatch.setattr(+ "openexecutive.workflows.gate_delivery.deliver_gate_question", _deliver+ )++ asyncio.run(_process_resumable(datetime.now(UTC)))++ run = wf_persistence.get_run("res-1")+ assert run["status"] == "awaiting_human"+ assert json.loads(run["resume_state_json"])["gate_step_id"] == "gate2"+ assert run["resolution_json"] is None+ assert run["artifact"] is None+++def test_resume_fails_when_the_workflow_was_deleted(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A custom workflow can be deleted while a run sits at its gate."""+ import openexecutive.workflows as wf_pkg+ from openexecutive.workflows.resumer import _process_resumable++ _resolved()++ def _missing(name: str): # noqa: ANN202+ raise KeyError(name)++ monkeypatch.setattr(wf_pkg, "get_workflow", _missing)+ monkeypatch.setattr(+ "openexecutive.workflows.dynamic_store.get_definition", lambda name: None+ )++ asyncio.run(_process_resumable(datetime.now(UTC)))++ run = wf_persistence.get_run("res-1")+ assert run["status"] == "error"+ assert "deleted" in run["error"]+ assert run["resume_state_json"] is None+++def test_resume_says_deactivated_when_the_definition_still_exists(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Deleted and switched-off need different things from the reader."""+ import openexecutive.workflows as wf_pkg+ from openexecutive.workflows.resumer import _process_resumable++ _resolved()++ def _missing(name: str): # noqa: ANN202+ raise KeyError(name)++ monkeypatch.setattr(wf_pkg, "get_workflow", _missing)+ monkeypatch.setattr(+ "openexecutive.workflows.dynamic_store.get_definition",+ lambda name: object(),+ )++ asyncio.run(_process_resumable(datetime.now(UTC)))++ assert "deactivated" in wf_persistence.get_run("res-1")["error"]+++def test_unreadable_payload_fails_the_run_rather_than_the_sweep(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from openexecutive.workflows.resumer import _process_resumable++ _resolved(resume_state="{not json")+ _install_stub(monkeypatch, _real_workflow())++ asyncio.run(_process_resumable(datetime.now(UTC)))++ run = wf_persistence.get_run("res-1")+ assert run["status"] == "error"+ assert "could not be read" in run["error"]+++def test_auto_proceed_timeout_executes_in_the_same_tick(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """`on_timeout='auto_proceed'` was inert: it synthesized a resolution and+ nothing ran. `_tick` calls the executor AFTER the timeout loop, which is+ what finally makes it proceed — with no special-casing anywhere."""+ _seed_awaiting(+ "auto-1", 7, on_timeout="auto_proceed",+ resume_state=_RESUME_STATE, workflow_name="weekly_watch",+ inputs={"topic": "pricing"},+ )+ stub = _real_workflow()+ _install_stub(monkeypatch, stub)++ asyncio.run(_tick(datetime.now(UTC)))++ run = wf_persistence.get_run("auto-1")+ assert run["status"] == "done"+ assert run["artifact"] == "# Final artifact"+ assert stub.calls[0]["resolution"].parsed_decision["decision"] == "auto_proceed"+++def test_escalate_timeout_drops_the_resume_payload() -> None:+ """`timed_out` is terminal — nobody answered, so the payload will never be+ replayed and must not keep the run on the resumable queue."""+ _seed_awaiting("esc-1", 7, on_timeout="escalate", resume_state=_RESUME_STATE)++ asyncio.run(_tick(datetime.now(UTC)))++ run = wf_persistence.get_run("esc-1")+ assert run["status"] == "timed_out"+ assert run["resume_state_json"] is None+++def test_a_stranded_resume_is_requeued_and_retried(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Crash recovery: a worker that died after claiming leaves the run in+ `running`, which no other sweep looks at."""+ from openexecutive.workflows.resumer import _RESUME_STALE_AFTER, _process_resumable++ _resolved()+ wf_persistence.claim_run_for_resume("res-1") # simulate the dead worker+ assert wf_persistence.get_run("res-1")["status"] == "running"++ stub = _real_workflow()+ _install_stub(monkeypatch, stub)+ later = datetime.now(UTC) + _RESUME_STALE_AFTER + timedelta(minutes=1)++ assert asyncio.run(_process_resumable(later)) == 1+ assert wf_persistence.get_run("res-1")["status"] == "done"+++def test_acknowledgement_says_the_run_is_resuming() -> None:+ """#143 shipped wording promising the opposite; a resumable gate must not+ tell the approver to come back and ask for the next step themselves."""+ from openexecutive.workflows.resumer import resolution_acknowledgement++ _resolved()+ ack = resolution_acknowledgement(+ "res-1",+ WaitForHumanResolution(+ run_id="res-1", reply_text="yes", source_channel="slack",+ parsed_decision={"decision": "approve"}, person_id=7,+ ),+ )+ assert "Approved" in ack+ assert "picking up" in ack+ assert "doesn't pick up from here on its own" not in ack+++def test_acknowledgement_says_the_run_stops_on_a_decline() -> None:+ from openexecutive.workflows.resumer import resolution_acknowledgement++ _resolved(decision="reject")+ ack = resolution_acknowledgement(+ "res-1",+ WaitForHumanResolution(+ run_id="res-1", reply_text="no", source_channel="slack",+ parsed_decision={"decision": "reject"}, person_id=7,+ ),+ )+ assert "Declined" in ack+ assert "stops there" in ack+++def test_acknowledgement_keeps_the_old_wording_for_a_pause_only_gate() -> None:+ """Nothing continues a gate with no payload, and saying otherwise would be+ the same lie in the other direction."""+ from openexecutive.workflows.resumer import resolution_acknowledgement++ _resolved(resume_state=None)+ ack = resolution_acknowledgement(+ "res-1",+ WaitForHumanResolution(+ run_id="res-1", reply_text="yes", source_channel="slack",+ parsed_decision={"decision": "approve"}, person_id=7,+ ),+ )+ assert "doesn't pick up from here on its own" in ack+++def test_resume_refuses_a_workflow_that_is_no_longer_dynamic(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """`get_workflow` checks the built-in registry first, so a custom+ workflow's name can be shadowed by a built-in shipped later. Running the+ built-in's steps against this run's payload would be nonsense."""+ import openexecutive.audit as audit+ import openexecutive.knowledge.store as knowledge_store+ import openexecutive.workflows as wf_pkg+ from openexecutive.workflows import WORKFLOW_REGISTRY+ from openexecutive.workflows.resumer import _process_resumable++ _resolved()+ builtin = WORKFLOW_REGISTRY["board_prep"]+ monkeypatch.setattr(wf_pkg, "get_workflow", lambda name: builtin)+ monkeypatch.setattr(knowledge_store, "ChromaDBStore", lambda *a, **k: object())+ monkeypatch.setattr(audit, "log_event", lambda *a, **k: None)++ asyncio.run(_process_resumable(datetime.now(UTC)))++ run = wf_persistence.get_run("res-1")+ assert run["status"] == "error"+ assert "no longer a custom workflow" in run["error"]+++def test_a_crash_mid_resume_fails_the_run_on_both_paths(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The kick and the poll must agree. An earlier version had the poll fail+ the run while the kick only logged, which left a crashed run sitting in+ `running` waiting on a 30-minute sweep — a different outcome for the same+ failure depending on which entry point happened to win the claim."""+ from openexecutive.workflows.resumer import _process_resumable++ _resolved()+ wf = _real_workflow()++ async def _boom(*a, **k): # noqa: ANN002, ANN003, ANN202+ raise RuntimeError("the model fell over")+ yield # pragma: no cover - makes this an async generator++ wf.resume = _boom # type: ignore[method-assign]+ _install_stub(monkeypatch, wf)++ asyncio.run(_process_resumable(datetime.now(UTC)))++ run = wf_persistence.get_run("res-1")+ assert run["status"] == "error"+ # Off the resumable queue, so it is not retried forever.+ assert run["resume_state_json"] is None+++def test_a_gate_as_the_final_step_fails_rather_than_hanging(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """`validate_definition` requires synthesis last, but a definition stored+ before that rule can still reach the engine. Resuming past a trailing gate+ runs no steps and produces no artifact; the run must end at `error` with a+ legible reason instead of silently reporting success."""+ from openexecutive.workflows.resumer import _process_resumable++ _resolved()+ # next_step_index == len(steps): the loop body never executes.+ _install_stub(monkeypatch, _real_workflow(events=[]))++ asyncio.run(_process_resumable(datetime.now(UTC)))++ run = wf_persistence.get_run("res-1")+ assert run["status"] == "error"+ assert "without producing an artifact" in run["error"]diff --git a/packages/core/tests/unit/test_wait_for_human_persistence.py b/packages/core/tests/unit/test_wait_for_human_persistence.pyindex 9087939e..2722659e 100644--- a/packages/core/tests/unit/test_wait_for_human_persistence.py+++ b/packages/core/tests/unit/test_wait_for_human_persistence.py@@ -180,3 +180,184 @@ def test_list_awaiting_runs_filters_correctly(db: Path) -> None:run_ids = [r["run_id"] for r in awaiting]assert "r1" in run_idsassert "r2" not in run_ids+++# ---------------------------------------------------------------------------+# Resume — columns, claim, crash recovery+# ---------------------------------------------------------------------------++def test_initialize_runs_db_creates_resume_columns(db: Path) -> None:+ import sqlite3+ conn = sqlite3.connect(str(db))+ cols = {row[1] for row in conn.execute("PRAGMA table_info(workflow_runs)")}+ conn.close()+ assert "resume_state_json" in cols+ assert "resumed_at" in cols+ assert "resume_attempts" in cols+++def _checkpoint(db: Path, run_id: str, *, resume: str | None) -> None:+ wf_persistence.save_checkpoint(+ run_id,+ '{"person_id": 7, "question": "ok?"}',+ 7,+ datetime.now(UTC) + timedelta(hours=24),+ db_path=db,+ resume_state_json=resume,+ )+++def _row(db: Path, run_id: str) -> dict:+ import sqlite3+ conn = sqlite3.connect(str(db))+ conn.row_factory = sqlite3.Row+ row = conn.execute(+ "SELECT * FROM workflow_runs WHERE run_id = ?", (run_id,)+ ).fetchone()+ conn.close()+ return dict(row)+++def test_save_checkpoint_stores_resume_payload(db: Path) -> None:+ _seed_run(db)+ _checkpoint(db, "run-001", resume='{"workflow_name": "wf"}')+ assert _row(db, "run-001")["resume_state_json"] == '{"workflow_name": "wf"}'+++def test_save_checkpoint_without_payload_leaves_it_null(db: Path) -> None:+ """A pause-only gate must not look resumable."""+ _seed_run(db)+ _checkpoint(db, "run-001", resume=None)+ assert _row(db, "run-001")["resume_state_json"] is None+++def test_second_checkpoint_clears_the_previous_resolution(db: Path) -> None:+ """The second-gate case. A run resumed past gate 1 still carries gate 1's+ resolution and claim stamp; leaving them would let the executor act on the+ old answer at the new gate, and the stale sweep treat a fresh pause as an+ abandoned resume."""+ _seed_run(db)+ _checkpoint(db, "run-001", resume='{"gate": 1}')+ wf_persistence.store_resolution("run-001", '{"decision": "approve"}', db_path=db)+ assert wf_persistence.claim_run_for_resume("run-001", db_path=db)+ assert _row(db, "run-001")["resumed_at"] is not None++ _checkpoint(db, "run-001", resume='{"gate": 2}')+ row = _row(db, "run-001")+ assert row["status"] == "awaiting_human"+ assert row["resume_state_json"] == '{"gate": 2}'+ assert row["resolution_json"] is None+ assert row["resumed_at"] is None+++def test_claim_run_for_resume_succeeds_once(db: Path) -> None:+ """The guard against double execution: the poll loop and the immediate+ kick both call this, and only one may win."""+ _seed_run(db)+ _checkpoint(db, "run-001", resume='{"gate": 1}')+ wf_persistence.store_resolution("run-001", "{}", db_path=db)++ assert wf_persistence.claim_run_for_resume("run-001", db_path=db) is True+ assert wf_persistence.claim_run_for_resume("run-001", db_path=db) is False+ row = _row(db, "run-001")+ assert row["status"] == "running"+ assert row["resume_attempts"] == 1+++def test_claim_ignores_a_resolved_run_with_no_payload(db: Path) -> None:+ """A pause-only gate is finished at `resolved`. Claiming it would flip a+ completed run back to `running` with nothing to execute."""+ _seed_run(db)+ _checkpoint(db, "run-001", resume=None)+ wf_persistence.store_resolution("run-001", "{}", db_path=db)++ assert wf_persistence.claim_run_for_resume("run-001", db_path=db) is False+ assert _row(db, "run-001")["status"] == "resolved"+++def test_list_resumable_runs_selects_only_claimable_rows(db: Path) -> None:+ for rid, resume, resolve in (+ ("ready", '{"gate": 1}', True), # resolved + payload -> yes+ ("pause-only", None, True), # resolved, no payload -> no+ ("still-waiting", '{"gate": 1}', False), # awaiting_human -> no+ ):+ wf_persistence.create_run(rid, "wf", rid, {"a": "b"}, db_path=db)+ _checkpoint(db, rid, resume=resume)+ if resolve:+ wf_persistence.store_resolution(rid, "{}", db_path=db)++ ids = [r["run_id"] for r in wf_persistence.list_resumable_runs(db_path=db)]+ assert ids == ["ready"]+++def test_list_resumable_runs_parses_inputs(db: Path) -> None:+ wf_persistence.create_run("r", "wf", "t", {"topic": "pricing"}, db_path=db)+ _checkpoint(db, "r", resume='{"gate": 1}')+ wf_persistence.store_resolution("r", "{}", db_path=db)+ assert wf_persistence.list_resumable_runs(db_path=db)[0]["inputs"] == {+ "topic": "pricing"+ }+++def test_clear_resume_state_makes_a_run_unclaimable(db: Path) -> None:+ _seed_run(db)+ _checkpoint(db, "run-001", resume='{"gate": 1}')+ wf_persistence.store_resolution("run-001", "{}", db_path=db)+ wf_persistence.clear_resume_state("run-001", db_path=db)++ assert wf_persistence.list_resumable_runs(db_path=db) == []+ assert wf_persistence.claim_run_for_resume("run-001", db_path=db) is False+++def test_stale_resuming_run_is_found_and_requeued(db: Path) -> None:+ """Crash recovery. `sweep_stale_awaiting` only looks at awaiting_human, so+ a worker that dies after claiming would otherwise strand the run in+ `running` with nobody coming back for it."""+ _seed_run(db)+ _checkpoint(db, "run-001", resume='{"gate": 1}')+ wf_persistence.store_resolution("run-001", "{}", db_path=db)+ wf_persistence.claim_run_for_resume("run-001", db_path=db)++ future = datetime.now(UTC) + timedelta(minutes=1)+ assert wf_persistence.list_stale_resuming_runs(future, db_path=db) == ["run-001"]+ assert wf_persistence.requeue_run_for_resume("run-001", db_path=db) is True+ assert _row(db, "run-001")["status"] == "resolved"+ # Requeued rows are claimable again, and the attempt count keeps rising.+ assert wf_persistence.claim_run_for_resume("run-001", db_path=db) is True+ assert _row(db, "run-001")["resume_attempts"] == 2+++def test_a_fresh_claim_is_not_treated_as_stale(db: Path) -> None:+ _seed_run(db)+ _checkpoint(db, "run-001", resume='{"gate": 1}')+ wf_persistence.store_resolution("run-001", "{}", db_path=db)+ wf_persistence.claim_run_for_resume("run-001", db_path=db)++ past = datetime.now(UTC) - timedelta(minutes=30)+ assert wf_persistence.list_stale_resuming_runs(past, db_path=db) == []+++def test_stale_sweep_respects_the_attempt_cap(db: Path) -> None:+ """A run that reliably kills its worker must stop being retried."""+ _seed_run(db)+ _checkpoint(db, "run-001", resume='{"gate": 1}')+ wf_persistence.store_resolution("run-001", "{}", db_path=db)+ future = datetime.now(UTC) + timedelta(minutes=1)++ for _ in range(3):+ wf_persistence.claim_run_for_resume("run-001", db_path=db)+ wf_persistence.requeue_run_for_resume("run-001", db_path=db)+ wf_persistence.claim_run_for_resume("run-001", db_path=db)++ assert _row(db, "run-001")["resume_attempts"] == 4+ assert wf_persistence.list_stale_resuming_runs(+ future, max_attempts=3, db_path=db+ ) == []+++def test_an_ordinary_running_run_is_never_requeued(db: Path) -> None:+ """A normal in-flight run has no payload and must be left alone."""+ _seed_run(db) # create_run leaves status='running', resume_state_json NULL+ future = datetime.now(UTC) + timedelta(hours=1)+ assert wf_persistence.list_stale_resuming_runs(future, db_path=db) == []+ assert wf_persistence.requeue_run_for_resume("run-001", db_path=db) is Falsediff --git a/packages/core/tests/unit/test_workflow_routes.py b/packages/core/tests/unit/test_workflow_routes.pyindex 3e49675d..3b249a3b 100644--- a/packages/core/tests/unit/test_workflow_routes.py+++ b/packages/core/tests/unit/test_workflow_routes.py@@ -6,6 +6,7 @@ integration tests)."""from __future__ import annotations+import jsonimport osimport tempfilefrom pathlib import Path@@ -270,3 +271,173 @@ def test_all_workflows_listed_via_api(client: TestClient) -> None:assert r.status_code == 200api_names = {w["name"] for w in r.json()["workflows"]}assert api_names == set(WORKFLOW_REGISTRY.keys())+++# -----------------------------------------------------------------------------+# Approval gates over SSE+# -----------------------------------------------------------------------------++class _GateRouteWorkflow:+ """A workflow that pauses, with a resume payload like a real dynamic one."""++ name = "gate_route"+ title = "Gate Route Workflow"+ description = "Pauses for a sign-off."+ estimated_minutes = 1++ def __init__(self, *, resumable: bool = True) -> None:+ self._resumable = resumable++ def input_model(self): # noqa: ANN201 - duck-typed stub+ from pydantic import BaseModel as _BM+ from pydantic import create_model+ model: type[_BM] = create_model("_GateIn", topic=(str, ""))+ return model++ def steps(self): # noqa: ANN201+ from openexecutive.workflows.base import WorkflowStepDef+ return [WorkflowStepDef(id="gate", title="Approve", description="Sign off.")]++ async def run(self, inputs, store): # noqa: ANN001, ANN201+ from openexecutive.workflows.wait_for_human import (+ WaitForHumanEvent,+ WorkflowResumeState,+ )+ state = (+ WorkflowResumeState(+ workflow_name="gate_route", gate_step_id="gate",+ gate_step_index=0, next_step_index=1, outputs={},+ )+ if self._resumable+ else None+ )+ yield WaitForHumanEvent(person_id=7, question="Approve?", resume_state=state)+++def _sse_events(body: str) -> list[dict]:+ return [+ json.loads(line[len("data: "):])+ for line in body.split("\n")+ if line.startswith("data: ")+ ]+++def gate_client(temp_db: Path): # noqa: ANN201+ """A client whose registry resolves `gate_route`, with delivery stubbed."""+ async def _deliver(event, **_kw): # noqa: ANN001, ANN202+ return event.model_copy(update={"channel": "slack", "channel_ref": "U1"}), "sent"++ with patch("openexecutive.workflows.persistence.DB_PATH", temp_db), \+ patch("openexecutive.api.routes.workflows.create_run",+ side_effect=lambda **kw: create_run(db_path=temp_db, **kw)), \+ patch("openexecutive.api.routes.workflows.get_run",+ side_effect=lambda run_id: get_run(run_id, db_path=temp_db)), \+ patch("openexecutive.api.routes.workflows.get_workflow",+ lambda name: _GateRouteWorkflow()), \+ patch("openexecutive.workflows.gate_delivery.deliver_gate_question", _deliver):+ app = create_app()+ with TestClient(app) as c:+ yield c+++def test_paused_run_ends_the_stream_with_a_terminal_frame(+ gate_client: TestClient, temp_db: Path+) -> None:+ """A paused run emits no `done` and no `error` — the stream just stops. The+ `terminal` flag is what tells a client that IS the end, instead of leaving+ it waiting for a frame that never comes."""+ r = gate_client.post("/workflows/gate_route/runs", json={"topic": "x"})+ assert r.status_code == 200+ events = _sse_events(r.text)++ assert events[-1]["type"] == "awaiting_human"+ assert events[-1]["terminal"] is True+ assert events[-1]["resumable"] is True+ assert events[-1]["delivery"] == "sent"+ assert not any(e["type"] in {"done", "error"} for e in events)+++def test_paused_run_is_checkpointed_with_its_payload(+ gate_client: TestClient, temp_db: Path+) -> None:+ r = gate_client.post("/workflows/gate_route/runs", json={"topic": "x"})+ run_id = _sse_events(r.text)[-1]["run_id"]++ run = get_run(run_id, db_path=temp_db)+ assert run is not None+ assert run["status"] == "awaiting_human"+ assert json.loads(run["resume_state_json"])["gate_step_id"] == "gate"+++def test_a_stream_error_after_the_checkpoint_does_not_fail_the_run(+ temp_db: Path,+) -> None:+ """`fail_run` has no status guard, so an exception raised after a+ successful checkpoint used to overwrite `awaiting_human` with `error` —+ destroying a resumable run for something as ordinary as a client+ disconnecting mid-frame."""+ async def _deliver(event, **_kw): # noqa: ANN001, ANN202+ return event.model_copy(update={"channel": "slack"}), "sent"++ def _boom(payload): # noqa: ANN001, ANN202+ if payload.get("type") == "awaiting_human":+ raise RuntimeError("client went away")+ return f"data: {json.dumps(payload)}\n\n"++ with patch("openexecutive.workflows.persistence.DB_PATH", temp_db), \+ patch("openexecutive.api.routes.workflows.create_run",+ side_effect=lambda **kw: create_run(db_path=temp_db, **kw)), \+ patch("openexecutive.api.routes.workflows.get_workflow",+ lambda name: _GateRouteWorkflow()), \+ patch("openexecutive.workflows.gate_delivery.deliver_gate_question", _deliver), \+ patch("openexecutive.api.routes.workflows._sse", _boom):+ app = create_app()+ with TestClient(app) as c:+ c.post("/workflows/gate_route/runs", json={"topic": "x"})++ runs = list_runs(db_path=temp_db)+ assert len(runs) == 1+ assert runs[0]["status"] == "awaiting_human", (+ "a broken stream must not destroy the parked run"+ )+++def test_run_detail_strips_the_resume_payload(+ gate_client: TestClient, temp_db: Path+) -> None:+ """The payload holds every completed step's full text, and the run-detail+ page polls this endpoint every few seconds while a run is unfinished."""+ r = gate_client.post("/workflows/gate_route/runs", json={"topic": "x"})+ run_id = _sse_events(r.text)[-1]["run_id"]++ detail = gate_client.get(f"/workflows/runs/{run_id}").json()++ assert "resume_state_json" not in detail+ assert detail["resume_progress"]["gate_step_id"] == "gate"+ assert detail["resume_progress"]["completed_step_ids"] == []+++def test_run_detail_resume_progress_is_null_for_a_pause_only_run(+ temp_db: Path,+) -> None:++ async def _deliver(event, **_kw): # noqa: ANN001, ANN202+ return event.model_copy(), "sent"++ with patch("openexecutive.workflows.persistence.DB_PATH", temp_db), \+ patch("openexecutive.api.routes.workflows.create_run",+ side_effect=lambda **kw: create_run(db_path=temp_db, **kw)), \+ patch("openexecutive.api.routes.workflows.get_run",+ side_effect=lambda run_id: get_run(run_id, db_path=temp_db)), \+ patch("openexecutive.api.routes.workflows.get_workflow",+ lambda name: _GateRouteWorkflow(resumable=False)), \+ patch("openexecutive.workflows.gate_delivery.deliver_gate_question", _deliver):+ app = create_app()+ with TestClient(app) as c:+ r = c.post("/workflows/gate_route/runs", json={"topic": "x"})+ events = _sse_events(r.text)+ assert events[-1]["resumable"] is False+ detail = c.get(f"/workflows/runs/{events[-1]['run_id']}").json()++ assert detail["resume_progress"] is Nonediff --git a/packages/core/tests/unit/test_workflow_run_tools.py b/packages/core/tests/unit/test_workflow_run_tools.pyindex 5f389497..166109b7 100644--- a/packages/core/tests/unit/test_workflow_run_tools.py+++ b/packages/core/tests/unit/test_workflow_run_tools.py@@ -398,3 +398,110 @@ def test_every_delivery_status_has_a_presentation_hint() -> None:clear=True,), pytest.raises(RuntimeError, match="alerted"):_assert_hints_cover_every_delivery_status()+++class _ResumableGateWorkflow:+ """A gate that carries a resume payload, i.e. a real dynamic workflow."""++ name = "resumable_gate"+ title = "Resumable Gate Workflow"++ def input_model(self) -> type[BaseModel]:+ return _StubInputs++ async def run(self, inputs: BaseModel, store: Any) -> AsyncIterator[Any]:+ from openexecutive.workflows.wait_for_human import WorkflowResumeState++ yield WaitForHumanEvent(+ person_id=3,+ question="Approve the plan?",+ timeout_hours=24,+ resume_state=WorkflowResumeState(+ workflow_name="resumable_gate",+ gate_step_id="gate",+ gate_step_index=1,+ next_step_index=2,+ outputs={"research": ("Research", "body")},+ ),+ )+++def _stub_sent_delivery(monkeypatch: pytest.MonkeyPatch) -> None:+ async def _deliver(event: Any, **_kw: Any) -> tuple[Any, str]:+ return event.model_copy(update={"channel": "slack", "channel_ref": "U1"}), "sent"++ monkeypatch.setattr(+ "openexecutive.workflows.gate_delivery.deliver_gate_question", _deliver+ )+++def test_pause_only_gate_is_reported_as_not_resuming(+ monkeypatch: pytest.MonkeyPatch, run_db: Path+) -> None:+ """`_GateWorkflow` yields a bare WaitForHumanEvent — no resume payload —+ which is what every caller got before resume existed. The run must be+ checkpointed as un-resumable and described that way, so the Executive does+ not promise the principal work that will never happen."""+ from openexecutive import workflows as wf_pkg+ from openexecutive.workflows import persistence++ monkeypatch.setattr(wf_pkg, "get_workflow", lambda name: _GateWorkflow())+ _stub_sent_delivery(monkeypatch)++ out = _call(handle_run_workflow, {"workflow": "gate", "inputs": {"topic": "x"}})++ assert out["resumable"] is False+ assert "does not continue past the gate" in out["presentation_hint"]+ run = persistence.get_run(out["run_id"], db_path=run_db)+ assert run is not None+ assert run["resume_state_json"] is None+++def test_resumable_gate_is_reported_as_continuing_on_its_own(+ monkeypatch: pytest.MonkeyPatch, run_db: Path+) -> None:+ from openexecutive import workflows as wf_pkg+ from openexecutive.workflows import persistence++ monkeypatch.setattr(wf_pkg, "get_workflow", lambda name: _ResumableGateWorkflow())+ _stub_sent_delivery(monkeypatch)++ out = _call(+ handle_run_workflow, {"workflow": "resumable_gate", "inputs": {"topic": "x"}}+ )++ assert out["status"] == "awaiting_human"+ assert out["resumable"] is True+ assert "picks up where it left off" in out["presentation_hint"]++ run = persistence.get_run(out["run_id"], db_path=run_db)+ assert run is not None+ assert json.loads(run["resume_state_json"])["gate_step_id"] == "gate"+ # The payload must not leak into the checkpoint the resolver reads.+ assert "resume_state" not in json.loads(run["state_json"])+++def test_an_undelivered_resumable_gate_says_both_things(+ monkeypatch: pytest.MonkeyPatch, run_db: Path+) -> None:+ """Delivery and resumability are independent, and the hint has to be+ honest about each: nobody was asked, AND the run will continue once they+ are."""+ from openexecutive import workflows as wf_pkg++ monkeypatch.setattr(wf_pkg, "get_workflow", lambda name: _ResumableGateWorkflow())++ async def _failed(event: Any, **_kw: Any) -> tuple[Any, str]:+ return event.model_copy(), "failed"++ monkeypatch.setattr(+ "openexecutive.workflows.gate_delivery.deliver_gate_question", _failed+ )++ out = _call(+ handle_run_workflow, {"workflow": "resumable_gate", "inputs": {"topic": "x"}}+ )++ hint = out["presentation_hint"]+ assert "could not be delivered" in hint+ assert "picks up where it left off" in hintdiff --git a/packages/ui/src/app/jobs/page.tsx b/packages/ui/src/app/jobs/page.tsxindex e306c617..ff32788b 100644--- a/packages/ui/src/app/jobs/page.tsx+++ b/packages/ui/src/app/jobs/page.tsx@@ -19,6 +19,12 @@ import {listWorkflowRuns,listWorkflows,} from "@/lib/api";+import {+ RunBucket,+ runStatusBadgeColor,+ runStatusBucket,+ runStatusLabel,+} from "@/lib/runStatus";const SECTION_ORDER: WorkflowSection[] = ["Board",@@ -45,13 +51,15 @@ const SECTION_BLURB: Record<WorkflowSection, string> = {};type Tab = "catalog" | "runs";-type RunStatus = "active" | "done" | "error";+type RunStatus = RunBucket;function isTab(v: string | null): v is Tab {return v === "catalog" || v === "runs";}function isStatus(v: string | null): v is RunStatus {- return v === "active" || v === "done" || v === "error";+ return (+ v === "active" || v === "awaiting" || v === "done" || v === "error"+ );}function formatRelativeTime(iso: string): string {@@ -65,17 +73,11 @@ function formatRelativeTime(iso: string): string {}function statusBadge(status: string) {- const color =- status === "done"- ? "bg-emerald-500/10 text-emerald-400 ring-emerald-500/30"- : status === "error"- ? "bg-red-500/10 text-red-400 ring-red-500/30"- : "bg-amber-500/10 text-amber-400 ring-amber-500/30";return (<span- className={`inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-medium ring-1 ${color}`}+ className={`inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-medium ring-1 ${runStatusBadgeColor(status)}`}>- {status}+ {runStatusLabel(status)}</span>);}@@ -100,13 +102,6 @@ function groupBy<T, K extends string>(return out;}-function runStatusBucket(s: WorkflowRunSummary["status"]): RunStatus {- if (s === "running") return "active";- if (s === "done" || s === "error") return s;- // Defensive: unknown future statuses surface under Active so they're not lost.- return "active";-}-function JobsPageInner() {const router = useRouter();const pathname = usePathname();@@ -157,7 +152,7 @@ function JobsPageInner() {);const runCounts = useMemo(() => {- const c = { active: 0, done: 0, error: 0 };+ const c = { active: 0, awaiting: 0, done: 0, error: 0 };for (const r of runs) c[runStatusBucket(r.status)]++;return c;}, [runs]);@@ -172,9 +167,12 @@ function JobsPageInner() {if (status !== null) return;if (defaultedStatusRef.current) return;defaultedStatusRef.current = true;- const next: RunStatus = runCounts.active > 0 ? "active" : "done";+ // Awaiting first: a run blocked on the viewer outranks one that is simply+ // still working.+ const next: RunStatus =+ runCounts.awaiting > 0 ? "awaiting" : runCounts.active > 0 ? "active" : "done";setParam({ status: next });- }, [tab, loading, status, runCounts.active, setParam]);+ }, [tab, loading, status, runCounts.active, runCounts.awaiting, setParam]);const workflowTitleMap = useMemo(() => new Map(workflows.map((w) => [w.name, w.title] as const)),@@ -475,6 +473,8 @@ function RunsView({const emptyMsg =status === "active"? "No active runs."+ : status === "awaiting"+ ? "Nothing waiting on a sign-off.": status === "done"? "No completed runs yet.": "No errors.";@@ -489,6 +489,13 @@ function RunsView({count={counts.active}tone="amber"/>+ <StatusSegment+ active={status === "awaiting"}+ onClick={() => onStatusChange("awaiting")}+ label="Awaiting sign-off"+ count={counts.awaiting}+ tone="amber"+ /><StatusSegmentactive={status === "done"}onClick={() => onStatusChange("done")}diff --git a/packages/ui/src/app/jobs/runs/[id]/page.tsx b/packages/ui/src/app/jobs/runs/[id]/page.tsxindex 6ab810b8..6ddabb17 100644--- a/packages/ui/src/app/jobs/runs/[id]/page.tsx+++ b/packages/ui/src/app/jobs/runs/[id]/page.tsx@@ -5,7 +5,33 @@ import { useParams } from "next/navigation";import Link from "next/link";import ReactMarkdown from "react-markdown";import remarkGfm from "remark-gfm";-import { WorkflowRunDetail, getWorkflowRun } from "@/lib/api";+import {+ GateState,+ TERMINAL_RUN_STATUSES,+ WorkflowRunDetail,+ getWorkflowRun,+} from "@/lib/api";+import { runStatusLabel, runStatusTextColor } from "@/lib/runStatus";++// A paused run is resumed by a background worker, so this page has to notice+// a change it did not cause. Poll quickly at first — an approval that just+// landed finishes in seconds — then back off, because a run can legitimately+// sit awaiting a person for days and polling that every 3s for 48h is waste.+const POLL_FAST_MS = 3000;+const POLL_SLOW_MS = 10000;+const POLL_BACKOFF_AFTER_MS = 2 * 60 * 1000;++function parseGateState(raw: string | null | undefined): GateState | null {+ if (!raw) return null;+ try {+ const parsed = JSON.parse(raw);+ return typeof parsed === "object" && parsed !== null+ ? (parsed as GateState)+ : null;+ } catch {+ return null;+ }+}function formatTimestamp(iso: string): string {return new Date(iso).toLocaleString();@@ -20,9 +46,46 @@ export default function RunDetailPage() {useEffect(() => {if (!runId) return;- getWorkflowRun(runId)- .then(setRun)- .catch((e) => setError(e instanceof Error ? e.message : String(e)));+ let cancelled = false;+ let timer: ReturnType<typeof setTimeout> | undefined;+ // Scoped to THIS run, not to the component: the App Router can keep the+ // same instance across a navigation between two run ids, and a mount-time+ // ref would hand the next run the previous one's elapsed clock — starting+ // a seconds-old run straight onto the slow cadence.+ const startedAt = Date.now();++ function schedule() {+ const elapsed = Date.now() - startedAt;+ timer = setTimeout(+ poll,+ elapsed > POLL_BACKOFF_AFTER_MS ? POLL_SLOW_MS : POLL_FAST_MS+ );+ }++ async function poll() {+ try {+ const next = await getWorkflowRun(runId!);+ if (cancelled) return;+ setRun(next);+ setError(null); // a previous blip is over+ if (TERMINAL_RUN_STATUSES.has(next.status)) return; // nothing more to see+ schedule();+ } catch (e) {+ if (cancelled) return;+ // Keep any run already on screen — a transient fetch failure should not+ // replace a rendered artifact with an error page — and KEEP POLLING.+ // Returning here instead would stop the page updating for good after a+ // single blip, on a run that is still moving.+ setError(e instanceof Error ? e.message : String(e));+ schedule();+ }+ }++ poll();+ return () => {+ cancelled = true;+ if (timer) clearTimeout(timer);+ };}, [runId]);const handleCopy = useCallback(async () => {@@ -49,7 +112,11 @@ export default function RunDetailPage() {URL.revokeObjectURL(url);}, [run]);- if (error) {+ // Only take over the whole page when there is nothing to show. Once a run has+ // loaded, a failed poll is a transient blip: keep the artifact on screen and+ // report the problem inline (below), or the page would flip to an error view+ // and lose everything the reader was looking at.+ if (error && !run) {return (<div className="flex flex-col h-full bg-surface text-fg items-center justify-center"><div className="text-sm text-red-400 mb-4">Error: {error}</div>@@ -102,9 +169,36 @@ export default function RunDetailPage() {)}</div>+ {error && (+ <div className="rounded-md border border-red-500/30 bg-red-500/5 px-4 py-3 text-xs text-red-300">+ Couldn't refresh just now ({error}). Still retrying.+ </div>+ )}+{run.status === "running" && (<div className="rounded-md border border-amber-500/30 bg-amber-500/5 px-4 py-3 text-sm text-amber-300">- This run is still in progress. Refresh in a moment.+ This run is still in progress — this page updates itself.+ </div>+ )}++ {run.status === "awaiting_human" && (+ <AwaitingPanel run={run} />+ )}++ {run.status === "resolved" && (+ <div className="rounded-md border border-indigo-500/30 bg-indigo-500/5 px-4 py-3 text-sm text-indigo-300">+ Answered — picking the workflow back up now. The remaining steps+ are running.+ </div>+ )}++ {run.status === "timed_out" && (+ <div className="rounded-md border border-red-500/30 bg-red-500/5 px-4 py-3 text-sm text-red-300">+ <div className="font-medium mb-1">No reply before the deadline</div>+ <div className="text-xs">+ The step's timeout policy was applied, so this run stopped+ without finishing.+ </div></div>)}@@ -156,11 +250,63 @@ export default function RunDetailPage() {}function StatusPill({ status }: { status: string }) {- const color =- status === "done"- ? "text-emerald-400"- : status === "error"- ? "text-red-400"- : "text-amber-400";- return <span className={`${color} font-medium`}>{status}</span>;+ return (+ <span className={`${runStatusTextColor(status)} font-medium`}>+ {runStatusLabel(status)}+ </span>+ );+}++// What the question's delivery state means for the reader. The distinction+// matters: a suppressed or failed send means nobody has actually been asked,+// and saying "waiting on them" would be untrue.+const DELIVERY_NOTES: Record<string, string> = {+ sent: "The question was sent to them.",+ self: "The question was put to them directly in the conversation.",+ suppressed:+ "The message was held back (duplicate, rate cap, or quiet hours), so they have not been asked yet.",+ alerted:+ "They could not be reached on any messaging channel — the request is on their briefing board instead.",+ failed: "The question could not be delivered, so nobody has been asked yet.",+};++function AwaitingPanel({ run }: { run: WorkflowRunDetail }) {+ const gate = parseGateState(run.state_json);+ const delivery = gate?.delivery;+ const undelivered = delivery !== undefined && delivery !== "sent" && delivery !== "self";+ const deadline = run.awaiting_until+ ? new Date(run.awaiting_until).toLocaleString()+ : null;+ const done = run.resume_progress?.completed_step_ids.length ?? 0;++ return (+ <div className="rounded-md border border-amber-500/30 bg-amber-500/5 px-4 py-3 text-sm text-amber-300 space-y-2">+ <div className="font-medium">+ Waiting for sign-off+ {run.awaiting_person_id ? ` from person ${run.awaiting_person_id}` : ""}+ </div>+ {gate?.question && (+ <div className="text-fg text-sm">“{gate.question}”</div>+ )}+ <div className="text-xs space-y-1">+ {deadline && <div>Deadline {deadline}.</div>}+ {delivery && (+ <div className={undelivered ? "text-red-300" : undefined}>+ {DELIVERY_NOTES[delivery] ?? `Delivery: ${delivery}.`}+ </div>+ )}+ {run.resume_progress ? (+ <div>+ {done} step{done === 1 ? "" : "s"} already finished — they run on+ automatically once this is answered.+ </div>+ ) : (+ <div>+ This run stops at the sign-off; the decision is recorded but no+ further steps will run.+ </div>+ )}+ </div>+ </div>+ );}diff --git a/packages/ui/src/components/WorkflowRunner.tsx b/packages/ui/src/components/WorkflowRunner.tsxindex 4dd8d51b..8c8c8d19 100644--- a/packages/ui/src/components/WorkflowRunner.tsx+++ b/packages/ui/src/components/WorkflowRunner.tsx@@ -2,6 +2,7 @@import { useState } from "react";import { useRouter } from "next/navigation";+import Link from "next/link";import {WorkflowEvent,WorkflowMeta,@@ -9,7 +10,7 @@ import {runWorkflow,} from "@/lib/api";-type StepState = "pending" | "running" | "done" | "skipped";+type StepState = "pending" | "running" | "done" | "skipped" | "paused";interface StepStatus {def: WorkflowStepDef;@@ -36,12 +37,14 @@ export default function WorkflowRunner({const [error, setError] = useState<string | null>(null);const [streaming, setStreaming] = useState(false);const [started, setStarted] = useState(false);+ const [paused, setPaused] = useState<WorkflowEvent | null>(null);async function handleStart() {setStarted(true);setStreaming(true);setError(null);setRunId(null);+ setPaused(null);setSteps(workflow.steps.map((s) => ({ def: s, state: "pending" })));try {@@ -84,6 +87,15 @@ export default function WorkflowRunner({);return;}+ if (evt.type === "awaiting_human") {+ // The stream ends here — no `done` or `error` follows. Without this the+ // gate step sat spinning on "running" and the panel just went quiet.+ setPaused(evt);+ setSteps((prev) =>+ prev.map((s) => (s.state === "running" ? { ...s, state: "paused" } : s))+ );+ return;+ }if (evt.type === "done" && evt.run_id) {// Redirect to the run page to view the artifactrouter.push(`/jobs/runs/${encodeURIComponent(evt.run_id)}`);@@ -129,7 +141,10 @@ export default function WorkflowRunner({Running</span>)}- {!streaming && !error && runId && (+ {!streaming && !error && paused && (+ <span className="text-xs text-amber-400">Paused</span>+ )}+ {!streaming && !error && !paused && runId && (<span className="text-xs text-emerald-400">Complete</span>)}{error && <span className="text-xs text-red-400">Failed</span>}@@ -159,6 +174,11 @@ export default function WorkflowRunner({</li>))}</ol>+ {paused && (+ <div className="mt-4">+ <PausedNotice event={paused} runId={runId} />+ </div>+ )}{error && (<div className="mt-4 text-sm text-red-400 bg-red-500/5 border border-red-500/20 rounded-md p-3"><div className="font-medium mb-1">Workflow failed</div>@@ -171,7 +191,57 @@ export default function WorkflowRunner({);}+function PausedNotice({+ event,+ runId,+}: {+ event: WorkflowEvent;+ runId: string | null;+}) {+ // Only `sent` and `self` mean the approver actually has the question. Saying+ // "waiting on them" for the others would describe a request nobody received.+ const delivery = event.delivery;+ const reached = delivery === "sent" || delivery === "self";+ return (+ <div className="rounded-md border border-amber-500/30 bg-amber-500/5 px-4 py-3 text-sm text-amber-300 space-y-2">+ <div className="font-medium">Paused for sign-off</div>+ {event.question && (+ <div className="text-fg">“{event.question}”</div>+ )}+ <div className="text-xs space-y-1">+ <div>+ {reached+ ? `Sent to person ${event.person_id} — waiting on their reply.`+ : `Person ${event.person_id} has NOT been asked yet (${delivery ?? "unknown"}).`}+ </div>+ {event.resumable ? (+ <div>The run continues by itself once they answer.</div>+ ) : (+ <div>+ Their answer is recorded, but this run stops at the gate.+ </div>+ )}+ </div>+ {runId && (+ <Link+ href={`/jobs/runs/${encodeURIComponent(runId)}`}+ className="inline-block text-xs text-indigo-400 hover:underline"+ >+ Follow this run →+ </Link>+ )}+ </div>+ );+}+function StepIndicator({ state, index }: { state: StepState; index: number }) {+ if (state === "paused") {+ return (+ <div className="flex-shrink-0 w-6 h-6 rounded-full bg-amber-500/20 text-amber-400 flex items-center justify-center text-[10px] font-bold">+ ⏸+ </div>+ );+ }if (state === "done") {return (<div className="flex-shrink-0 w-6 h-6 rounded-full bg-emerald-500/20 text-emerald-400 flex items-center justify-center text-[10px] font-bold">diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.tsindex 69307a04..f4d5ae4d 100644--- a/packages/ui/src/lib/api.ts+++ b/packages/ui/src/lib/api.ts@@ -1055,23 +1055,82 @@ export interface WorkflowSample {inputs: Record<string, unknown>;}+/** Every status `workflow_runs.status` can hold. `awaiting_human`, `resolved`+ * and `timed_out` have been served for a while; the union only ever listed+ * three, so the others reached the UI as unhandled strings. */+export type WorkflowRunStatus =+ | "running"+ | "done"+ | "error"+ | "awaiting_human"+ | "resolved"+ | "timed_out";++/** Statuses the run will not move on from by itself. Anything else means a+ * poll is worth repeating: `running` is working, `awaiting_human` is waiting+ * on a person, and `resolved` is queued for the resumer to pick up. */+export const TERMINAL_RUN_STATUSES: ReadonlySet<WorkflowRunStatus> = new Set([+ "done",+ "error",+ "timed_out",+]);++/** How the gate's question actually reached the approver. Anything other than+ * `sent` or `self` means nobody was asked, and the UI must not imply+ * otherwise. */+export type GateDelivery = "self" | "sent" | "suppressed" | "alerted" | "failed";+export interface WorkflowRunSummary {run_id: string;workflow_name: string;title: string;- status: "running" | "done" | "error";+ status: WorkflowRunStatus;created_at: string;updated_at: string;}+/** Which steps a paused run already finished. The server sends this in place+ * of the raw resume payload, which carries every completed step's full text+ * and would otherwise ride on every poll. */+export interface ResumeProgress {+ gate_step_id: string;+ completed_step_ids: string[];+}+export interface WorkflowRunDetail extends WorkflowRunSummary {inputs: Record<string, unknown>;artifact: string | null;error: string | null;+ // Checkpoint columns the run record has always carried; the detail route+ // returns the whole row, so these were already on the wire untyped.+ awaiting_person_id?: number | null;+ awaiting_until?: string | null;+ state_json?: string | null;+ resolution_json?: string | null;+ resume_progress?: ResumeProgress | null;+}++/** The serialized gate in `state_json`, for rendering what a paused run is+ * waiting on. Every field is optional: older checkpoints predate some of+ * them, which is exactly how the server tells legacy rows apart. */+export interface GateState {+ question?: string;+ person_id?: number;+ expected_reply_shape?: string;+ delivery?: GateDelivery;+ channel?: string;}export interface WorkflowEvent {- type: "run_created" | "step_start" | "step_done" | "artifact" | "done" | "error";+ type:+ | "run_created"+ | "step_start"+ | "step_done"+ | "result"+ | "artifact"+ | "done"+ | "error"+ | "awaiting_human";run_id?: string;title?: string;workflow?: string;@@ -1082,6 +1141,17 @@ export interface WorkflowEvent {sources?: string[];message?: string;steps?: WorkflowStepDef[];+ /** `result` events only. */+ data?: Record<string, unknown>;+ // `awaiting_human` only. A paused run emits NO `done` or `error` — this+ // frame is the last one, which `terminal` says explicitly so a client+ // doesn't sit waiting for an end that never comes.+ person_id?: number;+ question?: string;+ awaiting_until?: string;+ delivery?: GateDelivery;+ resumable?: boolean;+ terminal?: boolean;}export async function listWorkflows(): Promise<WorkflowMeta[]> {diff --git a/packages/ui/src/lib/runStatus.ts b/packages/ui/src/lib/runStatus.tsnew file mode 100644index 00000000..40c3e5db--- /dev/null+++ b/packages/ui/src/lib/runStatus.ts@@ -0,0 +1,62 @@+/** Shared presentation of a workflow run's status.+ *+ * Both the jobs list and the run-detail page render the same six statuses, and+ * an earlier version of this feature defined the label map and the colour+ * branching separately in each — byte-for-byte identical, and free to drift+ * the moment a seventh status arrives. One source, imported by both.+ */+import { WorkflowRunStatus } from "@/lib/api";++/** Raw status strings are for the database. "awaiting_human" and "timed_out"+ * mean nothing to someone scanning a list of jobs. */+export const RUN_STATUS_LABELS: Record<string, string> = {+ running: "running",+ done: "done",+ error: "failed",+ awaiting_human: "awaiting sign-off",+ resolved: "resuming",+ timed_out: "no reply",+};++export function runStatusLabel(status: string): string {+ return RUN_STATUS_LABELS[status] ?? status;+}++/** Tailwind text colour per status. `timed_out` reads as a failure from the+ * viewer's side — nobody answered and the run produced nothing — so it shares+ * the error colour rather than looking like it is still going. */+export function runStatusTextColor(status: string): string {+ if (status === "done") return "text-emerald-400";+ if (status === "error" || status === "timed_out") return "text-red-400";+ if (status === "resolved") return "text-indigo-400";+ return "text-amber-400";+}++/** The badge variant used in list views: same semantics, with a ring + tint. */+export function runStatusBadgeColor(status: string): string {+ if (status === "done")+ return "bg-emerald-500/10 text-emerald-400 ring-emerald-500/30";+ if (status === "error" || status === "timed_out")+ return "bg-red-500/10 text-red-400 ring-red-500/30";+ if (status === "resolved")+ return "bg-indigo-500/10 text-indigo-400 ring-indigo-500/30";+ return "bg-amber-500/10 text-amber-400 ring-amber-500/30";+}++/** Coarse bucket for the runs sub-tabs.+ *+ * `resolved` groups with active, not done: the answer is in and the resumer is+ * about to run the steps after the gate. `awaiting_human` is its own bucket —+ * it is the one state that needs a person to DO something, and folding it into+ * "active" hid it among jobs that are merely still running.+ */+export type RunBucket = "active" | "awaiting" | "done" | "error";++export function runStatusBucket(s: WorkflowRunStatus): RunBucket {+ if (s === "running" || s === "resolved") return "active";+ if (s === "awaiting_human") return "awaiting";+ if (s === "error" || s === "timed_out") return "error";+ if (s === "done") return "done";+ // Defensive: unknown future statuses surface under Active so they're not lost.+ return "active";+}