omnius 1.0.591 → 1.0.592

package/docs/work-orders/daemon-hud-ui-overhaul.md

@@ -0,0 +1,82 @@
+# Daemon HUD UI Overhaul Work Order
+
+## Objective
+
+Overhaul the daemon web interface using `/home/roko/Desktop/hud-ui-style-kit(6)/hud-ui-style-kit` as the source of truth. Preserve current daemon behavior while replacing the OpenWebUI-like rounded dashboard styling with the cold tactical HUD visual system.
+
+## Ground Truth
+
+- Style kit files:
+  - `README.md`
+  - `styles.css`
+  - `tokens.json`
+  - `index.html`
+  - `assets/reference-hud-map.png`
+- Required component contract:
+  - `hud-panel`, `hud-panel--cut`, `hud-panel--slant`
+  - required child: `hud-panel__chrome`
+  - `hud-btn` with `hud-btn__chrome` and `hud-btn__label`
+  - `hud-tab` with `hud-tab__chrome` and `hud-tab__label`
+- Visual grammar:
+  - cold blue-gray/black base
+  - dense grid overlays
+  - frosted panels with thin steel borders
+  - clipped/slanted panel geometry
+  - amber active/warning states
+  - pale cyan focus/glow
+  - condensed uppercase display headings
+  - monospace operational logs
+
+## Anchors
+
+- Main daemon UI template: `packages/cli/src/api/web-ui.ts`
+- Existing Generate page: `packages/cli/src/api/web-ui.ts` around `#generate-panel`
+- Server-side SPA route allowlist: `packages/cli/src/api/serve.ts` around `guiRoutes`
+- Existing Generate JS: `genSelectKind`, `generateMedia`, `loadGenerateTab`
+- Existing AV REST analysis endpoint: `POST /v1/media/av/analyze`
+- Existing media endpoint tests: `packages/cli/tests/routes-media.test.ts`
+- Existing inline script parse test: `packages/cli/tests/web-ui-script.test.ts`
+
+## Work Items
+
+- [x] Update file header and UI foundation away from OpenWebUI naming toward HUD.
+- [x] Add HUD design tokens and component classes from the style kit.
+- [x] Apply global shell/sidebar/topbar/page-panel HUD styling while preserving IDs.
+- [x] Replace Generate page markup with a HUD workbench.
+- [x] Add Generate left nested menu with Image, Video, Audio, Music, Audio Analysis, Video Analysis, and Live AV Analysis.
+- [x] Wire Generate media controls to existing `/v1/media/<kind>` behavior.
+- [x] Add AV analysis controls backed by `POST /v1/media/av/analyze`.
+- [x] Render analysis results with source metadata, adapter status, answer, entities, events, relations, and shots.
+- [x] Add tests for HUD classes, Generate analysis panels, and AV endpoint discoverability.
+- [x] Run targeted tests and typecheck.
+
+## Evidence Log
+
+- The daemon UI is a single self-contained HTML/CSS/JS template in `web-ui.ts`.
+- The current Generate page already supports generation for image/video/audio/music and gallery browsing.
+- `POST /v1/media/av/analyze` already performs multimodal analysis over local media paths/URIs with roles: `video_temporal`, `grounding`, `tracking`, `audio_event`, `audio_lalm`, `asr`, and `cross_modal`.
+- Direct `/v1/tools/{name}/call` is intentionally restricted to bookkeeping tools right now, so the UI should use the AV REST route first rather than trying to call agent tools directly.
+- Added HUD token bridge and component classes directly inside `web-ui.ts` to preserve the no-build static daemon UI.
+- Replaced the Generate tab with a three-column HUD workbench: left operation rail, center synthesis/analysis panels, and right evidence output.
+- Added route support for `/generate`.
+- Added server-side `/generate` HTML route support so the Generate page can be opened directly.
+- Added `genSelectMode`, `analyzeAvMedia`, and `renderAvAnalysis`.
+- Updated the Generate button label handling so nested HUD chrome is not destroyed by `textContent` writes.
+- Added regression coverage in `web-ui-script.test.ts` and `routes-media.test.ts`.
+- Verification passed:
+  - `pnpm --filter omnius test -- web-ui-script.test.ts routes-media.test.ts`
+  - `pnpm --filter omnius test -- web-ui-script.test.ts web-ui-routes.test.ts routes-media.test.ts`
+  - `pnpm --filter omnius typecheck`
+  - `pnpm --filter omnius build`
+- Live daemon check on `http://127.0.0.1:11635/generate` returned `200 text/html` and contained the HUD Generate/analysis controls.
+- Live browser-cookie AV validation check reached `/v1/media/av/analyze` and returned expected `400 Missing media path`.
+
+## Acceptance Criteria
+
+- The page uses the HUD tokens, clipped panel chrome, nested button/tab chrome, and tactical grid styling from the style kit.
+- Existing tabs still switch correctly.
+- Existing Generate media generation still works.
+- Audio Analysis and Video Analysis are visible under the Generate tab's left nested menu.
+- Analysis submissions call `/v1/media/av/analyze`.
+- Inline script still parses under the current Vitest guard.
+- Media route tests still pass.

package/docs/work-orders/hermes-architecture-deltas/01-public-scrutiny-provenance-control/INDEX.md

@@ -0,0 +1,21 @@
+# Public Scrutiny Provenance Control Index
+
+Progress: not started.
+
+Files in this folder:
+- [WORKORDER.md](WORKORDER.md) - Full phased implementation workorder.
+
+Primary Omnius anchors:
+- `packages/cli/src/tui/telegram-bridge.ts:2778` - public fast runner options.
+- `packages/cli/src/tui/telegram-bridge.ts:2795` - admin evidence runner options.
+- `packages/cli/src/tui/telegram-bridge.ts:13079` - Telegram message entrypoint.
+- `packages/cli/src/tui/telegram-bridge.ts:13436` - public/admin sub-agent run dispatch.
+- `packages/cli/src/tui/command-registry.ts:208` - Telegram command registry entries.
+- `packages/cli/tests/telegram-bot-api-10.test.ts:868` - current public fast option assertions.
+
+Primary Hermes anchors:
+- `/home/robit/Documents/repositories/hermes-agent/gateway/session_context.py:51` - task-local session metadata.
+- `/home/robit/Documents/repositories/hermes-agent/docs/kanban/multi-gateway.md:3` - profile-scoped gateway behavior.
+
+Completion target:
+- Public Telegram has a clean, reversible, non-scenario-specific path to elevate provenance scrutiny when humans request it or the agent explicitly declares low confidence.

package/docs/work-orders/hermes-architecture-deltas/01-public-scrutiny-provenance-control/WORKORDER.md

@@ -0,0 +1,225 @@
+# Workorder: Public Scrutiny Provenance Control
+
+## Objective
+
+Add a public Telegram scrutiny control plane that can elevate completion provenance checks when public accuracy risk rises, without hard-coded scenario phrases or shortcut wording that teaches the model to satisfy the gate without evidence.
+
+The feature must support:
+- Human command control: `/scrutiny on`, `/scrutiny strict`, `/scrutiny off`, `/scrutiny status`.
+- Agent discretion: a bounded internal request to elevate scrutiny when the current public run cannot confidently distinguish answerable facts from unsupported claims.
+- Time limits: elevated state expires by TTL unless renewed.
+- Safety: public runs remain bounded; admin DM evidence behavior remains stronger and cannot be weakened by public controls.
+
+## Problem Statement
+
+Current public Telegram behavior is split by static runner options:
+- `TELEGRAM_PUBLIC_FAST_OPTIONS` disables `completionProvenanceGuard` and `backwardPassReview`.
+- `TELEGRAM_ADMIN_EVIDENCE_OPTIONS` enables both.
+
+This fixed split is correct for ordinary public chat latency, but it lacks a runtime path for public contexts where the agent or group needs additional scrutiny. The implementation must not inspect fixed phrases such as names, topics, or controversy labels. The decision must be based on current conversation context, explicit human command, or an explicit agent confidence/scrutiny request.
+
+## Existing Code Anchors
+
+Omnius:
+- `packages/cli/src/tui/telegram-bridge.ts:2778` defines `TELEGRAM_PUBLIC_FAST_OPTIONS`.
+- `packages/cli/src/tui/telegram-bridge.ts:2795` defines `TELEGRAM_ADMIN_EVIDENCE_OPTIONS`.
+- `packages/cli/src/tui/telegram-bridge.ts:13079` starts Telegram message handling.
+- `packages/cli/src/tui/telegram-bridge.ts:13118` computes Telegram slash command routing.
+- `packages/cli/src/tui/telegram-bridge.ts:13436` dispatches `runSubAgent`.
+- `packages/cli/src/tui/telegram-bridge.ts:13450` derives final public/admin text.
+- `packages/cli/src/tui/telegram-bridge.ts:13917` builds quick-chat system context.
+- `packages/cli/src/tui/command-registry.ts:208` begins `/telegram` command metadata.
+- `packages/cli/src/tui/command-registry.ts:700` defines public Telegram bot commands.
+- `packages/cli/tests/telegram-bot-api-10.test.ts:868` asserts public options are fast and guard-off.
+
+Hermes comparison anchors:
+- `/home/robit/Documents/repositories/hermes-agent/gateway/session_context.py:51` stores session context in task-local variables.
+- `/home/robit/Documents/repositories/hermes-agent/docs/kanban/multi-gateway.md:3` documents profile-scoped gateway ownership.
+
+## Target Architecture
+
+Introduce a runtime `TelegramPublicScrutinyState` keyed by the current Telegram session key.
+
+Suggested state:
+
+```ts
+type TelegramPublicScrutinyMode = "fast" | "elevated" | "strict";
+
+interface TelegramPublicScrutinyState {
+  mode: TelegramPublicScrutinyMode;
+  reason: string;
+  setBy: "human_admin" | "human_user" | "agent";
+  updatedAtMs: number;
+  expiresAtMs?: number;
+  lastRunId?: string;
+}
+```
+
+Mode behavior:
+- `fast`: current public behavior. Bounded, no completion provenance guard, no backward-pass review.
+- `elevated`: bounded public behavior with completion provenance guard enabled.
+- `strict`: bounded public behavior with completion provenance guard and backward-pass review enabled, but with tighter max cycles than admin DM.
+
+Controls:
+- Human commands change state directly after authorization checks.
+- Agent discretion records an elevation request with reason and TTL; it cannot silently turn scrutiny off.
+- Expiration is checked before each run and when reporting status.
+
+Important boundary:
+- Do not implement scenario keyword filters.
+- Do not infer scrutiny from specific people, events, topics, or external domains.
+- If the agent uses discretion, it must output a generic reason derived from uncertainty, missing source support, conflicting context, or public-impact sensitivity in the current run.
+
+## Phased Implementation
+
+### Phase 0: Baseline and Guardrails
+
+Tasks:
+- Add tests that prove current public fast behavior remains fast by default.
+- Add tests that admin DM still forces evidence options and cannot be weakened by scrutiny commands.
+- Add a source test preventing direct use of `TELEGRAM_PUBLIC_FAST_OPTIONS` at the runner call site once the resolver exists.
+
+Completion metrics:
+- Existing simple Telegram public test still reaches completion.
+- Admin incomplete verification tests remain unchanged.
+- No new command is exposed before authorization and state handling exist.
+
+### Phase 1: State Model and Persistence
+
+Tasks:
+- Add `TelegramPublicScrutinyState` types near Telegram state definitions in `telegram-bridge.ts`.
+- Add an in-memory map keyed by `sessionKeyForMessage(msg)`.
+- Persist state under `.omnius/telegram-public-scrutiny.json` or the existing Omnius settings store if a clean per-chat settings helper exists.
+- Add helpers:
+  - `getTelegramPublicScrutinyState(msg)`
+  - `setTelegramPublicScrutinyState(msg, state)`
+  - `clearTelegramPublicScrutinyState(msg)`
+  - `pruneExpiredTelegramPublicScrutinyState(nowMs)`
+
+File-by-file notes:
+- `packages/cli/src/tui/telegram-bridge.ts`: own the runtime state because session keys, chat types, admin checks, and reply routing already live here.
+- `packages/cli/src/tui/omnius-directory.ts`: use only if settings persistence is already centralized and does not create unrelated churn.
+
+Completion metrics:
+- State round-trips across bridge instance reload in a unit test.
+- Expired state is ignored and pruned.
+- Private admin DM is unaffected by public state.
+
+### Phase 2: Runner Option Resolver
+
+Tasks:
+- Add `resolveTelegramRunnerEvidenceOptions(msg, toolContext)` or equivalent.
+- Replace static selection at the sub-agent runner call with this resolver.
+- Preserve bounded options for public modes.
+- Keep admin DM equivalent to `TELEGRAM_ADMIN_EVIDENCE_OPTIONS`.
+
+Expected behavior:
+- Public fast: `completionProvenanceGuard=false`, `backwardPassReview=false`.
+- Public elevated: `completionProvenanceGuard=true`, `backwardPassReview=false`.
+- Public strict: `completionProvenanceGuard=true`, `backwardPassReview=true`, bounded max turns/cycles.
+- Admin DM: unchanged evidence-heavy defaults.
+
+Completion metrics:
+- Source test sees resolver usage instead of `isAdminDM ? TELEGRAM_ADMIN_EVIDENCE_OPTIONS : TELEGRAM_PUBLIC_FAST_OPTIONS`.
+- Tests prove each mode maps to expected runner options.
+- Strict public mode does not enable unbounded turn extension.
+
+### Phase 3: Human Command Surface
+
+Tasks:
+- Add command metadata to `command-registry.ts`:
+  - `/scrutiny on [ttl]`
+  - `/scrutiny strict [ttl]`
+  - `/scrutiny off`
+  - `/scrutiny status`
+  - `/telegram scrutiny ...` aliases if preferred for admin discoverability.
+- Add command handling before sub-agent spawn in `handleMessageWithSubAgent`.
+- Public group command authorization should be explicit:
+  - Admins can set group state.
+  - Non-admin public users can request status if that matches existing command policy, but should not be able to weaken an active state unless product policy explicitly allows it.
+
+File-by-file notes:
+- `packages/cli/src/tui/command-registry.ts`: add metadata and public bot command exposure if desired.
+- `packages/cli/src/tui/telegram-bridge.ts`: parse and apply commands.
+- `packages/cli/tests/telegram-command-menu.test.ts` or `telegram-bot-api-10.test.ts`: assert command visibility and behavior.
+
+Completion metrics:
+- `/scrutiny on` enables elevated mode for that chat/session.
+- `/scrutiny strict` enables strict mode with TTL.
+- `/scrutiny off` clears mode only when authorized.
+- `/scrutiny status` reports mode, reason, setter, and expiry.
+
+### Phase 4: Agent Discretion Hook
+
+Tasks:
+- Add an internal tool or control event that lets a public Telegram sub-agent request scrutiny elevation for the current session.
+- The tool should accept only generic fields:
+  - `mode`: `elevated` or `strict`
+  - `reason`: short natural-language reason
+  - `ttl_minutes`: bounded integer
+  - `confidence`: optional number
+- The tool must not send a Telegram message by itself.
+- The tool must not turn scrutiny off.
+- The prompt should describe when to use it in generic terms: unresolved evidence, conflicting observations, low confidence in factual answer, or public answer needs stronger source discipline.
+
+Completion metrics:
+- Agent can request elevation during a public run.
+- The next run in the same public session uses elevated options.
+- The request is logged in TUI/sub-agent view for operator observability.
+- No topic-specific words or phrase lists are used by the resolver.
+
+### Phase 5: UX and Observability
+
+Tasks:
+- Add TUI sub-agent view lines when scrutiny mode changes.
+- Include current scrutiny mode in context explorer or run metadata for public runs.
+- Ensure final public answer is not polluted with internal status text.
+- Add compact status in `/telegram status` if there is an active elevated public chat state.
+
+Completion metrics:
+- Operators can see why scrutiny was elevated.
+- Public users do not see internal implementation details unless a command response intentionally reports status.
+- Expiry and state transitions are auditable.
+
+### Phase 6: Regression Tests
+
+Required tests:
+- Public default stays fast and simple Q&A reaches `task_complete`.
+- Public elevated uses completion provenance guard.
+- Public strict uses completion provenance guard and backward-pass review but remains bounded.
+- Admin DM ignores public mode and uses admin evidence options.
+- Agent discretion can elevate but cannot lower.
+- Expired TTL reverts to fast.
+- Source test blocks direct static option selection at runner call site.
+
+## Required Tests
+
+- Public default stays fast and simple Q&A reaches `task_complete`.
+- Public elevated uses completion provenance guard.
+- Public strict uses completion provenance guard and backward-pass review but remains bounded.
+- Admin DM ignores public mode and uses admin evidence options.
+- Agent discretion can elevate but cannot lower scrutiny.
+- Expired TTL reverts to fast.
+- Source test blocks direct static option selection at runner call site.
+- Normal public final replies do not include internal scrutiny/provenance status text.
+
+## Rollout Plan
+
+1. Ship disabled-by-default public scrutiny state with `/scrutiny status`.
+2. Enable human `/scrutiny on|strict|off` commands.
+3. Add agent discretion after resolver tests are stable.
+4. Add optional persistence after in-memory behavior is verified.
+
+## Risks
+
+- Overblocking simple public replies. Mitigation: public fast remains default and strict remains bounded.
+- Hidden gate-satisfying shortcuts. Mitigation: resolver consumes state, not scenario words.
+- Public status leaks. Mitigation: only explicit command replies mention state; normal replies remain user-facing.
+
+## Definition of Done
+
+- Public scrutiny can be voluntarily toggled by authorized humans.
+- The agent can request scrutiny elevation with a generic reason and TTL.
+- Public default remains fast and reliable for simple tasks.
+- No hard-coded scenario keyword path controls provenance behavior.
+- Tests cover all state transitions and option mappings.

package/docs/work-orders/hermes-architecture-deltas/02-context-engine-plugin-boundary/INDEX.md

@@ -0,0 +1,20 @@
+# Context Engine Plugin Boundary Index
+
+Progress: not started.
+
+Files in this folder:
+- [WORKORDER.md](WORKORDER.md) - Full phased implementation workorder.
+
+Primary Omnius anchors:
+- `packages/orchestrator/src/agenticRunner.ts:3200` - mission completion contract injection.
+- `packages/orchestrator/src/agenticRunner.ts:18146` - context window trimming logic.
+- `packages/orchestrator/src/agenticRunner.ts:18579` - Telegram runner system prompt assembly.
+- `packages/memory/src/context-window.ts` - existing memory/context utilities.
+- `packages/retrieval/src/contextAssembler.ts` - existing retrieval context assembly.
+
+Primary Hermes anchors:
+- `/home/robit/Documents/repositories/hermes-agent/agent/context_engine.py:32` - abstract `ContextEngine`.
+- `/home/robit/Documents/repositories/hermes-agent/agent/context_compressor.py:522` - default compressor implements the engine.
+
+Completion target:
+- Context assembly and compression can evolve independently from `AgenticRunner` without leaking prompt-specific hacks into unrelated surfaces.

package/docs/work-orders/hermes-architecture-deltas/02-context-engine-plugin-boundary/WORKORDER.md

@@ -0,0 +1,198 @@
+# Workorder: Context Engine Plugin Boundary
+
+## Objective
+
+Extract context assembly, compaction, memory stitching, and completion framing behind a small orchestrator-owned interface. The current runner should remain behaviorally compatible, but future context strategies should be swappable without editing the main `AgenticRunner` loop.
+
+## Problem Statement
+
+`AgenticRunner` carries too many responsibilities:
+- prompt assembly,
+- Telegram-specific prompt differences,
+- memory and retrieval context,
+- completion contract framing,
+- context compaction,
+- tool-result triage,
+- post-critique context injection.
+
+Hermes separates the context subsystem through an explicit `ContextEngine` interface. Omnius already has good pieces in memory and retrieval packages, but the orchestration boundary is still tangled into the runner.
+
+## Existing Code Anchors
+
+Omnius:
+- `packages/orchestrator/src/agenticRunner.ts:3200` builds mission completion contract text.
+- `packages/orchestrator/src/agenticRunner.ts:18146` starts context-window trimming.
+- `packages/orchestrator/src/agenticRunner.ts:18579` branches Telegram-specific system prompt text.
+- `packages/orchestrator/src/completionContract.ts:294` formats completion contracts.
+- `packages/memory/src/context-window.ts` contains context-window helpers.
+- `packages/retrieval/src/contextAssembler.ts` assembles retrieval context.
+- `packages/orchestrator/tests/context-fabric.test.ts` is a likely regression home.
+
+Hermes:
+- `/home/robit/Documents/repositories/hermes-agent/agent/context_engine.py:32` defines `ContextEngine`.
+- `/home/robit/Documents/repositories/hermes-agent/agent/context_compressor.py:522` implements `ContextCompressor`.
+- `/home/robit/Documents/repositories/hermes-agent/agent/context_compressor.py:754` prunes old tool results.
+- `/home/robit/Documents/repositories/hermes-agent/agent/context_compressor.py:1572` cleans orphaned tool call/result pairs after compression.
+
+## Target Architecture
+
+Create `packages/orchestrator/src/contextEngine.ts` with a narrow interface:
+
+```ts
+export interface ContextEngineInput {
+  goal: string;
+  surface: "tui" | "telegram-public" | "telegram-admin" | "api" | "background";
+  messages: AgentMessage[];
+  toolEvents: ToolEvidenceEvent[];
+  memoryHints: string[];
+  runState: ContextRunState;
+}
+
+export interface ContextEngineOutput {
+  systemMessages: AgentMessage[];
+  conversationMessages: AgentMessage[];
+  compacted: boolean;
+  diagnostics: ContextEngineDiagnostics;
+}
+
+export interface ContextEngine {
+  build(input: ContextEngineInput): Promise<ContextEngineOutput>;
+  compact(input: ContextEngineInput): Promise<ContextEngineOutput>;
+}
+```
+
+Default implementation:
+- `DefaultContextEngine` wraps existing runner behavior without changing semantics.
+- It exposes diagnostics for prompt token size, dropped tool results, retained evidence, and compaction reason.
+
+Future extension point:
+- Optional registration through config, but no plugin loader is required for the first cut.
+
+## Phased Implementation
+
+### Phase 0: Inventory and Golden Tests
+
+Tasks:
+- Add tests that snapshot key prompt fragments for:
+  - normal TUI coding task,
+  - public Telegram reply,
+  - admin Telegram task,
+  - API `/v1/run` task,
+  - completion retry after critic feedback.
+- Record current event/evidence fragments that must remain visible.
+
+Completion metrics:
+- Snapshot tests capture behavior before extraction.
+- No new context logic exists yet.
+
+### Phase 1: Define Context Types
+
+Tasks:
+- Add `contextEngine.ts` with input/output types and `DefaultContextEngine`.
+- Define common message/event types, or import existing runner types if they are already exported safely.
+- Add diagnostics:
+  - `tokenEstimateBefore`
+  - `tokenEstimateAfter`
+  - `compactionStrategy`
+  - `evidenceRetained`
+  - `evidenceDropped`
+  - `surface`
+
+File-by-file notes:
+- `packages/orchestrator/src/contextEngine.ts`: new boundary.
+- `packages/orchestrator/src/index.ts`: export only if other packages need it.
+- `packages/orchestrator/tests/contextEngine.test.ts`: unit tests for default no-op build.
+
+Completion metrics:
+- Types compile.
+- Default engine can round-trip messages unchanged.
+
+### Phase 2: Wrap Current Runner Assembly
+
+Tasks:
+- Move context construction code from `AgenticRunner` into default engine methods in small, reversible chunks.
+- Do not change prompts while moving logic.
+- Keep Telegram-specific content as input-selected surface policies, not scattered string checks.
+
+Migration order:
+1. Non-Telegram system prompt assembly.
+2. Telegram prompt assembly.
+3. Completion contract insertion.
+4. Context trimming/compaction.
+5. Tool-result pruning.
+
+Completion metrics:
+- Existing prompt snapshots remain stable.
+- `AgenticRunner` delegates to `contextEngine.build` before backend calls.
+- No behavior change for simple `task_complete` tests.
+
+### Phase 3: Evidence-Aware Compaction
+
+Tasks:
+- Preserve recent tool evidence and critic reconciliation packets as first-class context items.
+- Replace ad hoc retention rules with ranked evidence groups:
+  - user goal and constraints,
+  - final/proposed claims,
+  - latest tool observations,
+  - failed tool results,
+  - modified artifacts,
+  - critique feedback and reconciliation evidence.
+
+Completion metrics:
+- A repeated critic review sees evidence recorded after the prior critique.
+- Tool call/result pairs remain paired after compaction.
+- Orphaned tool results are removed or summarized with a diagnostic.
+
+### Phase 4: Plugin Boundary
+
+Tasks:
+- Allow an optional configured engine name, defaulting to `default`.
+- Keep plugin API internal until one alternate engine exists.
+- Add a test fake engine that injects a diagnostic marker to prove selection works.
+
+Completion metrics:
+- Config can select default engine explicitly.
+- Unknown engine fails closed with a clear error.
+- Test fake engine runs without editing `AgenticRunner`.
+
+### Phase 5: Documentation and Handoff
+
+Tasks:
+- Add an architecture note under `docs/architecture/` describing the context engine boundary.
+- Document invariants:
+  - context engine may reorder/summarize but not fabricate observations,
+  - completion evidence must remain attributable,
+  - surface-specific safety text is selected by surface, not by topic keywords.
+
+Completion metrics:
+- Docs include diagrams or tables for inputs and outputs.
+- Future feature workorders can target `ContextEngine` rather than `AgenticRunner`.
+
+## Required Tests
+
+- `contextEngine.test.ts`: interface, diagnostics, no-op default round trip.
+- `agenticRunner.test.ts`: runner still completes simple tasks.
+- `telegram-bot-api-10.test.ts`: public/admin prompt behavior remains stable.
+- `completionContract.test.ts`: completion contract still appears where expected.
+- Compaction test: evidence after prior critique survives into the next critic prompt.
+
+## Rollout Plan
+
+1. Add boundary with no behavioral change.
+2. Move non-Telegram assembly.
+3. Move Telegram assembly.
+4. Move compaction.
+5. Enable diagnostics in TUI/admin surfaces.
+
+## Risks
+
+- Prompt drift can break fragile Telegram and tool-call behavior. Mitigation: golden prompt tests before migration.
+- Over-generalized interface can freeze wrong abstractions. Mitigation: start with current runner data and only extract actual needs.
+- Plugin loading can introduce untrusted code. Mitigation: internal registry only for first release.
+
+## Definition of Done
+
+- `AgenticRunner` no longer owns all prompt/context assembly directly.
+- Existing behavior is preserved by tests.
+- Context diagnostics expose what was retained and compacted.
+- Completion evidence and critic reconciliation packets are protected through compaction.

package/docs/work-orders/hermes-architecture-deltas/03-typed-gateway-event-stream/INDEX.md

@@ -0,0 +1,19 @@
+# Typed Gateway Event Stream Index
+
+Progress: not started.
+
+Files in this folder:
+- [WORKORDER.md](WORKORDER.md) - Full phased implementation workorder.
+
+Primary Omnius anchors:
+- `packages/orchestrator/src/agenticRunner.ts:15760` - run completion event emission.
+- `packages/cli/src/tui/telegram-bridge.ts:2828` - Telegram completion/task_complete filtering.
+- `packages/cli/src/tui/telegram-bridge.ts:12504` - public progress rendering.
+- `packages/cli/src/tui/telegram-bridge.ts:12650` - admin completion classification.
+
+Primary Hermes anchors:
+- `/home/robit/Documents/repositories/hermes-agent/gateway/stream_events.py:151` - stream event union.
+- `/home/robit/Documents/repositories/hermes-agent/gateway/stream_dispatch.py:88` - adapter dispatch.
+
+Completion target:
+- Runner events carry typed facts; Telegram/TUI adapters decide rendering without string-based status interpretation.