Feature Inventory

Exhaustive by design — never trim it

This is the engine’s capability index. It is a contract for consuming repos: brain authors and anyone integrating with the engine read this to learn what already exists, and they read it without access to this source tree. Nothing here is “derivable from the code” for them — they have no code to derive it from.

Exhaustiveness is the feature. Length is justified by coverage, not by how many decisions a section carries, and this file is read on demand, never loaded into every session — its size costs nothing until someone needs it. Never trim it for context-budget or doc-rot reasons: a missing entry is a lost capability, and the default outcome is that someone rebuilds what the engine already ships.

It lives in docs/brain-dev/ because that folder is the corpus omnislash upgrade copies verbatim into every brain’s docs/engine/. Words written here arrive in consumer repos at the engine version they run, so they may not point outside this folder: the sibling-only link gate in packages/cli/src/docker/engine-docs-builder.test.ts fails CI on any link that would 404 once flattened into a brain.

The exhaustive list of shipped engine features. Three levels: area (##) → feature → sub-feature. What a brain is and why it is shaped this way: PHILOSOPHY.md. What the engine guarantees a brain and what it demands back: contract.md.

A line here answers one question: does the engine already do this? Its job is findability — name the mechanism, name the symbols and defaults worth grepping, and let the reader leave for the code. So: one sentence, ~30 words, 45 at the outside (a bare list of names is measured in items, not prose). Present tense. No rationale for why it was built that way, no account of what it used to do wrong, and nothing carried across from the doc-comment beside the code — that reasoning is already where a reader who wants it will look. A line that needs more than this is a sub-feature that has not been split yet.

Contents

Framework — Engine-as-a-Framework

Agents — Agents Runtime · Models & Model Routing · Agent Isolation & Execution Context · Chat & Conversational Surface

Governance — Tools & MCP · HITL (Human-in-the-Loop) · Policy & Security

Orchestration — Cascade Planner · HTN Planner · Workflow System · Durable Pipelines (Restate) · Artifacts & Deliverables · Evaluation & Self-Evolving

Automation — Scheduler & Heartbeats · Hooks

Knowledge — Memory System · Skills System

Surfaces — Control Plane (Dashboard) · Events System · Media Processing · Integrations

Platform — CLI · Distribution & Deployment · Data & Persistence · Infrastructure

Operations — Observability & Operations · CI/CD

Engine-as-a-Framework

• Brain ↔ Engine Separation — engine is runtime + infrastructure, brain is domain + behavior; one engine serves many standalone brain projects
  • Ownership split — engine owns agent execution, workflow engine, queues, bot framework, system table definitions, CLI, Docker and monitoring; brain owns prompts (constitution/), capabilities/grants, planner methods, custom tools, its own tables and the PostgreSQL instance
  • No domain code in the engine — engine carries no brain-specific prompts or capabilities, and a brain can be open-sourced without exposing engine source (engine ships as npm packages + a GHCR base image)
  • No engine internals in the brain — brains import only from @omnislash-ai/* public packages; extension happens through declared points, never monkey-patching or subclassing
  • Criteria checklist — the full EaaF criteria (separation, config-as-code, runtime composition, schema composition, extension points, operational guarantees, distribution, CLI, zero-config dev infra, production build, DX) with per-item status live in docs/eaaf-criteria.md
• omnislash.config.ts + defineProject() — one typed TypeScript file is the entire engine↔brain contract, validated before the runtime starts
  • Runtime composition, zero codegen — loadProjectConfig() reads the file once at boot (walk-up in file mode, image-baked in Docker); apps are factory functions (createBot, createWorker, …) returning { start, stop, status }; there is no generated directory and no engine-specific compile step
  • Config vs env boundary — ProjectConfig is public, committed configuration; secrets/private/infrastructure values live in .env and are read via env.* directly in packages. The config file must never import env
  • Brain-declared env schema — defineProject({ env: z.object(...) }) merges the brain’s Zod shape into the engine’s at load time, so validation, getEnvCatalog() and checkProdEnvRequirements() all see the combined shape; .meta({ category }) groups brain vars in the dashboard catalog
  • Function-carried fields — tools, ingest.sources, bots[].policy, kpis[].read carry brain code by reference (file mode only; the function itself is never validated — kpis is the one whose declaration around it is) and may read env inside their bodies even though the config module may not
  • Fixed dirs are convention, not config — features/, constitution/, skills/, memory/, constitution/models.json derive from the brain root; defineProject takes no paths key (passing one throws with a pointer to features/<feature>/)
• Display formatting for people — formatInstant (Oct 12, 20:17 GMT+2, the brain’s locale.timezone), formatDecimal (2.33, 0.004, 12,400) and formatUsd ($7.50, $0.0042 below a cent) from @omnislash-ai/config/public: the one spelling the engine uses in every chat notice, card and reason, so a brain’s own reason text reads the same
  • Per-service toggles — services: { bot, worker, scheduler, mcp, webhooks, monitoring, pipelines, dashboard, caddy, nocodb, n8n, playwright, browser, brain-sync }, all default true; a disabled service drops its compose template, its depends_on references, its Prometheus scrape job and its domain-mode Caddy vhost
  • Fail-fast validation — projectConfigSchema.safeParse() rejects a bad config before the runtime boots, with a stable OmnislashError code + actionable hint instead of a stack trace
  • Loading is parse-only; the runtime invariants are the app’s — loadProjectConfig() parses the file and installs the env shapes it derives, and never reads through the validated env proxy, so it succeeds on a brain whose environment is half-filled or absent. The cross-layer config+env rules (isolation ⇒ BRAIN_GIT_REMOTE, Telegram surface ⇒ an addressable HITL chat) live in validateRuntime(config), which the shared app-boot ritual bootstrapEngineApp runs immediately after the load. That split is what lets omnislash doctor DIAGNOSE a broken environment instead of dying of it, and lets regen / upgrade regenerate artifacts in a CI job that carries no brain secrets at all
• G / R / W Path Classification — every path under /app/brain is exactly one of git-backed-and-writable (G), image-baked-read-only (R), or host-bound runtime output (W)
  • G-set composition — engine baseline (memory/, constitution/, skills/, features/) ∪ brainSync.additional; resolveGPaths(config) is the single source consumed by sparse-checkout anchors, the daemon commit set, the compose subpath mounts and .dockerignore
  • Runtime-only directories — brainSync.runtimeOnly names the G-directories whose whole tree the stack reads on demand (never imported or parsed at boot): a push touching only those needs no deploy. Engine tier is every .md plus memory/; resolveRuntimeOnlyDirs(config) is the one list the generated deploy.yml paths-ignore and brain-sync’s deploy-drift clock (BRAIN_SYNC_RUNTIME_ONLY_DIRS) are rendered from (ci.yml has no push trigger, so no filter). defineProject() rejects a directory that is not a G-path (image-baked, so only a deploy carries it) or that the engine loads at boot (features/, constitution/, skills/). The Workflow filters doctor check catches an owned (.override) deploy.yml whose hand-edited filter drifted from the list; Owned workflows warns when such a file is frozen on an older engine template than the one installed
  • Additive only — a brain can extend the G-set but never shrink the engine baseline (a v0.131 narrowing knob silently lost dashboard writes to skills/ and was removed)
  • Forbidden G-paths — ENGINE_FORBIDDEN_G_PATHS rejects structural entries (package.json, lockfiles, .npmrc, db/, omnislash.config.ts, env.schema.ts, tools/, node_modules/, .git/, .env) and blast-radius entries (.github/, docker/, Dockerfile*, .dockerignore)
  • Directories only — the sparse-checkout anchor is /{path}/, which git never matches against a blob, so a file or symlink-to-dir entry would never materialize; assertGPathValid throws at defineProject() and the Brain G-paths doctor check fails
  • Materialization guarantee — brain-sync mkdir -ps every declared G-path after checkout, because docker refuses to start any container whose bind source is missing — one unmaterialized path would take every app service down at once
  • Criterion for adding a path — G is the agent’s unreviewed push surface; a live-mode agent’s write outside the G-set succeeds and then vanishes on container recreate
  • Image-baked deps asymmetry — new files inside G are hot; new external deps are cold — a new npm import in a *.pipeline.ts or a new install[] spec in a SKILL.md needs omnislash build
• Brain Runtime Persistence (brain-sync daemon) — a dedicated long-running service is the single owner of brain git state, keeping the G-set synchronized between the brain repo and the brain_state volume
  • Bootstrap — git sparse-checkout set --no-cone with anchored G-path patterns, shallow fetch, checkout -B <branch> origin/<branch>; a poisoned or corrupt .git is rebuilt in place — whatever the worktree holds beyond origin is pushed to a brain-sync/recovered-<time> branch to merge, and the worktree is reset to origin; on an existing volume the checkout’s origin is reconciled against BRAIN_GIT_REMOTE first, so a transport switch reaches the persistent tree on the redeploy that made it (a different repository is reported, never re-pointed)
  • History window — after bootstrap keepRecentHistory deepens the shallow brain_state checkout to the last HISTORY_WINDOW_DAYS (30) via deepenHistorySince (fetch --shallow-since), never shortening it, best-effort
  • Steady-state loop — every BRAIN_SYNC_INTERVAL_MS (default 5 min): repair the sparse worktree → fetch → commit the G-paths → rebase origin/<branch> → push (no pre-pull; one pull --rebase + retry only on a non-fast-forward rejection) → fetchBaseline() for the per-run sandbox alternates source; fetch-before-commit keeps the network round-trip out of the gap between the snapshot and git’s clean-worktree check, commit-before-rebase is deliberate
  • Self-heal and escalation — each tick starts with a sparse-checkout reapply (a no-op on a healthy tree) because a worktree that loses its skip-worktree bits fails every later tick with cannot pull with rebase and cannot recover on its own; and a streak of ticks failing with the same non-conflict error sends one 🆘 to the status chat, with a ✅ stand-down when syncing resumes
  • Boot gate — every brain-consuming service declares depends_on: { brain-sync: service_healthy }, so nothing starts before the G-set is materialized; the gate covers that and nothing else (the agent-sandbox baseline and attached-repo clones follow it, and an agent dispatched before the baseline lands waits for it — up to BRAIN_BASELINE_WAIT_TIMEOUT_MS, then a retryable failure — rather than running unsandboxed). The healthcheck stays green while the last tick is within 3× the interval
  • Manual sync — a brain-sync:command / brain-sync:completed pub/sub pair driven by the brain.sync op — its brain_sync agent tool and the dashboard “Sync now” button (outcome, durationMs, conflicts; skipped when no daemon runs); an in-flight tick is waited out first, conflict holds apply
  • Tick deadline — each tick runs under BRAIN_SYNC_TICK_TIMEOUT_MS (default 2 min) composed with the shutdown signal, so a credential mint or a git op against a stuck remote is aborted and retried on the next interval instead of holding the loop’s single-tick slot forever. Bootstrap’s cold clone is deliberately outside that budget — the healthcheck start_period bounds it
  • Recovery posture — tracked dirty state is committed (never stashed), non-conflict pull failures warn and retry next tick, untracked files are swept into the next commit, and SIGTERM drains the in-flight tick through an AbortSignal so the volume is never left mid-rebase
  • Observability — brain_sync_last_tick_seconds, brain_sync_interval_seconds, brain_sync_conflicts_total{direction} plus app_check_healthy{check="brain-sync-bootstrap"|"brain-sync-staleness"}, surfaced through health.overview’s brainSync (the dashboard’s sync badge, an agent’s health_overview)
  • Git identity — GIT_AUTHOR_NAME/GIT_AUTHOR_EMAIL are optional once an App is registered (until then they are required — brain-sync fails fast at boot with no identity from either tier): unset, they are derived from the registered App row (<slug>[bot] / <app_id>+<slug>[bot]@users.noreply.github.com) by applyGitIdentityDefault, so a commit is attributed to the bot rather than to whatever ambient identity the container carried. Set, the env pair wins. Either way the value is mirrored into GIT_COMMITTER_* so every git invocation, including bwrap’d agents, has a complete identity
• AI Conflict Resolution (supervised episode) — a rebase conflict exports the daemon’s unpushed commits to origin and spawns a system:git-conflict-resolver agent in a clone of its own; the episode is closed only by a git-verified, clean tick
  • Export first — the rebase is aborted (local commits preserved) and the local tip is force-pushed to the engine-reserved branch brain-sync/conflict; from that moment the commits are durable on origin, and a human can resolve by hand
  • Open once — one ⚠️ names the branch on the status chat, and a single-instance resolver is dispatched (Agents.recreate({ ifBusy: 'throw' }), runIn: 'clone', interactive: false, ResolverReportSchema structured output) with the exact range to replay: base..brain-sync/conflict onto origin/<branch>
  • Hold — while the resolver is busy the sync loop performs no git operations, so it never re-exports a moving tip under the agent; a stalled attempt past RESOLVER_DEADLINE_MS (15 min) is stopped and respawned against the same export
  • Verify, adopt, close — the resolver’s reported pushedTip must be a push made after the export (a strict descendant of the origin/<branch> the resolver was handed) that sits on the freshly fetched origin/<branch>, or the attempt fails and re-dispatches with the tree untouched; on success the daemon replays only what its writers produced during the hold onto the resolved branch, pushes, deletes the side branch and sends the ✅ report (duration, attempts, the agent’s own summary); repeated failure escalates 🆘 at attempt 3 and every 10 thereafter
  • Restart-safe — episodes are in-memory but the side branch is the record: a restarted daemon re-reads the export from origin on its first tick and resumes supervision — holding for a still-running resolver, verifying and adopting one that finished during the downtime — without a duplicate ⚠️; a side branch already integrated by the previous process is retired
  • Private workspace — only brain-sync mounts the sync clone’s .git; the resolver and every other agent see G-paths through subpath mounts and reach the daemon’s history only through origin
• Content Hot-Reloading (ContentWatcher) — a generic node:fs.watch wrapper with per-directory debounce reloads brain content without restarting any process
  • Zero domain knowledge — dir → callbacks, 300 ms debounce per directory, observer-style unsubscribe, error isolation per listener, missing dirs warned and skipped
  • Per-app wiring — worker reloads capabilities / tool policy / planner methods / loop prompts (+ skills) and republishes the tools a widget page’s call runs on, mcp additionally republishes the tool catalog and fires MCP notifyListChanged, chat-core reloads capabilities + tool policy + skills, pipelines adds a filtered *.pipeline.ts listener that rebuilds and re-registers Restate services, webhooks reloads capabilities + tool policy for the tool door it hosts, dashboard reloads capabilities + skills (it holds no tool registry, and its tool lists come from the Redis catalog mirror), scheduler pokes its reconcilers
  • Runs in production too — the caches it resets are boot-time caches with no self-revalidation, and the G-set is hot-synced by brain-sync; entity loaders are deliberately absent because they self-correct on a content fingerprint
  • Reads held until a change — every process trusts its watch: an entity loader’s probe and the features listing answer from what the process last read until the watch reports a change under features/, constitution/ or the engine’s templates, at which moment (ahead of the debounce) the next read walks again; a read outside the watched directories, or under a watcher that failed, walks every turn as before
  • Keep-last-known-good — reloads are eager with fallback: a broken engine-tools.json keeps the previous valid policy and logs STALE rather than stripping the agent of every tool; hard fail-fast stays at boot only
• Brain Runtime Contract (singleton shape) — the five things a brain owes the engine, enforced at install, at build and at boot
  • Single-pin peer shape — @omnislash-ai/* are declared exactly once, in peerDependencies, at an exact X.Y.Z; any entry in dependencies/devDependencies produces a second physical copy and bifurcates module-level state
  • Committed .npmrc — auto-install-peers=true + strict-peer-dependencies=true (install-time guard against singleton skew) plus a scope-routing line derived from the engine’s own NPM_REGISTRY (empty under public npm). Never an auth line: a committed _authToken=${NODE_AUTH_TOKEN} outranks ~/.npmrc and pnpm expands the unset variable to an EMPTY token it then uses, so the placeholder shadows the real credential — auth belongs to the environment (~/.npmrc, actions/setup-node in CI, registryAuthEnv() for children the CLI spawns)
  • Three enforcement layers — strict-peer at install (aborts the image build on a version mismatch), omnislash doctor’s structural Brain package.json check, and the assertEngineSingletons() boot probe in bootstrapEngineApp() (production only) that fails if any @omnislash-ai/* resolves back inside the brain root
  • Lockfile decoupling — the brain commits pnpm-lock.yaml for local installs only; the image build rides engine’s lockfile and fresh-resolves brain-only deps, so no workspace-shaped importer paths are required of external authors
  • .gitignore discipline for CLI agent dirs — once .claude/ / .codex/ are in the G-set their runtime subpaths (projects/, todos/, sessions/, settings.local.json, …) must be excluded or the daemon commits CLI churn every tick; a warn-level doctor check arms on the declaration
• Suffix-Based Content Layout — brain entities are discovered by filename suffix inside feature directories (features/<feature>/, any depth), not by a registry
  • Entity suffixes — *.scenario.md, *.heartbeat.md, *.hook.md, *.agent.md, discovered depth-agnostically inside a feature; system roles (constitution/Agents/system/role-*.md, a namespaced id one subdirectory per : — system:loop:proposer ↔ loop/role-proposer.md) are fixed-path engine convention, not features
  • Flat feature directories — features/<name>/ holds the scenario, its pipelines, helpers and fixtures as siblings, with no spec/code split; adding a feature is a mkdir + commit, no image rebuild unless a new npm dep appears
  • constitution/ is configuration only — MANIFEST.yaml, models.json, the capability/tool JSONs, PHILOSOPHY.md and system prompts; entities there are not loaded
  • Misplaced files fail boot — defineProject refuses to start when any entity or feature file (.scenario.md .heartbeat.md .hook.md .agent.md .pipeline.ts .blueprint.yml .loop.ts) sits under constitution/ or loose in features/, listing every offending path; the Brain entities doctor check reports late arrivals as [misplaced]
  • Per-feature pipelines — a scenario owns its *.pipeline.ts files by NAME, anywhere inside its feature (subfolders, a directory shared with other scenarios): one primary (<scenarioId>.pipeline.ts) plus 0..N auxiliaries (<scenarioId>-<suffix>.pipeline.ts), when several ids match, the exact name wins, then a scenario with its own primary, then the file’s directory, then the longest id; filename must equal <name>.pipeline.ts, names globally unique; a file no pipeline scenario of its feature owns is logged at boot and failed by doctor Brain entities, never silently dropped
  • System files at fixed paths — system prompts (constitution/Agents/system/*, Grants/custom-grant-parser.md, planner stage prompts, Evaluation/Methods/default.md, Loop/*) ship as engine defaults in @omnislash-ai/config/templates/ and are overridden file-by-file by placing the same path in the brain’s constitution/
  • Brain-tunable probe TTL — every entity loader re-walks features/ to decide whether its cache still describes the disk; defineProject({ contentProbe }) caps how often each kind pays for that walk (engine defaults: hook 1000ms, every other kind 0 = walk per read), so a brain with hundreds of scenarios collapses the per-scenario engine classification bursts onto a single walk instead of paying one each
  • Env var substitution — brain content interpolates env values at render time, with documented best practices in content-layout.md
  • Entity repair — a *.scenario.md/*.heartbeat.md/*.hook.md/*.agent.md whose frontmatter stops parsing is repaired in place by EntityRepairer on boot and on every content tick, announced to the status channel so the diff can be reverted
• Entity vocabulary — a feature ships four entity kinds, scenario · heartbeat · hook · role (a *.agent.md), and every engine surface names one as kind:id — split on the FIRST :, so role:system:loop:proposer is the role system:loop:proposer (@omnislash-ai/types/entity: ENTITY_KINDS, EntityRef, formatEntityRef / parseEntityRef, LOOP_TARGET_KINDS, ActionTarget for what a command acts on); how one is doing is the health set off · ok · attention · failing plus how many of its executions are in flight (@omnislash-ai/types/health: HealthState, EntityHealth) — the Brain Atlas speaks it already
• Feature Switches — a feature is a top-level directory under features/; everything inside it ships and switches together
  • FEATURE.md — optional features/<id>/FEATURE.md with strict frontmatter name?, description?, icon? (a Lucide icon name as lucide.dev writes it — chart-line, users — from the dashboard’s curated set, which feature_set_icon lists in its value enum; the dashboard ships lucide-react 1.47; never an emoji; no icon draws none), enabled? (default true; an unknown key such as enable: is an error) and the feature’s README as body; absent = the feature is on
  • Feature tools — feature_list / feature_get (feature:read, since 1.23.0 the brain index: every feature with the entities it ships — their own and effective flags, whether each declares an evaluation: block (evaluated) and the files each owns; a scenario’s inline hooks included, each a hook of the scenario’s feature with no files of its own (their definition is the scenario’s file) — its own code modules labelled by what they declare registering (inbound event source, service OAuth provider or integration, bot-policy, tool, lifecycle, else module), files that do not load, entities in other features that use its roles, the FEATURE.md sha; no run state — how they run is health_list), feature_trend (feature:read, since 1.24.0: one feature’s runs, failed runs and its agents’ chat turns per hour or day over 24h, 7d, 30d or any window — the chart the Features page opens from a feature’s week), feature_read_file (feature:read, since 1.23.0: the FEATURE.md as written with its sha — empty when the feature has none yet), feature_set_enabled / feature_set_icon and, since 1.23.0, feature_write_file (the whole FEATURE.md, raw) (feature:write): dry-run → confirm → compare-and-swap on that sha, answering { sha, diff, consequences: { liveRunsKilled } } — the dry run of a switch-off says how many live pipeline runs it would kill; a stale expectedSha is refused as conflict, a result that would not load as invalid, and the file keeps every comment. Since 1.25.0 a feature also lists its widget files (widgets: each page’s ui:// address, sha and the .widget.yml beside it), and feature_read_file / feature_write_file take a widget file’s path to read or write one (widgets.md). The same ops back the dashboard’s Features page
  • feature_summary (feature:read, since 1.24.0) — how big every feature is and what it did over a window (window: 24h, 7d — the default —, 30d, …, or from / to; feature narrows it to one, engine the built-in one), per feature and per entity it ships: what it ships by kind (ships); its weight — its share of the brain, 0–1, by what it is made of alone: its units over the brain’s — a scenario (a pipeline among them) 3, a hook 2 (a scenario’s inline hooks included), a heartbeat 1, an agent 1, a code module that registers something 1 (a helper none), a file that does not load as its kind (a context file as code); activity and spend do not weigh; the built-in feature is not weighed —; runs started and how many succeeded, failed or are still in flight; its agents’ own sessions — chats outside any run — with their turns; sessions busy now (working, a session awaiting input included); what executes now (running: runs running, sessions in a turn — never one queued, paused or waiting on a person); requests about it waiting on a person now (needsYou, attributed as hitl_summary attributes them — what the Inbox counts); and what its runs and sessions cost. An entity that did nothing is left out of its feature’s entities; totals is the whole brain, summed from the records — ad-hoc and system runs, runs of an entity no feature ships any more and every pending request included. The size and figures the dashboard’s Features page draws its tiles from. How each is doing: health_list; each run on its lane: run_timeline
  • The Engine feature (since 1.23.0) — feature_list also answers a built-in feature, id engine (builtIn: true): the engine’s system: roles as its entities, the system role files that do not load as its broken files; it has no folder, no FEATURE.md and no switch (feature_set_* / feature_write_file refuse it). Every attribution reads it the same way — a system: role’s agents, runs, spend and requests belong to feature engine. Its shared instruction modules are instruction_list / instruction_get (feature:read) and instruction_write_file / instruction_reset (role:write: the first save copies the engine template into your constitution/, a reset deletes the copy) — the self-evolving loop’s prompts among them since 1.24.0 (loop/… ids for constitution/Loop/**, each with the loop agents that read it and when, and a save refused when a placeholder would reach the agent unfilled); its passes are schedule_overview’s
  • Reserved feature id (since 1.23.0) — engine is reserved: a features/engine/ folder is not a feature — each entity file in it is skipped naming the folder, defineProject refuses to boot on them, and doctor Brain entities names the folder ([Reserved feature id]). Rename the folder
  • Effective enabled — each entity runs only when its own frontmatter enabled (default true for every kind) AND its feature’s enabled are true; entities carry feature, declaredEnabled (the file’s own flag — what entity toggles write) and enabled (effective — what scheduler crons, hook dispatch, pipeline registration, the heartbeat worker, doctor and the loop tick act on)
  • Non-destructive — switching a feature off writes only FEATURE.md; switching it back restores each entity’s own flag
  • Roles switch too — a *.agent.md in a switched-off feature resolves like a missing role; the Agent roles doctor check flags enabled entities that dispatch to it
  • Hot — FEATURE.md is part of the entity-loader fingerprint, so a flip self-corrects caches like an entity edit; the pipelines service re-registers when the set of enabled pipeline scenarios changes
  • Broken FEATURE.md holds, not drops — an unparsable file makes every entity in the feature an unparsable skip pointing at it: crons are held and entity repair tries that file once
• Entity & feature health — one health set for every entity and feature, off · ok · attention · failing plus how many runs are in flight (a count, not a state), judged by the engine from its own records (since 1.21.0)
  • health_entity / health_list (runtime:read, the health.entity / health.list ops; since 1.23.0 one health_list call answers every feature, or one with feature, and each entity carries its trigger in words with its next fire and its ten newest runs as outcomes, newest first, each late when a clock-started run started past its grace, and how many tool calls failed on its newest run (lastRunToolErrors); feature_list carries no run state since) — first matching rule wins: Off (switched off, its feature off, the scheduler stopped or a disabled schedule — the last two only for an entity on a clock); Failing (its file or plan file broken, not served by the pipelines build or no build served, a run that gave up after its retries or broke on an edit — reset it, a schedule that never fires (outside the scheduler grammar, or a cron with no valid time like 0 9 31 2 *), a hook gate that threw, failingAfter failed runs in a row, Down: downAfter expected fires in a row that never started); Attention (runs, requests with no run behind them (an input a start waits on, a scenario grant request) or evolution changes waiting on you, Late: a scheduled start past its grace, or one expected fire missing, a failed run short of failingAfter, tool failures on the last run, a run queued / running / retrying past stuckAfterMs, a role or pinned model on an open provider circuit, a schedule declared but not registered, a workflow scenario with no plan yet, an edit the pipelines build has not taken — the previous build still serves, a *.pipeline.ts that never runs); OK. Every reason in words, most severe first; since 1.24.0 an entity whose model chain cannot dispatch on its first step for a CLI sign-in or provider key the credential inventory grades missing, expired or rejected (“a fallback carries it” when a later step still can; a fallback step alone lacking one is no fault), or whose role’s MCP server authenticates through a connection that is expired or rejected (mcpServers.<name>.connection), is Attention too, and every row carries blockedBy — the provider: of each open circuit on its model chain and the credential: of each such sign-in, key or connection (an MCP server with no live connection blocks too — its revoked connection named, none at all said in words), what the entity page offers as Open provider / Reconnect. A feature is the worst of its switched-on entities plus its own faults (a FEATURE.md that does not load, a stray pipeline file), always with the counts in words (1 failing · 2 need attention · 4 OK). Infrastructure health is health_overview
  • Summaries (since 1.23.0) — run_summary adds onTime (the share of clock-started runs that started within the grace Late reads by — no new number), evalPassRate (graded runs whose grade passed — since 1.24.0 with evals, the window’s graded and passed counts it is a share of), errorClasses (failures per executions.error_class, unclassified for none) and, with by: "feature" | "entity", groups with the same figures and each group’s newest failure; hitl_list takes feature / entity (a request’s run’s entity, the entity of the tick or fire whose turn — or a sub-agent of it — raised it, the scenario it names, else the role of the agent that opened it — derived at read; a scope: chat hook’s agent outlives its fires, so its requests are never the hook’s); hitl_summary (hitl:read) answers what waits on a person per kind and per feature and the requests opened per hour or day; usage_breakdown / usage_trend take the feature dim (the feature shipping the row’s entity now, else its role’s; a system: role or one no feature ships is engine), grouped before the top-N fold
  • The windows are yours — constitution/MANIFEST.yaml § health for the brain, health: in a scenario’s, heartbeat’s or hook’s frontmatter for one entity, each key nearest-tier-wins: graceRatio / graceMinMs / graceMaxMs (grace = clamp(ratio × period, min, max), default 10% within 5 min – 1 h; set one bound alone — a min above the max wins), downAfter (default 2 fires), failingAfter (default 3 runs; 1 = every failed run is Failing), stuckAfterMs (default 2 h). Down counts fires, not hours, so a weekday cron is not Down over a weekend, and a manual run does not stand in for a missed fire; it counts only the fires since its clock last became due — the newest change of its file, its FEATURE.md or MANIFEST.yaml (a re-enable, a new schedule, a released scheduler), so switching it back on is not Down; an entity with a run in flight, with an input request waiting on you, or with no clock-started run on record, is never Down
• Extension Points — every place a brain plugs into the engine is typed, optional and reachable from defineProject()
  • Skills — the primary extension mechanism; brain authors think in skills (SKILL.md + scripts/MCP), not tools
  • Tools — tools: (registry) => void registrar, stamped source: 'project'
  • Integrations — integrations: [defineIntegration(...)], tools + webhooks in one bundle
  • Lifecycle hooks — lifecycle.onStartup / onShutdown with a per-service LifecycleContext
  • Ingest sources — ingest.sources: [defineEventSource(...)] for provider-agnostic inbound events, each optionally carrying its own verify credential check in place of the shared WEBHOOK_SECRET, its own body cap (maxBodyBytes) and per-event resources; engine-reserved names (mtproto, github, widget) throw
  • Business KPIs — kpis: [defineKpi({ id, label, unit, direction, period, goal, read })], up to six numbers read by brain code and shown on the overview; each read isolated under its own timeoutMs (default 8 s) — kpis.md
  • Chat policy — per-bot policy: defineChatPolicy({ chat, sender, engage }), the code tier of the chat frame over normalized signals that never carry an adapter type — chat-access.md
  • Dispatch targets — dispatch: DispatchTarget[] for outbound HTTP fan-out
  • Store curation — integrationsStore.mcpAllowed (reverse-DNS allowlist over the official catalog) and integrationsStore.additional (extra custom rows)
• Engine-Owned Artifacts + Override Sentinels — files the engine regenerates in the brain repo, each with an explicit opt-out
  • The set — Dockerfile + .dockerignore, .github/workflows/deploy.yml, .github/workflows/ci.yml, the synced docs/engine/ tree, docker/compose.{prod,start}.yml.example, and the mirrored skills/engine/ corpus
  • Sentinels — Dockerfile.override, deploy.yml.override, ci.yml.override, docs/engine.override, docker/.infra-examples.override, skills/.engine-skills.override
  • Version stamps — docs/engine/, docker/.infra-examples-version and skills/engine/.engine-skills-version carry the engine version so drift is detectable and self-healing
• Brain-Facing Docs Corpus — docs/brain-dev/ is a self-contained doc set carried inside the @omnislash-ai/cli tarball and synced verbatim into every brain’s committed docs/engine/ — first by omnislash init, then by every regen / upgrade; getting-started.md is its front door and the file doctor hints name, and sibling-only links are enforced by a link-check test
• Brain Scaffolding — omnislash init takes an empty directory to a runnable, committed brain in three flavors (chat-only, scheduled-ops, pipeline-heavy), guarded by a byte-equality + peer-set drift test so a new brain never starts as a copy of the in-tree fixture
  • The author-owned tree — templated: config, constitution/, skills/, the toolchain (biome.json, vitest.config.ts, lefthook.yml), a three-line .npmrc whose registry scope derives from the engine’s own NPM_REGISTRY constant and which carries no auth token
  • The engine-owned tree — NOT templated: init installs the pinned engine and then spawns the brain’s OWN omnislash regen, so a --version-pinned brain is never stamped by whichever CLI ran the command
  • The dotenv pair — .env and .env.example are generated from the live env catalog, never templated, so they cannot drift from the schema the engine validates against
• Brain Example — brain-example/ is the engine’s in-tree fixture: a minimal working brain used for self-contained dev (BRAIN_ROOT=brain-example pnpm omnislash dev), smoke CI and the Dockerfile / deploy.yml byte-equality tests

Agents Runtime

• Unified Agent Runtime — CLI agents (Claude Code, Codex, OpenCode) and API agents (LLM providers) behind one interface; the consumer picks via ModelRef, never by calling a different API
  • CLI mode — child process per turn, stateful sessionId resume, repo required, tools delivered over the engine’s MCP server, resilience via backoff retry + stream-idle watchdog
  • Long turn for Claude — background work without a pool — the Claude runner hands the prompt to the Agent SDK as a streaming input (stdin stays open) and decides the terminal itself: the first result that arrives with no live background task (the harness’s background_tasks_changed set, minus its ambient housekeeping entries). A backgrounded shell, harness subagent or Workflow run therefore finishes inside the turn and the CLI wakes the model with its notification in the same turn (several results per turn — each reports its own segment’s tokens, turns and cost, and they are summed — last non-empty answer kept). The set draining closes nothing, because the drain is exactly what triggers that wake-up: a wake-up segment may start more background work and the turn ends at ITS terminal instead, so chained background steps work end to end and only a segment that starts nothing new ends the turn. The whole chain is bounded by one AGENT_BACKGROUND_HOLD_TIMEOUT_MS total; the process still lives for exactly one turn, and Codex / OpenCode stay one-shot
  • API mode — in-process AI SDK stream, stateless (history rebuilt from conversation_events every turn), tools injected directly as a capability-filtered ToolSet, resilience via fallover chains + connection timeout; prompt-cached per chain step in that step’s dialect — the role’s system prompt (shared by every agent of the role), the end of the replayed history, the tool-loop tail — with environment and MEMORY.md in a standing system message and the daily window / state in each turn’s message, never in the cached system prompt; TTL promptCache.ttl (engine 1h → MANIFEST.yaml → role)
  • fake harness — a test/demo harness programmed from the prompt itself with <fake>{…}</fake> directives (text/thinking/tool/sleep/complete/fail/askQuestion/requestGrant/hang/awaitSignal steps, named transcript fixtures, synthetic usage, structured output matching jsonSchema), so the whole FSM — streaming, HITL pause, failover, cancellation — can be driven deterministically without burning tokens
  • Harness-specific adapters — Claude via @anthropic-ai/claude-agent-sdk, Codex via @openai/codex-sdk, OpenCode via a generic subprocess runner; all three normalize onto one CliStreamEvent union through shared SDK-shape factories, and each takes the system prompt through its native instruction channel (Claude system prompt, Codex developer instructions, an injected OpenCode instructions file) — sent once, not pasted into every user turn; a changed prompt on a live Codex thread is re-delivered once at the top of the next turn
• Crash-Proof Agents (Durable Runtime) — every agent is a Restate Virtual Object keyed by agentId: kill the server mid-run, redeploy, lose the network — the agent resumes exactly where it stopped
  • Single durable owner — Restate serializes invocations per key, so the per-agent execution queue is native (no BullMQ queue, no hand-rolled claim/CAS); the VO is the sole writer of lifecycle state
  • Same-invocation HITL pause — the enqueue handler holds the per-key lock across the entire session including a human wait of arbitrary length, so a pipeline callbackId never leaves handler scope and settles exactly once
  • agents row is a projection, not a control surface — status / error / currentInvocationId / currentAuth / currentInputIds are projected after each transition, then exactly one lifecycle signal is emitted (agent:started / agent:completed / agent:input_request), so observers never wake before the row is readable
  • Creator attribution — agents.created_by — every agent row records the Actor that created it (spawning agent, heartbeat, hook, workflow run, pipeline, planning, evaluation, loop, chat, dashboard, system); AgentCreateParams.createdBy is required on every create, NULL only on older rows
  • Zero zombie runs — reconcileAgentOrphans (pipelines startup + scheduler 5-min sweep) cross-references each busy agent’s currentInvocationId against sys_invocation and routes every settle through the VO’s EXCLUSIVE reap handler, which no-ops if a fresh turn re-claimed the row, purges the dead invocation’s limiter footprint and clears a dead pause’s resume-awakeable
  • Gap-filled terminals — settleRunlessTerminal announces a stream terminal for every terminal with no run to announce it (stop of a paused agent, cancel while parked, preclaim bail, reap), stamping the session’s inputIds so the chat card it served still closes
• Durable Dispatch Primitives — six verbs on the agent facade, all routed through the per-agent VO over the Restate ingress
  • agent.enqueue(input, opts?) — programmatic fire-and-forget standalone turn carrying its own callback / schema / opts; a busy agent never throws, the turn is durably serialized behind the per-key lock
  • agent.call(input, opts?) — programmatic request-response awaiting the terminal AgentExecutionResult; dispatched with send then awaited by re-attaching to the invocation on an engine-owned 4-minute window, so it is not capped by Node’s 300 s headersTimeout and has no overall deadline (the bound is causal — any invocation that ends answers the attach)
  • agent.send(input, opts?) — the chat verb: append to the agent’s durable inbox and poke the VO’s zero-arg run handler; callback-/schema-free by type
  • agent.sendCompact(opts?) — the chat /compact: a compact entry in the same inbox, at the tail (queue mode) or — with interrupt — at the head after preempting the live turn; served alone as the compaction turn, the outcome on its turn.completed
  • agent.sendCommand(command, opts?) — a CLI harness’s own slash command (/review, /init) from a chat: an inbox entry of its own (kind: 'command'), served alone with nothing in front of it — no envelope, no merge — because a harness reads a slash command only when it leads the user message; otherwise exactly send
  • agent.stop() — cancel the live Restate invocation; the VO’s catch aborts the run, settles the pipeline callback and projects cancelled
  • resume — deliberately not a facade method: the HITL gateway reads resumeAwakeableId from Restate’s state introspection and resolves the suspended awakeable directly through the ingress, soft-deferring when the barrier is not yet committed
  • Dispatch modifiers — interrupt (cancel the live invocation, then dispatch), delay (deferred dispatch, enqueue only), idempotencyKey (duplicate sends latch onto the running invocation), signal (caller-owned abort)
  • Agents.task / Agents.oneshot / Agents.recreate — ephemeral fan-out sub-agent (create → enqueue → await the row terminal → soft-delete, one timeout contract with a 24 h anti-wedge backstop), ephemeral inline one-shot, and a fresh deterministic slot per call
  • dispatchAndObserve — dispatch-then-observe helper shared by planner stages and the recovery boss; an already-aborted signal dispatches nothing and returns cancelled instead of minting a turn only to kill it
• Durable Chat Inbox (Mailbox) — agents.pendingInputs is the chat’s durable, ordered queue of operations (messages, harness slash commands, and a queued /compact), served by the VO’s run handler one turn at a time
  • An entry lives until delivered — read → claim → turn; an entry leaves the inbox once its turn has put it into the agent’s history, so an interrupted turn’s message is never served twice (the next turn sees it, like Esc in an interactive CLI), while a turn that died before delivery leaves its message to be served again; a message is never lost
  • A deploy terminates interrupted, not failed — interruptedByShutdown rewrites only a failed terminal, and only while isShuttingDown() is latched, so no failure bubble is posted and anything not yet delivered stays owed; a boot-time sweep then pokes run once per agent still owed a turn
  • Merge semantics — nextMailboxTurn takes the inbox head: consecutive messages merge (bodies joined with \n\n---\n\n, attachments FIFO, last runOptions wins), so rapid sends collapse into one follow-up turn; a queued compact is served alone, a barrier nothing is merged across
  • One turn, then yield — after its turn the handler pokes itself to the back of the agent’s queue when entries remain, so a message that arrived mid-turn is served next (human intervention in a working agent) while programmatic turns queued meanwhile — auto-compact, agent_call, hooks — never starve behind a busy chat
  • Explicit discard — Agent.stop → stopAgentDiscardingInput drops input a turn claimed but has not delivered yet (dashboard Stop, /agents stop button, agent_stop tool); /stop clears the whole column; interrupt preempt, flushMailbox and recovery use the bare stopAgent
  • flushMailbox — “send now”: cancel the live turn, then poke, so the queued inbox is served at once
  • Empty drain is an inert no-op — a surplus poke takes no permit, projects no running, emits no lifecycle signal and does not touch the row’s terminal projection
• Node-wide Concurrency Limiter — a Restate agent-limiter VO caps concurrent agent subprocesses across the whole deployment (AGENT_EXECUTION_CONCURRENCY, default 12) as one global pool shared by every agent class
  • Permits free across a HITL pause — an awaiting_input pause returns from the run normally, so the cap counts active subprocesses rather than parked agents
  • Token + invocation accounting — each permit carries a unique-per-acquisition token (the release key) and the acquiring invocationId (the recovery key), so purge(invocationId) can remove a dead invocation’s entire footprint — held permits and still-parked waiters — without stranding anything under a reused invocation id
  • Nested permits — a sub-agent spawned from inside a running agent carries auth.spawnedByAgentId and takes a non-blocking permit, so a permit-holding parent can never deadlock on a permit-needing child
• Streaming — real-time output via Redis Streams with namespaced subscribers, so UI, planner and workflow observers never interfere
  • Stream event taxonomy — one Zod union (agentOutputEventSchema) across content.delta, item.*, turn.*, tool.progress, task.*, hook.*, hitl_*, session.cleared, model.rerouted, runtime.warning|error|retry, each carrying eventId / provider / threadId / createdAt / turnId / itemId
  • Three derived types — AgentOutputEvent (everything on the wire), AgentEmitEvent (what producers push), AgentConsumerEvent (what subscribers get); the run terminal reaches consumers as an AgentStreamTerminal — a Pick of AgentExecutionResult that deliberately carries no output text
  • Consume modes — consume() is ephemeral (auto-stop at the first turn.completed, for one-shot programmatic observers), consumePersistent() subscribes once and streams across turns with a subscribe-time floor; a persistent request over a live ephemeral consumer upgrades it in place with no teardown
  • Late-join and replay — readState / readOutput / readSnapshot, cursor-resumable streamOutput({ afterId }) on a dedicated blocking connection, and streamOutputMany multiplexing N agents into one XREAD for the dashboard matrix
  • PG↔Redis checkpoint — every event’s Redis stream id is stamped onto its conversation_events row, so a snapshot page hands the client an exact lastEventId and the live tail resumes with no gap and no duplicate
  • Cross-process waiting — waitForStateChange combines the pub/sub bell (fast path) with a periodic durable re-read of the row (correctness floor under an at-most-once bell)
• Conversation Timeline (conversation_events) — one append-only table is the single source of truth for an agent’s history; every path reads it and everyone writes through ConversationService
  • run.emit() 3-way fan-out — Redis stream write (returns the streamId) → PG persistence carrying that checkpoint → derived EventBus notifications
  • Persisted vs transient — CONVERSATION_EVENT_TYPES decides what lands (item.completed, turn.started|completed|plan.updated, hitl_*, session.cleared, model.rerouted, runtime.*, task.completed, hook.completed); deltas and item.started collapse into their terminal row
  • Tool-call pairing — item.started is held in memory until its item.completed lands, then persisted enriched with toolName / toolInput / toolCallId
  • Monotonic id ordering — every reader sorts by the serial id, never by timestamp, and compaction is a prefix delete that keeps surviving rows’ ids, so delivery cursors and SSE checkpoints stay valid
  • Prompt storage split — the system half is content-addressed in agent_system_prompts (one row per distinct prompt), the turn half rides conversation_events.turn_prompt, joined back byte-identically on read; two consecutive turns with different hashes make a cache-prefix break attributable and diffable
  • Paused-turn ledger row — a HITL pause persists its own turn.completed{state:'paused'} row (never streamed) so pre-pause spend reaches Audit › Cost and the context meter even if the resume never happens
• Session Management & Compaction — session save/restore, history compaction and transcript management, reported as outcomes rather than silent no-ops
  • Session slot ownership — the single agents.session_id column holds the primary harness’s session (config.ref step 0); a failover step runs with ownsSessionSlot: false and can never stamp its id over the primary’s (the cross-harness session-poisoning fix)
  • session_not_found self-heal — a resuming step holding an id invalid for its harness clears the slot and re-runs the same harness once fresh, inside the executor, so the chain never burns a circuit-breaker tick on a healthy primary; recognized across Claude / Codex / OpenCode wordings
  • /clear is a rotation — the live conversation is archived, a fresh one is created with a session.cleared back-pointer, the inbox drains and the agent:cleared bell reaches every chat where the agent was active
  • Threshold summarization — summarizeIfNeeded folds the prefix into conversations.summary past conversation.summarizeTokenThreshold, using the brain-defined summarization prompt and the fast chain, in-layer (text→text, never an agent run, so nested compaction cannot deadlock)
  • compactAgent — one compaction turn on the agent’s queue, API and CLI alike, folding the conversation and (Claude CLI) compacting the harness session in parallel inside it, so no other turn can race the fold; with wait it returns a CompactionResult reporting the conversation rewrite (with before/after token sizes) and the session separately, since they succeed and fail independently — also carried on the turn’s turn.completed; interrupt and wait are independent knobs, both default off
  • Compaction markers — context_compaction items narrate a compaction on the stream (item.started → terminal pair for the compaction turn, a declined marker when there was nothing to fold, terminal-only for the finalize-stage summarize and the harness’s own after-the-fact compact), collapsed by the dashboard into one work-log row
  • Control turns — the compaction turn is dispatched with turnKind: 'control' + control: 'compact' (the engine operating the agent, not conversing with it), so it records no user_message row, never echoes into a bound chat, is skipped by everything that reasons about the conversation (context policy, summarize, memory flush), and runs on the primary harness only — never the fallover chain, since another vendor has no session to compact and would answer the literal /compact in prose; every other turn — chat, enqueue, call, heartbeat — is a conversation turn, and the chat inbox produces one only from a typed compact entry, never from a message
• Context Window Policy — per-role token marks (context.notifyAt / context.compactAt) decide what the engine does as an agent’s window fills
  • Edge-triggered marks — at the turn’s end the agent compares this turn’s usage.context against the previous turn’s and fires only on the crossing, so there is no “already notified” flag: a compact re-arms the mark by data
  • Per-key resolution — engine → MANIFEST.yaml § context → the role’s own context: block, key by key (resolveContextConfig), read lazily, so editing the role file or MANIFEST changes live agents’ policy on their next turn; system:general’s block is its own, not every role’s default (since 1.21.0)
  • Durable, non-interrupting auto-compact — the agent’s own durable owner decides the crossing and queues the compact turn on itself, journaled: exactly once per crossing, never lost to a restart, never repeated per bot replica, no bot service required; it runs before the agent’s next turn and never kills one. agent:context_threshold announces the crossing; the bot only posts the nudge
  • Honest denominators — percentages appear only when the runtime reported a window; the nudge names the agent that crossed, because a chat hosts more agents than its active one (heartbeats, hooks, agents switched away from, a business chat’s sub-agents) and /compact typed in reply would target a different one; an ordinary sub-agent runs surfaceless, so its nudge reaches no chat
• Context Placement (cache-prefix stability) — what goes where is decided by volatility and agent-independence, never by topic, because Anthropic invalidates tools → system → messages top-down
  • Three fields — systemPrompt (authored, agent-independent), contextSources (environment, MEMORY.md, the period ladder, agent state — tagged sources made of keyed sections, injected into the message stream), turnContext (clock + this turn’s recall)
  • Per-step, per-section envelope — what goes out is planned per executing step (a failover step and a session_not_found self-heal, both brand-new sessions, still get everything) against one map of what the transcript holds, agents.context_marks (section → hash): only the sections that moved are re-sent, as self-describing updates; a gone view or a lost source gets a one-line tombstone; unknown marks (after a compaction or a reset) re-snapshot everything under a header that withdraws the blocks above. A harness that compacts silently (Codex, OpenCode) re-sends a changed source whole
  • API prompt caching (promptCache.ttl) — applyPromptCache marks each API chain step in its own cacheDialect: cache-control on Anthropic native and vercel:anthropic/*, breakpoints on OpenAI GPT-5.6+, none elsewhere; TTL 5m | 1h, engine 1h → MANIFEST.yaml → role promptCache:
  • Preset-side knobs — the Claude runner unconditionally pins excludeDynamicSections, CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1 and CLAUDE_CODE_TOTAL_TOKENS_REMINDER=off, which is what lets a fleet of same-role agents share one prefix, and CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 (Codex: features.memories = false): a harness keeps no memory of its own — an agent’s memory is the engine’s, and a role without a memory: block has none
  • Break detection — agent_cache_prefix_breaks_total{level} compares hashed tools / system prefixes across consecutive turns per (agent, harness) and warns when somebody else’s build moves them
• Context Budget — per-role breakdown of what fills an agent’s context window before its first message, with findings that name the concrete lever
  • Three measured groups — tool definitions (priced by the exact tools/list bytes for a CLI delivery, the narrower AI-SDK projection for API), the system-prompt cascade attributed section by section from PromptSection[], and the context envelope by named part
  • promptedTokens vs deferredTokens — the on-wire turn-1 cost and the search-deferred remainder are never conflated, so a Claude or Codex deployment is not shown as five times heavier than it is; anything known-but-unpriced is counted unmeasured, never zero
  • Delivery-aware pricing — deferral, grant selection, session traits and the window all hang off one resolved ContextDelivery (cli+harness(+router) / api, the grant on both arms), derived after the ref resolves; which deliveries defer is one rule, deferredOnTurnOne — on API the role’s loading plan (toolLoading), direct Claude keeps all but its engine-eager and role-eager tools behind ToolSearch, native Codex keeps every MCP tool behind its tool_search, and a routed Claude or Codex step and OpenCode defer nothing (Claude Code turns ToolSearch off behind a non-Anthropic base URL)
  • Window provenance — registry or observed — an API delivery reads contextWindowTokens off models.json, a CLI role is sized by the one window resolver (resolveContextWindows) keyed by the MODEL its delivering step was last measured on (findServedContextModels: delivery ref → usage.context.model, month lookback, derived never stored); window-unknown splits on the harness reportsContextWindow flag
  • Measured prefix beside the estimate — measured: { tokens, at, outsideEngine }: the first API call of the newest turn of this role, on the step the report prices, that opened a fresh session (usage.firstCall + turn.completed.delivery, read by findMeasuredPrefixes) — so the harness’s own preset prompt and builtin tools, which no estimate sees, show up as outsideEngine (measured − estimate: harness floor + estimate error), a line and never a verdict; on Codex only a fresh turn that called no tool qualifies (its usage is one sum per turn)
  • Findings — prefix-over-budget, no-tool-deferral, unused-tools (per role, from the spend ledger; silent for a role that ran nothing in the window), unmeasured-tools, skills-truncated, skills-catalog-heavy, state-truncated (state views the state.chars budget cut or stubbed), memory-heavy, role-heavy, window-unknown, mcp-servers-unavailable, and the footprint flags wildcard-capabilities / wildcard-skills ('*'), memory-unused (memory declared, no memory tool called), grant-pinned (live agents of the role holding capabilities beyond its file) and unconfined-builtins (a Codex / OpenCode ref whose own tools ignore the grant); every threshold is the role’s resolved context: config (engine → MANIFEST → role)
  • Usage beside the footprint — agent.context (tool agent_context, runtime:read) answers each role’s report with its runs, the tools they called and the skills they opened (skillsOpened, beside skillRuns — the turns that recorded their opens; a Codex or OpenCode turn records none) in a window (the one window shape every period read takes, default the last 7 days), from usage_records by role — runs counted as usage_breakdown counts turns, tools by the bare name usage_tools names them, spend left to usage_breakdown by role (usage:read) — numbers that survive an agent’s reap and a compaction — and “N tools / M used” (offered, on turn 1, deferred, called)
  • Trim to used — role.trim (tool role_trim, runtime:read) previews a role_update patch: the skills: list narrowed to the skills the role’s agents opened (recorded per turn in usage_records.skill_loads; observed on API and Claude CLI, left alone on Codex / OpenCode and while any run in the window did not record its skill opens — a fallover to Codex may have used any listed skill), deferred tools called on most runs proposed for toolLoading.eager, the diff and the tokens every turn sheds; it writes nothing — the patch commits through role_update against the previewed sha
  • Feature contexts carried (contextUse) — per role, each feature context’s attached and stubbed turns against the turns that recorded contexts (usage_records.contexts), mean rendered chars, links and stubbing knobs; a stub raises context-stubbed, shown on /system/context
  • Surfaces — /system/context (one tab per role with its usage and a Trim to used preview, unresolvable and failed roles reported separately) and a Context budget doctor check that grades the heaviest role’s on-wire tool definitions, each role priced under its own delivery (tools a direct-Claude or native-Codex role keeps behind its search tool, and an API role past toolLoading.deferAbove behind tool_search, do not count; an OpenCode, routed-Claude or routed-Codex role’s whole set does, and so does an API role at or under the threshold); its hint names the lever for that role — a deferring harness or toolLoading, a narrower capabilities: grant or constitution/engine-tools.json — and the skills to turn off when the catalog cap dropped some
  • Role-prompt budget — promptBudget.roleChars (engine 6000 → MANIFEST.yaml § promptBudget → a role’s own promptBudget:, 0 = off): a role body over it raises role-heavy on /system/context with its three largest ## sections, and doctor Context budget warns naming it — observation only, never a failure. Writing guidance: role-prompts.md
• System Prompt Cascade — one composeSystemPrompt builds the prompt for the CLI path, the API path and the budget report, so a report can never describe a prompt nobody sends
  • Modules — identity → role → background-tasks/environment → chat delivery → memory instructions → language → question policy → skills catalog → per-row instruction append, joined with an explicit separator and each tagged with a closed PromptSectionId
  • Per-harness question policy — a different AUQ enforcement file per harness (claude / codex / opencode / generic / API / disabled), because tool names and footguns differ per runner
  • Background-tasks module — CLI-path runtime truth about background work, per harness: Codex / OpenCode get the one-shot rules (the subprocess dies at the turn’s end, with the live AGENT_STREAM_IDLE_TIMEOUT_MS rendered into the polling guidance); Claude gets a half that states ONLY where the engine diverges from what its own harness already teaches — nothing runs between turns (it names no harness tool — the timer builtins are never offered), with the AGENT_BACKGROUND_HOLD_TIMEOUT_MS total (omitted when the idle watchdog is off). Both halves carry two tool bullets that follow the grant: “come back later → schedule_create_prompt” only with schedule:write, “too long → agent_task / agent_create + agent_enqueue + agent_await” only with agent:execute and runtime:read — a role is never told about a tool it is not offered
  • State module + modelling guide — a role with state: gets a short module (what its namespace owns, which views render, the determinism rule) plus one pointer to the unlisted agent-state engine skill for the long guide — present only when the agent can load it (CLI always; API with skill:read)
  • Chat-delivery module — runtime truth for an agent a person talks to (agents.source = 'chat'): the person reads the turn’s final message, so it carries the whole answer and stands on its own (never “see above”); text between tool calls is only passing live status; bookkeeping goes before the answer, because text written after it replaces it; the text before a question is delivered with the question — plus a per-surface status-card half. It agrees with the CLI harness’s own final-message convention instead of overriding it, and adds what no model can observe from inside a turn; carried regardless of promptFlags
• Per-Role Prompt Flags — role/agent frontmatter gates which system-prompt modules the agent gets, and turning one off skips the upstream work, not just the text
  • Seven flags — identity, environment (also gates background-tasks), dateTime, questions, capabilities (the requestable-capabilities module; false drops the list, never the request tool), skills, language
  • skills is three-valued — 'engine' | 'harness' | 'both' decides which of the two skill systems delivers what the role’s skills: list grants on a CLI turn (the engine’s policy-gated catalog vs the harness’s own Skill tool and self-discovered .claude/skills/), because “both catalogs live” must be a choice rather than an accident; there is no off value — no skills: list is no skills (a stale false fails the role load)
  • Memory and skills are declarations, not flags — what an agent remembers is the top-level memory: block, which skills it sees the skills: list; no block, no memory, no list, no skills
  • Resolution — engine defaults + per-role override by a pure resolvePromptFlags, every flag replaced wholesale; defaults reproduce today’s cascade byte-for-byte, locked by a snapshot test
  • Loop roles ship without memory — the proposer (loop/role-proposer.md), the implementer (loop/role-implementer.md) and the judge (role-evaluator.md) declare no memory: block, so a round is reproducible and the judge’s rubric holds nothing unpinned; omnislash doctor → Loop role memory warns when a brain copy declares memory for the proposer / implementer, fails for the judge
• Agent Roles — a role is what an agent knows how to be; system roles ship with the engine, brain roles are markdown files
  • Engine system roles — general, chief, planner, coder, reviewer, researcher, evaluator, loop:proposer, loop:implementer, memory, consolidator, boss, editor-assistant, git-conflict-resolver, browser, remediation — a closed set: a brain overrides one by shipping its own copy of the file, and its own roles are brain roles (features/<feature>/<name>.agent.md); a role-*.md under any other id is skipped and named by Brain entities (with the rename when the id was renamed — a stale role-browser-operator.md or role-dashboard-guide.md). Namespaces are subdirectories: each : after system: in a role id is one directory under constitution/Agents/system/, so system:loop:proposer is loop/role-proposer.md and a brain overrides it with its own copy at constitution/Agents/system/loop/role-proposer.md (a role-proposer.md directly under system/ is a different role, system:proposer)
  • Brain roles — user-defined personas as <id>.agent.md files inside a feature directory (features/<feature>/) (name, description, body, modelRef, skills, capabilities, mcpServers, promptFlags, context, promptBudget); brain roles take priority over system defaults
  • Three-layer inheritance — system:general frontmatter → role → the agent’s own overrides; nothing is pinned: the model and the grant resolve from the role file on every turn (capabilities is the exception to the ladder: the role file’s own list, never role-general.md’s — no list means no capabilities, everything means an explicit '*'), so a role-file edit reaches live agents on their next turn; the row keeps only overrides — a model chosen for the agent (modelRef at create, /model, the edit form; empty = follow the role), capabilities added on top of the role’s, and an agent-spawned child’s ceiling (its spawner’s capabilities, for life); skills / mcpServers / promptFlags / context / prompt body are read per run the same way
  • Role writes — one path, by agent or page — role_update edits a role file (brain role in place; a system: role into your brain’s copy, the first write copying the engine template — the dry run says so) — name, description, modelRef, capabilities, skills, memory, promptFlags, toolLoading, promptCache, promptBudget, sessions, context, mcpServers, body — never the money budget:, which is budget_update’s (all three role_* writes refuse the key); role_create makes a new features/<feature>/<id>.agent.md. Each is dry-run → confirm → compare-and-swap on the file’s sha, refuses a file the role loader would skip, and answers what the write means: the grant it resolves to, the memory it declares, the fork, a brain-wide model in MANIFEST.yaml that shadows the file’s, and for the loop’s own roles what the loop does differently. A write that ADDS capabilities or MCP servers, or moves the role onto a model whose command-line agent (Codex, OpenCode) keeps its own shell, file and web tools whatever the grant says, is role_widen (role:widen, a person approves) — role_update / role_create refuse it, because every live agent of the role holds the new grant from its next turn. The dashboard’s agent pages (/agents, an agent’s Definition and Context), New agent dialog and Settings → Agent defaults cards call the same ops, and show a widening’s delta to the person before it lands. Since 1.23.0 role_write_file replaces a role file whole (the raw editor’s save, held to the same checks; a widening is role_widen with content), role_reset (role:widen — the template may grant more) deletes your brain’s copy of a system: role so the engine template serves again
  • Role reads (since 1.23.0) — role_list (feature:read) lists every role, the engine’s system: roles included (feature engine), each with its source (brain, engine = on the engine template, engine-customised = your brain keeps its own copy), the model it resolves to, how many skills and capabilities it holds and which it declares (declared), whether it declares memory, the MCP servers its agents connect to (mcpServers, by name), the scenarios / heartbeats / hooks that dispatch to it and the chats it serves (a bot’s own role, an access.yaml route, a secretary counterpart); role_get adds its frontmatter as written, body, {{placeholders}}, path and sha (forked = the text is the engine template and the first write copies it), or broken for a role file that does not load (its id and source answered either way); role_read_file (feature:read) is the role file as written with the sha role_write_file takes (for a system: role you never customised, the engine template — forked)
  • Picker reads (since 1.23.0) — model_list (config:read) lists every ref a modelRef: may take that can dispatch now: the models.json role words (API first, then CLI), each cli:<role>, the aliases, the API models with a configured provider and the CLI harnesses, each with its mode and what it resolves to — since 1.24.0 also the roles whose model names it (usedBy), a model’s provider, context window, pricing, rate limit and whether it is hidden (meta), and the speech / transcription chains defineProject declares — and the roles with a voice (roleSpeech) or a transcription chain (roleTranscription) of their own; skill_list (skill:read) lists the installed skills, each with its source, whether it can run here and the env vars or binaries it is missing — since 1.24.0 also whether it is switched on, what it is missing by remedy (eligibilityIssue), where the lockfile pins it and whether its directory drifted, the roles that list it (usedBy) and when an agent last opened it (lastLoadedAt, with loadsObserved: false when no turn that could have shown an open ran), plus the lockfile entries missing on disk
  • Role handlers (per-role extension point) — an AgentRoleHandler can be registered against any role (registerRoleHandler) to install a gate() that short-circuits a turn before any cost; the boss handler skipping a stale wake-up returns a quiet cancelled that is still announced on the stream
• Playwright MCP Browser — headless browser as a sidecar MCP service: agents get navigate, click, read, screenshot across all CLI providers; toggleable via services.playwright
• Browser Role — engine-shipped system:browser with the browser pre-attached and an anti-prompt-injection prompt; any agent spawns it with agent_task, engine code with Agents.task — no per-brain role authoring, and the only role that can carry MCP servers
• Full Desktop (computer use) — not shipped; a brain plugs one in as an HTTP MCP server on a role: a managed cloud desktop, or its own desktop container added through a compose override. Recipe, sizing, file hand-off through the artifacts root and approval rules: computer-use.md
• Per-Agent MCP Servers — the engine injects its own omnislash MCP entry per invocation with the caller’s auth context as URL query params, and merges the brain’s declared servers under it
  • Merge priority — .mcp.json (Claude only) < agent .agent.md frontmatter mcpServers < the engine-managed omnislash entry; an agent-declared omnislash key is dropped with a warning
  • Per-harness delivery — Claude via the SDK mcpServers argument, Codex via the in-memory CodexOptions.config, OpenCode via OPENCODE_CONFIG_CONTENT; ${VAR} placeholders interpolate from the environment
  • The declared set is the whole set (Claude) — sessions launch with strictMcpConfig, so the CLI mounts no claude.ai account connector, plugin or user-scope server on top; a declared server short of connected at session start is warned by name
• Structured Output — Zod-schema JSON responses from any agent, alongside plain text, persisted on the terminal turn.completed and mirrored onto the agent row
  • Runtime normalization — normalizeOutputSchema strips every constraint no strict provider accepts, forces additionalProperties: false on closed objects, and rejects recursion and non-object roots at two call sites (agent dispatch, tool registration)
  • Open-map policy split — structured output rejects a z.record (an unsatisfiable closed map would be silent corruption), while tool schemas preserve it as a genuinely open contract
  • Provider constraint matrix — documented per-provider support and limits (Claude strict-tools/optional/union budgets and compile timeout; OpenAI property, depth, enum and character caps) plus the safe cross-provider subset
  • Codex double-envelope unwrap — Codex sometimes satisfies a strict schema by serializing the real object into one of its string fields; the engine detects and unwraps it structurally, logging every hit, so brains need no unwrap of their own
• Model Fallback & Retry Resilience at the run level — failure is classified and surfaced, never swallowed
  • classifyError — one shared oracle answering two orthogonal questions about a failure: retryable (worth another attempt against the same provider, after a delay) and failover (worth the next step of a fallover chain). It covers timeout, rate_limit, session_not_found, bad_request, authentication_failed (401 / invalid key / expired token) and billing_failed (402/403, credit or key limits, insufficient_quota), plus provider reset-hint parsing (“resets 3:10pm (Europe/Amsterdam)”, “try again in 5 minutes”, Retry-After) into a real delay. On the API path it reads the status code and the provider’s own error code off the parsed transport error rather than hunting for them in the message text, which no longer contains them — the harness-shaped text patterns stay first-class for CLI agents, and the order is provider code → text → status (Anthropic bills an exhausted balance as HTTP 400, so status may not outrank what the message says)
  • Fallover is fail-open — a chain advances on anything the oracle does not positively rule out, including failures it cannot classify at all. Only a real 400 (a malformed request fails identically at every step), a stale CLI session (which self-heals on the same harness) and a caller’s own cancellation stop a chain. So a provider that runs out of money, has its key revoked, or fails in a way nobody has a pattern for yet costs one step, not the turn — the multi-provider apiChains you declared in constitution/models.json behave the way declaring them implies
  • Stream-idle watchdog, both execution modes — a turn emitting no stream event for AGENT_STREAM_IDLE_TIMEOUT_MS (default 15 min, reset by every event, 0 disables) fails as a retryable timeout, killing a wedged CLI harness or aborting a silent API stream and releasing its AGENT_EXECUTION_CONCURRENCY permit. A Claude turn held open by live background tasks is silent by design, so while the harness reports live work the budget in force is AGENT_BACKGROUND_HOLD_TIMEOUT_MS (default 1 h, 0 = the idle budget, inert when the idle budget is 0) — a TOTAL for the turn rather than a per-gap window: a deadline armed the first time work goes live, so a model chaining wake-up after wake-up spends one budget between them instead of renewing it per gap. The same retryable timeout when it trips (the retry starts with a fresh budget), and a deployment value because it bounds how long background work can hold a permit and an idle CLI process. A result with a HITL pause armed ends the turn regardless of live tasks — a paused turn keeps the shape it always had
  • In-process backoff retry — retryWithExponentialBackoff re-runs a step and banks each discarded attempt’s usage segments so burned tokens still reach Audit › Cost
  • Resilience events — model.rerouted (with fromModel / toModel / reason failed|circuit_open / the real triggering error) and runtime.retry (provider / attempt / maxAttempts / errorCategory) are first-class stream events reaching both Redis and PG
  • A stream error is a failed turn — an AI SDK error part is terminal and rides the result into one resolveOutcome, so a dead turn is failed with classification instead of completed with empty output; text and per-step usage produced before the error survive
  • Tool failure inside a turn is part of the result — failed tool calls are carried on the turn’s outcome (and onto meta.heartbeat.toolFailures) rather than being a line in the logs, so a tick whose delivery tool failed cannot read as green
  • Mode-independent tool ledger — AgentRun.toolCalls counts calls per tool name (keys in first-call order) at emitDerivedEvents, the one choke point both CLI and API tool results pass; runDispatch derives the result’s toolsUsed and hasToolUse from the same keys, so the list and the boolean cannot disagree, and the counts go to the spend ledger
• CLI Failover with Trace Handoff — the next harness in a chain picks up the execution trace and continues rather than restarting
  • Handoff file — the timeline is drained, serialized to a temp markdown file (led by the conversation’s summary once a compaction folded part of it), and the next step’s prompt gets only a <handoff-context> pointer (the harness reads the file with its own Read tool); all handoff files are cleaned in a finally
  • Usage banking — failed attempts’ usage segments fold chronologically into the final result, so the run’s single ledger row includes burned attempts with no double count
  • Same-harness continuations skip it — the SDK sessionId resume already carries the history
• Finalize Pipeline — a fixed, composable sequence of post-dispatch side-effect stages with an explicit per-stage error policy
  • Stages in order — writeOutputFile → emitTurnCompleted → recordUsage → drainStream (fatal) → summarizeConversation → flushMemory (background); the context-window policy runs after them, in the agent’s durable owner
  • Side-effects only on the VO path — voFinalizeStages writes no ownership state; the VO owns status, the row projection and the lifecycle signal
  • Brain extension point — AgentExecutorDeps.extraFinalizeStages run after the defaults so they observe fully committed state
• Per-Call Run Options — a single dispatch can override provider and prompt behaviour without touching the agent row
  • CLI knobs (opts.cli) — webSearch (false drops Claude’s WebSearch — it never widens past research:read / Codex webSearchMode), reasoningEffort (the per-invocation override of the ref’s @<effort>)
  • Prompt knobs — systemPrompt (replace the engine cascade entirely, including the per-row append), skills (replace the role’s skills list for this run — set by a scenario’s skills: and agent_task, never on a chat turn), agent.role (re-resolve prompt / skills / MCP for this turn)
  • Behaviour knobs — interactive: false (non-interactive autonomous mode: the agent cannot ask questions), outputSchema (raw JSON Schema on the wire; a Zod schema in the pipeline SDK’s runAgent / safeRunAgent, which returns the output typed and parsed), outputFile (auto-write the structured output or text result to a path), memoryFlush, auth (execution identity merged into the run’s AuthContext), runIn
• Agents That Manage Agents — sixteen engine tools let an agent spawn, drive and supervise child agents, so multi-agent hierarchies get real oversight instead of fire-and-forget
  • Spawn & drive — agent_create (the op agent.create, agent:execute: a role, an optional name, model, lineage, repo, runIn and first task; ifExists: 'reuse' with a name makes it get-or-create — the live agent of that name is answered as it is (reused: true) instead of refusing the clash; dryRun: true answers what the agent would get and which runIn rungs this brain can run, and why not — the dashboard’s New session is the same op; an agent creating one caps it at what it holds), agent_task (ephemeral: create + run + await + auto-delete), agent_call (await a turn on an existing agent; returns on awaiting_input like agent_task), agent_enqueue (fire-and-forget), agent_await (block until terminal or a chosen status), agent_stop, agent_delete, agent_update
  • Answer & escalate — agent_answer (answer a descendant’s pending question; the child resumes with Agent’s answer…) and agent_escalate (hand a descendant’s question to the person now, with a note the card shows above it); agent:execute, descendants only, never grant requests — see Sub-agent questions under HITL
  • Observe — agent_list (the op agent.list: one row per session — or per lineage / run with group — with its role’s feature, its status in words (word: idle, working, needs you, stuck, failed, done — a session in a turn with a request it opened waiting says needs you, never stuck), spend, queued messages, pending requests (the ones waiting on a person) with the oldest named, who holds it if intercepted, its parent and origin; the Boss session and live ones lead every sort; filters by status / word (what the rows say, Stuck included) / source / role / feature / lineage groupKey / name q / run / entity / parentId / one bot’s chat / intercepted / a window, deleted: true for soft-deleted ones; keyset pagination; counts: true — how many rows each word lists under the same filters), agent_summary (the op agent.summary: counts per status and, with words: true, the lineages per word (words), the working ones, the lineages and the intercepted ones, the window’s sessions active and started, failed and waiting with what agents spent beside the window before, every figure narrowed to one role with role, and with by: 'role' each role’s sessions and newest activity), agent_get (the op agent.get, by id or name: the row with its status in words, model, grant, spend, context fill and reap time, plus what it is doing now — current: lastAssistantText, currentItem, pendingHitl ({ hitlId, kind, questions, deliverAt } of the pending interaction), partialUsage and a stream cursor — the messages scheduled to it and the resource watches it holds), agent_history (the op agent.history: the transcript page by page, of the live conversation, an archived one or a chat episode; a request’s events — its payload and answer — only for a caller holding hitl:read), agent_tail (the op agent.tail: cursor-based projected event forensics), agent_prompt (the exact system and turn prompt a dispatch ran with, and what moved since the one before), agent_export (the whole record as one JSON document, its requests with hitl:read); all the reads are grant-free (runtime:read) — a request’s content is hitl:read’s
  • Name resolution — names are unique per chat scope, not globally: the reads address an agent by id; agent_get({ name }) resolves a chat-originated call to that chat’s agent and refuses an ambiguous global name with the candidates’ ids instead of picking one
  • Stuck — a working session with no activity for its role’s threshold reads stuck: engine 600 s → constitution/MANIFEST.yaml sessions.stuckAfterSeconds → a role’s own sessions: { stuckAfterSeconds }; observation only
  • A turn a deploy cut off continues — the engine resumes it on the same session with a note of what died with the process (harness subagents, tool calls in flight) and which sub-agents still live, at most sessions.continueAfterRestart times (engine 3 → MANIFEST → role; 0 = never), then ends it interrupted and says so in the chat; brain-sync holds a push that would deploy while a turn runs, up to brainSync.deployHoldMinutes (60); a turn card the restart left closes at the turn’s end
  • MCP agent resources — omnislash://agent/{id}/status and omnislash://agent/{id}/output expose the same reads as MCP resources, scoped to the caller’s spawn family (the created_by tree: its root and every live descendant — a parent sees its children, a child its parent and siblings)
• Agent Grouping (groupKey) — every agent row carries a lineage key so a planner that ran fifty times reads as one agent, not fifty impostors
  • Lineage rule — rows under one key must be a time-series of one logical agent (at most one live at a time); canonical shape prefix:instance (hb:<id>, hook:<id>, chat:<deliveryKey>, thread:<deliveryKey>:<root>, wf:<taskRunId>:<slug>), with deliberately coarse buckets allowed for disposable machinery
  • Optional with a safe default — omitting groupKey makes the agent its own lineage (groupKey = name); at least one of name / groupKey must be given, each deriving the other, and a forgotten key costs an extra row rather than a hidden agent
  • Orthogonal to role — one group can contain sessions of different roles, and a role can evolve inside a group
  • Not the spawn family — a child spawned through agent_create / agent_task is its own lineage, so a live parent never disappears behind its running child; who spawned whom is created_by, and the family (MCP resource scope, retention) is that tree
  • Per-instance meta — agents.meta JSONB replaces the dropped agent_boss_runs and heartbeat_runs tables (meta.boss, meta.heartbeat), with a partial unique index on meta->'boss'->>'status' enforcing the single-active-boss invariant
• Agent Retention & Reaping — a periodic sweep in the pipelines service (6 h) soft-deletes idle transient agents and hard-deletes expired rows
  • agentRetention.ttlHours — inactivity TTL against updatedAt, which auto-bumps on every status transition / inbox push / heartbeat, so an active chat never expires
  • Shape-aware deletion — headless hb: / hook: tick rows and ended boss rows are hard-deleted without a soft-delete phase (no undo UX to preserve); everything else soft-deletes first and stays readable until reap
  • Retention follows the spawn tree — an idle child whose parent row is gone or soft-deleted is transient too, so a persistent child of a heartbeat tick or a thread agent goes with it rather than living forever
  • A watching agent is waiting, not idle — an agent holding a resource watch (a subscription to the events of an external resource, e.g. a PR it opened) is exempt from both the soft-delete and the reap, however long it stays silent; every watch carries its own expiry, so the exemption is bounded, and deleting the agent removes its watches with it
  • The agent row owns its history — agent_conversations.agent_id is an FK with ON DELETE CASCADE, so a soft delete keeps the whole transcript readable while a hard reap takes the agent’s conversations, their conversation_events and their hitl_interactions with it. Grants minted from those approvals survive (capability_grants.hitl_id is ON DELETE SET NULL) — a retention sweep must not silently revoke an authorization
  • Pending cards are closed before the row is destroyed — a DELETE cannot run a lifecycle, so the sweep scans the expiring ids, has the HITL gateway drive every pending interaction under their conversations cancelled with a durable reason (the owner’s card finalizes as ”🗑 Agent removed”, a coalesced row’s joiners get their fan-out, a pending interception row hands its workflow run back), and only then deletes by id. A card never vanishes without a verdict, and an unanswered card is never an immortality token — the row is reaped either way
  • Sandbox-aware — the sweep runs where $RUNS_ROOT is mounted so a reaped agent’s checkout is actually removed, backed by a durable filesystem sweeper for orphan directories
• Attachments End-to-End — files (photos, audio, documents) flow from any ingress → blob storage → agent → dashboard conversation, with one canonical persistence type
  • Two types, one boundary — MediaAttachment is transport, AttachmentRef {blobRef, mime?, filename?} is persistence; toAttachmentRefs converts once in AgentRun.begin() and nothing downstream sees the transport shape (its inverse fromAttachmentRefs sits beside it, for replaying a persisted turn)
  • Clean content — the DB column holds exactly what the user typed; attachments live in metadata, so analytics never has to regex an “Attached files:” splice out
  • Transit splice, not storage splice — a CLI dispatch appends absolute file paths to the prompt at the subprocess boundary, and the cross-harness handoff serializer rebuilds the same format from metadata
  • API multipart with history round-trip — every prior user message with attachments is rebuilt as multipart UserContent, not just the current turn; local:// refs are read from disk, external URLs are handed to the SDK
  • Blob storage abstraction — BlobStorageRouter routes by scheme with a content-addressed local provider; resolveLocalBlobRef canonicalizes and contains every ref at each trust boundary (ingress, egress, retrieve)
  • file_send — the tool an agent uses to send a file back; it blocks until the document is actually delivered and returns its messageId, so a failed delivery is a failed tool call

Models & Model Routing

• ModelRef Grammar — one closed-format string names an agent’s model everywhere: the create wizard, /model, role frontmatter, models.json chains and the agents.model_ref column
• model_update (config:write) — writes constitution/models.json from its sections (models, roleAliases, apiChains, cliChains; a section left out and any other top-level key are kept), refused as invalid when the file would not load as the runtime loads it (schema, @<effort> suffixes, case-only key collisions), and as refused when an existing model name — a role, an alias or cli:<role> — resolves onto a Codex / OpenCode harness it did not reach before (an alias re-aimed or added over a role, a chain gaining a step, an API chain removed so the bare role falls through to its CLI chain), which keeps its own tools whatever a role’s grant says — that write is model_widen (role:widen, a person approves); D30-shaped. The dashboard’s Models page calls the same op, and on that refusal shows it to the person and saves through model_widen only on their yes
  • Shapes — bare CLI harness (claude, codex, opencode, fake), harness-through-router (claude:openrouter:x-ai/grok-4.1, claude:vercel:anthropic/claude-opus-5), API provider+model (openai:gpt-4o, vercel:anthropic/claude-opus-5), role word (smart, fast, smartest, cli:smart), literal fallover chain (claude@high,codex@medium), each step optionally suffixed @<effort>
  • An aggregator name means two things, and position decides which — vercel:anthropic/claude-opus-5 is an API step (we dial the gateway ourselves), claude:vercel:anthropic/claude-opus-5 is a CLI step routed through it; the middle segment is only ever read as a router
  • AgentRef canonical form — readonly [Step, ...Step[]]; a single ref is a chain of length 1, so nothing downstream has a “with-failover” special case
  • harness ≠ provider — a CLI step carries a harness field (the subprocess wrapper), an API step carries a provider field (the AI SDK slug); the two are never overloaded onto one name
  • Closed-world, case-insensitive parse — structural segments fold to lowercase and the model tail passes verbatim; every name must be a known harness, provider, router, role or alias, otherwise parseAgentRef throws at parse with the expected forms and a did-you-mean hint, so nothing silently parses as a nonexistent role
  • Chain rules — same-mode only, all-concrete, roles forbidden inside a literal chain (roles are themselves named chains); chains are stored comma-separated in the same single column
  • toDispatchableModelRef — the availability gate left after parse (provider env keys present, router env keys present, chain non-empty), kept separate from the grammar gate
• Catalogue and provider reads (since 1.24.0) — model_read_file (config:read) is models.json as model_update takes it (every section, the sha a commit passes as expectedSha); model_summary (config:read) says which step of each API chain (smart) and CLI chain (cli:smart) served the turns over a window (default 7d) — each step’s turns and share by the model that finished them, the turns of the chain’s roles that ended off it (otherTurns) and the fallbacks taken, with the note that a model in two chains counts in each; provider_list (runtime:read) is every LLM provider now — key set or not, its circuit read live (open while it blocks calls, with when it lets one through; half-open past that), its models’ calls in the current minute against their rate limit — plus every other circuit breaker (tools, memory embeddings) and each API chain with the steps an open circuit holds; provider_get({ id }) adds the chains through it in words, its spend and turns over a window, the fallbacks taken from it and its key in the credential inventory (no latency or error rate: nothing durable records them); provider_history pages the circuit-breaker, fallback and auth-issue events, one provider’s with provider. The dashboard’s Models and Providers pages read the same ops
• Model Registry (models.json) — the brain-owned catalogue of models, roles and chains the engine reads for every API dispatch
  • ModelEntry — id (provider:model), label, providerLabel, optional hidden, optional rateLimit.rpm, required contextWindowTokens, optional pricing (per-1M input/output/cacheRead/cacheCreation, optional cacheCreation1h — the 1-hour cache write rate, 2× input on Anthropic — or per-image), optional default reasoningEffort, optional timeoutMs (the brain tier of the per-attempt budget — declare it for a model whose first output legitimately arrives late; floored at 1 000 so a seconds-shaped typo fails loudly instead of aborting every call to that model)
  • roleAliases / apiChains / cliChains — role names map to alias targets or to ordered fallover chains (API entries may carry an @<effort> suffix, validated at load); role names are case-insensitive with a fail-fast collision check
  • Availability filtering — API chain steps whose provider has no configured key are dropped at load, while the declared role vocabulary stays unfiltered so the parser still recognizes the name
  • One error voice, three surfaces — parseModelsFile produces the same actionable message for the loader throw, the Models file doctor check (which fails on the real schema, not a shape guess) and the dashboard models editor
  • content-keyed cache — the file is read on every accessor and re-parsed only when its bytes differ, so editing models does not need a restart
• Role-Based Fallover Chains — a role word resolves to an ordered list of concrete models and the engine walks it on failure
  • API chains (tryChain) — advance on a failover-worthy error, throw on a non-failover error, at the last step, or when the caller’s AbortSignal has fired (decided by the signal, never by the error’s shape — a cancelled caller gets their own reason back, and the call’s rate-limit hold and retry backoff end with it); onExecuted records which model actually served, onFallback fires on every transition
  • CLI chains (cliTryChain) — iterate harness steps behind a circuit breaker, drop sessionId on every failover step, and hand the next harness a trace handoff file
  • Failover classification — timeouts, rate limits, circuit-open, 401–403, 429, 5xx, 404/410 and network errors are failover-worthy; 400 (schema/validation) and abort are rethrown raw
  • model.rerouted telemetry — carries fromModel, toModel (absent = chain exhausted, no retry follows), reason (failed / circuit_open) and the actual triggering error (absent on a circuit-open skip)
  • A dead credential reaches a person, and is fixable where it lands — CliAuthIssueNotifier (chat-core) subscribes to agent:auth_issue and posts to the status surface as a notice about the model’s credentials (one message however many agents trip over it, repeats folded, said again after notify.remindAfterHours); a CLI step’s notice carries a Sign in button into the in-chat sign-in below and names the dashboard-terminal login and omnislash auth-agents <harness> --force as alternatives; an API step’s (and a key-authenticated harness’s — OpenCode) remedy is its provider key, billing_failed offers none
  • A fallover reaches the user who was waiting on it — both modes ring agent:fallback from their dispatch strategy (makeFallbackEmitter), and ModelFallbackNotifier (chat-core) posts a standalone chat message naming the transition, the reason (failed / circuit_open) and the provider’s own error, into the run’s OWN surface (status surface for a run with no chat) as a notice — on a run’s chat about the agent and its transition, on status about the model, so one outage is one message whichever heartbeat agents hit it — the live status card shows the same transition for the seconds before the next tool overwrites its action slot, so it is not a record of anything
  • Bare role resolves API-first, then CLI — cli:<role> is the explicit disambiguator
• Reasoning Effort — one 5-level scale (minimal | low | medium | high | xhigh) expressed in the same ref grammar and mapped per provider
  • Per-step suffix — claude:fable@high, openai:gpt-5.2@low, smart@high, claude@high,codex@medium; split on the last @, case-folded, closed-world (a typo throws at parse)
  • Precedence, per mode — CLI: opts.cli.reasoningEffort → the step’s ref effort → harness default; API: the step’s ref/chain-entry effort → the role-step default → ModelEntry.reasoningEffort → provider default
  • Provider mapping — Anthropic API → thinking.budgetTokens (2k/5k/10k/30k/60k), OpenAI and OpenRouter → reasoning_effort (all five, normalized per routed provider), Codex → modelReasoningEffort, Claude CLI → SDK effort with minimal clamped to low, nvidia / OpenCode / fake → ignored
  • Vercel is mapped by the model’s vendor, not the provider — the native gateway forwards provider options under the real vendor’s key, so vercel:anthropic/… takes a thinking budget and vercel:openai/… takes reasoning_effort; any other gateway vendor ignores effort, like nvidia
  • Applied per step, not per call — the fragment is injected into that step’s own doGenerate / doStream, so every fallback step runs with its own effort
• LLM Provider Factory — lazy factory for AI SDK models wrapped in a ChainModel that drives the resilience pipeline on every call
  • Three resolution modes — model(role) (config chain), model('provider:model') (single-step, no failover), chain([steps]) (explicit ordered list); all three return the same shape
  • Supported providers — openai, anthropic, openrouter, nvidia (with an optional custom base URL) and vercel (Vercel AI Gateway, AI_GATEWAY_API_KEY), each keyed to its required env var; the set is declared once and consumed exhaustively, so a provider cannot be half-registered
  • Two aggregators, one shape — openrouter: and vercel: both front many vendors as provider:vendor/model, which is what makes a cross-gateway failover chain possible: the same frontier model behind two independent intermediaries, each with its own circuit breaker
  • Gateway slugs are NOT a prefix swap — the vendor/model FORM matches but the vendor slugs differ for OSS models (mistralai/ ↔ mistral/, z-ai/ ↔ zai/, qwen/ ↔ alibaba/); only anthropic/, openai/, google/ and nvidia/ are identical. A twin is two independent models.json entries — verify against GET https://ai-gateway.vercel.sh/v1/models (open, no auth)
  • Price the twins identically — a bare-model cost lookup resolves duplicate model tails by declaration order, so twins with different rates can bill one gateway at the other’s price; an entry with no pricing block silently gets a single retry and no cost at all
  • Observability hooks — executedModelId after each settle, onFallback and onRetry wired into model.rerouted / runtime.retry stream events
• Adaptive Rate Limiting & Circuit Breaking — every model call runs through a per-step resilience wrapper before it reaches the provider
  • Distributed circuit breaker — Redis-backed with atomic Lua scripts, so when one process detects a provider is down, bot, worker, pipelines and MCP all bypass it during the cooldown; openUntil accepts an explicit provider reset time and never shortens an existing window
  • Per-model rate limits — rateLimit.rpm from models.json is enforced proactively via the shared RateLimiterPort under category llm:{provider}:{model} (a Redis limiter in production, so the budget is deployment-wide)
  • Pricing-driven retry budget — 3 retries under $3/1M combined, 2 under $10, 1 at or above $10 or when pricing is unknown
  • Per-attempt timeout, three tiers — call site (ModelOptions.timeoutMs) → the model’s own timeoutMs in models.json → the 15 s engine default, resolved per chain STEP so a fallback model is measured against its own latency; background callers like the memory-ops worker take a long timeout and a single attempt instead of holding a serialized queue
  • The abandoned generation is cancelled — the deadline fires a per-attempt AbortSignal, joined to the caller’s own cancellation and forwarded to the provider request, so a timed-out generation stops instead of streaming on unread and billed (once per timeout, plus once per retry)
  • Cancelling ends the waiting too — /stop, a closed chat or an abandoned planning session also cuts short the pauses a call takes on its own (the proactive rate-limit hold, up to 60 s before a request even exists, and the retry backoff), and stops the chain where it stands instead of spending the remaining providers on an answer nobody is waiting for
• Routers for CLI Agents — reach an aggregator’s whole catalog through any CLI harness (claude:openrouter:x-ai/grok-4.1, codex:vercel:openai/gpt-5.3-codex), with the router a closed set in MODEL_ROUTERS (openrouter, vercel) and the whole triple stored in the single model_ref column
  • Endpoints are brain-tunable — each router’s Anthropic-protocol and OpenAI-protocol roots come from env vars with engine defaults (OPENROUTER_*_BASE_URL, AI_GATEWAY_*_BASE_URL), so a router can be repointed at your own proxy without an engine release
  • A missing router key degrades, it does not crash — a cliChains step whose router key is unset is dropped when the chain expands, omnislash doctor fails the role that depends on it, and setting a model ref to such a step is refused at edit time naming the exact variable
  • Routed turns do not inherit your direct keys — a routed Claude turn blanks ANTHROPIC_API_KEY for its subprocess and a routed Codex turn replaces OPENAI_API_KEY with the router credential, so a key you set for something else can neither hijack routed traffic nor leak to the aggregator
• Usage & Cost Accounting — usage is derived from the spend ledger (usage_records, below), never from a denormalized column, so it survives /clear, a compaction and the agent’s reap
  • Per-model segments — one segment per model/provider combo carrying inputTokens, outputTokens, cacheReadInputTokens, cacheCreationInputTokens, reasoningTokens, costUsd, provider, optional router, webSearchRequests
  • Billing type — metered (real money) vs subscription (phantom cost) with the plan recorded (max, pro, chatgpt:plus, …); the two are reported apart and never summed. A CLI login’s subscription stays subscription after its session expires — metered means a paid key or a router, never a dead login
  • A Claude turn costs its own calls — each turn records the API calls it made (main thread and harness subagents), priced from constitution/models.json (an anthropic:<id> entry with pricing) or else the engine’s Anthropic list prices, never the Claude CLI’s running total for the resumed session; the CLI’s own compaction summary and helper calls are not counted; doctor Model prices names a model neither prices
  • CLI billing keys on the OAuth session, not the access token — a run that starts mid-refresh is still billed to the subscription, from one shared credential parser
  • Cost math — calculateSegmentCost bills cache reads at the cacheRead rate with a fallback to the input price, bills the reported 1h share of cache writes at cacheCreation1h (falling back to cacheCreation) — Claude CLI and Anthropic API turns report the 1h / 5m split — suffix-matches unknown model ids, and returns undefined for image-priced models
  • Context snapshot vs cost sum — usage.context is the LAST step’s prompt-side tokens (the turn’s real context size); the segment sum is a cost quantity ≈ steps × context and must never be shown as context; usage.firstCall is the FIRST step’s (on a fresh session, the whole prefix as the model received it)
  • Per-harness usage adaptation — Claude reports per-step BetaUsage deduped by message id with a cache-creation TTL split and a context window; Codex is turn-total spend (cached_input_tokens pre-deducted, reasoning_output_tokens passed through) with the context snapshot read from the thread’s rollout file (its newest token_count, compactions the turn made emitted as compact events); OpenCode synthesizes both from per-step accumulation
  • Lifetime vs last-run — an agent’s lifetime usage and its /stats turn counters sum every priced turn it ever ran; “what did the last run cost” is its newest finished turn on the ledger; a workflow task’s usage is every turn its agent ran while the task was running (a retry and a recovery turn included); a run’s cost is every turn that ran inside it — its tasks’, their sub-agents’ and a turn that finished after a cancel — so it can exceed what its task rows add up to
  • Spend answers for agents (usage_*, capability usage:read) — the ledger read back as five tools, the same answers the Cost page draws: usage_summary (totals vs the window before, month to date with its projection, what caching saved), usage_breakdown (spend grouped by up to five dims — role, entity with its feature, agent, conversation, execution, kind of agent, requester, row kind, run status, eval outcome, model, provider, router, plan, billing — top-N plus other), usage_trend (per hour / day / week / month, zero-filled, with the window before and a split by any dim; a window of more than 1000 buckets is refused with the finest bucket that fits), usage_heatmap (hour × weekday, a dense grid) and usage_tools (calls per tool name — which tools a role really uses). usage_breakdown also groups by trigger (what started the run: cron, event, manual, agent, parent, chat — a turn outside any run is chat), and a row grouped by a run dim (entity, feature, execution, trigger) says how many of its runs succeeded and the cost per succeeded run; usage_summary answers the window’s costPerSuccessUsd; usage_trend takes unit: "per_run" (its split rows per run too) and marks its spike buckets (markers); usage_summary and usage_heatmap take a filter too. The window is the one shape every period read takes — window (1h, 24h, today, yesterday, 7d, 30d, 90d, mtd, all) or wall-clock from / to (YYYY-MM-DDTHH:mm) with an optional tz, converted in the brain’s timezone (or tz) by the database; a filter narrows to a feature, an entity, a role, an execution (a workflow run’s older turns included, through its tasks’ windows), a model…; each answer says when retention reaped part of its window (coverage)
  • Execution cost — every run, pipeline invocation, heartbeat tick and hook fire carries cost_usd: each priced turn that runs inside it (sub-agents included) adds its cost the moment it finalizes, even after the execution ended, and a replayed finalize adds nothing; null means nothing in it was priced, never $0. The eval cost_usd metric reads the same ledger
  • Spend ledger that outlives the agent — every priced turn segment (its terminal, or the HITL pause that split it) is also one row of omnislash.usage_records: typed rollups (metered vs subscription cost, input / output / cache-read / cache-write / reasoning tokens, web searches, the dominant model) computed once from its segments, the segments themselves, calls per tool name, and who it was for — the role it ran as, the requester, the surface, the execution it ran inside (the tick, fire or run — a sub-agent’s spend counts toward its parent’s execution and entity), the scenario / heartbeat / hook it served, the agent and its kind. No foreign keys, so an agent’s reap (which takes its transcript) and a compaction (which deletes the turn.completed rows it folds) leave the spend in place; written once per segment by the agent runtime’s finalize, so a replayed finalize counts nothing twice. Kept usage.retentionDays in constitution/MANIFEST.yaml (default 365, 0 = forever), reaped by the agent-retention sweep; read it with the usage_* tools (below) or db_query (omnislash.usage_records). History: the migration that creates it prices every turn the transcript still holds, and pipelines re-checks the last day at boot and every 6 h (the turns the previous version priced during a deploy, and a ledger write that failed — healed within that day, lost after it)
  • External spend from a pipeline — recordSpend(ctx, { service, costUsd, billing?, units? }) (pipeline SDK) books money a pipeline paid outside any agent turn — a metered API it called itself — as a kind: 'external' ledger row attributed to the invocation (execution, scenario, requester), so the run’s cost_usd and every spend reader count it beside agent turns; a journaled step whose row id derives from the invocation’s deterministic random, so a replay or a retried write records it once (pipelines.md)
• Money budgets with a hard stop — USD ceilings on METERED spend (cost_usd_metered; subscription never counts), checked at every agent turn’s admission; a spent budget refuses the turn before any model call and asks a person on a card — budgets.md
  • Three scopes, three windows — brain (day / month), scenario (run / day / month, sub-agents included), role (day / month, every agent of the role together — a role in a switched-off feature is under the MANIFEST default); calendar windows in locale.timezone
  • Seam — engine every limit null → MANIFEST budget.{brain,scenario,role} → a scenario’s or role’s budget: frontmatter, folded per window; null overrides the default below (resolveBudgetLimits, @omnislash-ai/config/spend-budget)
  • One gate — the agent VO’s prepare-params sums every applicable budget in one ledger query (readBudgetWindows); a refused turn ends failed, errorCategory: 'budget_refused' (BUDGET_REFUSED — recognised by the category, never the message; distinct from budget_exceeded, a CLI turn that ran past its own cli.maxBudgetUsd), execution error_class budget_refused
  • Consumers — a workflow task refusal parks the run awaiting_retry keeping completed tasks; safeRunAgent returns the failed result to pipeline code; chat, heartbeat and hook turns end failed and the next one re-asks
  • Incident card — HITL approval, producer budget, one per (scope, window, windowKey) to the default HITL chat, expiring at a day / month window’s end; +50% / ×2 or a replied amount raise THAT window only (omnislash.budget_raises); Cancel keeps it stopped (a turn an owner waits on — chat, dashboard or MCP — asks again); human responders only
  • Writes split by who may lift a ceiling — budget_update (config:write) lowers or adds a limit on MANIFEST or one scenario / role and refuses a raise or removal; budget_widen (budget:widen, restricted, a person approves) is the same write without the refusal; budget_raise (budget:widen) adds USD to the current window of one budget and re-drives the runs it stopped, with no agent turn needed. manifest_update refuses the budget section and the role_* writes a budget key. The dashboard binds all three
  • budget_status (runtime:read, op budget.status) — every limited scope with its spend, effective limit, raises and the card that speaks for it (pending / cancelled)
  • Loop cannot move a ceiling — budget is a measurement block: a loop proposal touching it is refused, and loop.budget (the loop’s own per-run allowance) stays a separate ceiling

Agent Isolation & Execution Context

• RunIn Execution Ladder — one per-agent execution-context vocabulary, live | clone | sandbox, monotonic (live ⊂ clone (+git) ⊂ sandbox (+bwrap)), with the same name on every layer
  • live (default) — the agent works directly in the live brain checkout and the brain-sync daemon commits and pushes its writes to the G-set; no git push needed
  • clone — its own git clone --shared with a pushable remote and no jail, forced regardless of isolation.enabled; this is what lets a live-brain agent delegate a durable edit of a cold file (CLAUDE.md, omnislash.config.ts, tools/, db/) to a sub-agent that commits and opens a PR
  • sandbox — the same clone plus a bubblewrap jail; persisting it requires project-level isolation.enabled (a hard write-gate), and a purely per-dispatch sandbox on an isolation-off brain degrades to clone with a warning
  • Three declaration levels — AgentSpec.runIn in *.heartbeat.md / *.hook.md frontmatter (the only durable place for row-per-fire agents), the persisted agents.run_in row default, and a per-dispatch AgentRunOptions.runIn override for one turn
  • Who can set it — the Telegram creation wizard and the dashboard’s New session dialog both render all three rungs through one resolveRunInAvailability() (available rungs enabled, unavailable ones explained — the dashboard through agent.create’s dry run), and agent_create / agent_task / agent_update / agent_call / agent_enqueue take the same vocabulary
  • Doctor check Agent runIn — reads the same oracle the create UI does: fail for sandbox declared on a brain with isolation off (a row-per-fire tick would never mint its row at all), warn for silent degradations (clone/sandbox with no baseline, dev-gated sandbox, an inert runIn on a scenario block)
  • Degrade, never throw — a forced clone/sandbox with no baseline falls back to live rather than failing the run
• Per-Scope Sandbox Checkouts — git clone --shared from a shared baseline gives each run or agent its own full checkout: own .git/index, refs/, HEAD, stash and working tree, with objects shared through git alternates
  • Two scopes — run (a workflow run, always cloned when a baseline exists, so parallel runs and PR-finalizer pushes get a private branch) and agent (standalone chat/dev, cloned per the run_in ladder), both through one resolveSandboxRepoPath
  • The owning run owns the turn’s cwd — a turn carrying the run’s auth.runId attaches to that run’s checkout (attachRunCheckout, attach-only — the run’s setup is the sole creator); every other turn resolves the agent’s own context, so neither side’s WIP leaks into the other. Mode-independent: an API turn’s file tools are rooted at the same attached tree
  • Path derived, never stored — agents.repo holds a repo name (two engine-internal writers still pass a path; packages/infra/CLAUDE.md scopes them), so the path is derived per dispatch: only the worker needs $RUNS_ROOT, no cross-pod path-equality contract, agent creation stays a single INSERT
  • Truthful prompt — the resolver returns the branch the checkout is really on, so the injected git-awareness block either says “the daemon syncs your writes” (live brain) or names the actual branch to commit && push; a non-git path renders no block at all.
  • A clone knows its own age — the ## Environment section of a clone/sandbox run carries a Checkout: line naming the baseline commit the tree was cut from (sha + committer date) and the instant brain-sync last fetched the baseline; “unknown” is stated, never omitted, when the baseline carries no fetch stamp. All three facts are captured once at clone time and never move for the checkout’s life (the agent’s commits move HEAD, not origin/HEAD; the fetch stamp is copied into the clone’s .git/), so the environment section’s hash stays put and it is not re-sent per turn. The fetch instant is what tells a quiet window from a stalled daemon — a tip date alone cannot
  • Resume reuses the tree — an existing checkout is reused whatever branch the work moved it to (detached HEAD included, reported as no branch); wiped and re-cloned only when the directory is not a git checkout at all, or when the caller mints a fresh branch per attempt and asks for it (onExisting: 'recreate' — the cycle’s revert, where an existing tree is the crashed attempt’s wreckage, not its WIP)
  • Cleanup waits for reap — a checkout is removed only after the agent subprocess is confirmed dead (terminal row after SIGKILL + stream drain), so a live delete can never rip a clone out from under an in-flight git push
  • Pinned to a commit — a workflow run carrying content_sha (set only by the loop’s pre-merge check) gets its checkout detached at that commit — fetched from origin when the baseline has not seen it — and every turn attached to it reads the scenario, blueprint, role (body and frontmatter — model, grant), prompt templates and skills from that checkout while everything that is not content (judge, memory, config, grants) stays live; such a run is a replay that asks nobody and has no side effects: its input is validated against the blueprint at that commit (no pre-run input card), its task agents ask no questions, a gated capability fails it, scoped hooks and the PR finalizer are skipped, its agents hold no git credential, no remediation agent is spawned for it and it cannot be retried; it is loop-launched (AuthContext.loopLaunched, derived from its loop creator and inherited by every sub-agent, child pipeline and MCP session): every engine tool that writes, launches or sends runs dry, and the run page marks it replay · dry-run
  • Sweepers — a race-tolerant 15-minute filesystem sweep with a DB re-check before every rm -rf (7-day TTL, ENOENT-tolerant, also collecting orphan and loop checkouts), plus the retention sweep’s synchronous per-agent cleanup
• Claude builtins follow the grant — a Claude turn is handed only the harness built-ins its capabilities name (HARNESS_BUILTINS: read, plan and ToolSearch always; file:write → edits, engineering:execute → Bash and its background control, research:read → web, harness:subagent → Agent, the harness’s own in-turn subagents — not engine agents, which are agent_task under agent:execute), as an allowlist, confined or not — the capabilities being the role’s plus its live grants’, so an approved engineering:execute hands a shell to the next step; Cron* and other runtime-foreign built-ins are off for every role, and a renamed built-in on a newer CLI is warned at session start
• Per-turn path confinement — AgentRunOptions.confinement carries three repo-relative glob lists (editable / denied / unreadable) that each CLI harness compiles, with the agent’s grant (no file:write ⇒ nothing editable), into its native permission surface; never persisted
  • One glob dialect — @omnislash-ai/types/path-glob matches every repo-relative path rule in the engine: ** across segments, */? within one, a trailing / for a directory, a bare path for an exact match; no negation, braces or character classes
• Bubblewrap Jail — a per-subprocess bwrap wrapper that lives exactly from spawn to exit, giving mount / PID / IPC namespaces and --die-with-parent
  • Same absolute paths inside and out — the run checkout is bound at /app/brain, baseline objects at their own path (so alternates resolve), so every absolute path in a tool call works transparently
  • $ARTIFACTS_ROOT is a sibling, not a subtree — engine-runtime artifacts are bound RW at the same absolute path outside /app/brain, because a checkout bind over them made every task with outputArtifacts fail with Missing output artifacts
  • Live skills bound read-only as a sibling — the catalogue is rendered outside the jail from the live tree and the same path is bound in, so the agent never gets ENOENT on a path its own system prompt named, and git status in the checkout stays clean
  • Session stores bound RW — ~/.claude (with CLAUDE_CONFIG_DIR), ~/.codex, and OpenCode’s four XDG directories, because pause ≡ process death and every resume spawns a fresh subprocess that must find its session file
  • Per-harness shims — one shim script per harness (CliWrapperKind = Exclude<CliHarness,'fake'>) with a shared sourced body, baked into the image; adding a harness breaks the type until its shim exists, so a new harness cannot silently become unsandboxed
  • Activated by cwd, not a global flag — the isolation env is stamped only when the agent’s repo is under $RUNS_ROOT, so planners, hooks, recovery and live agents pass straight through the shim
  • Container prerequisites — apparmor=unconfined + seccomp=unconfined + systempaths=unconfined are all required (the third for the fresh /proc mount), and omnislash doctor probes with the shim’s real flag combination rather than a weaker smoke test that gave false greens
  • Threat model is write isolation, not read isolation — the jail prevents accidental cross-run damage between trusted agents; the host filesystem stays readable and the network stays open by design
• Brain Baseline — a dedicated brain_baseline volume holds the full brain clone that every sandbox alternates against, with exactly one writer
  • Single writer — the brain-sync daemon bootstraps it (git clone $BRAIN_GIT_REMOTE) and refreshes it in its steady-state loop; workers mount it read-only, so a clone-path race between replicas is structurally impossible
  • Fetch plus local fast-forward — the refresh moves refs/heads/<default> onto refs/remotes/origin/<default> as well, because git clone --local reads local branches and a fetch-only baseline pinned every sandbox to the bootstrap commit forever
  • git gc forbidden — gc.auto=0 is set unconditionally on every bootstrap, since unreachable objects may be referenced by live clones through alternates; disk reclamation is a full rebuild in a maintenance window
  • Fetch stamp — every clean fetchBaseline (and the bootstrap clone) writes .git/omnislash-baseline-fetched-at in the baseline; a sandbox copies it at clone time and reports it in its prompt, so a run can see that the daemon has been silent rather than infer it from a file that “looks truncated”
• Git Write-Back — commits leave a sandbox over the network, never through a shared filesystem
  • Push to the real origin — the per-clone origin is rewritten to the baseline’s upstream (a local clone would otherwise point at the read-only baseline path), so an agent’s git push origin <branch> lands on GitHub; re-applied on every prepare, not only after the clone, so a baseline whose remote changed propagates into long-lived agent checkouts that already exist
  • Auth is two lanes, chosen per spawn — a GitHub checkout is served by an hour-long installation token delivered through the environment (GH_TOKEN for gh, GIT_CONFIG_* carrying http.<remote>.extraHeader for git); everything the App cannot serve (non-GitHub remotes, ssh URLs — D7) falls back to the host key. ~/.gitconfig is bound read-only into the container and the jail either way, ~/.ssh only into the container — the jail masks it with a tmpfs unless that spawn picked the ssh lane
  • What the mask buys — not isolation from engine credentials (agents still hold DATABASE_URL and CONNECTIONS_TOKEN_ENC_KEY by design), but that a non-expiring, account-wide write key stops sitting where a prompt-injected agent could copy it out, replaced by a one-hour token scoped to one repo
  • Committer identity enforced at the boundary — assertGitIdentity (brain-sync’s boot, after the App-derived default has had its chance) fails startup when neither tier produced a pair, and mirrorAuthorToCommitter copies author into committer since git links neither by default
  • Branch naming helpers — sanitized branch fragments and collision-free feature/… names for agent-opened branches
  • gh-backed PR helpers — read a PR’s merge state and changed files by URL (no checkout needed) and close a PR with an explanatory comment
  • Brain history — git_history (runtime:read) lists brain commits newest first — a feature, an entity’s files or paths, bounded by since / until — each tagged person / evolution / brain-sync / engine (filter tags) with its squash-merge PR; paged by cursor
  • One commit whole — git_get_commit — git.get_commit (runtime:read) returns one brain commit’s author, tag, PR, full message and per-file change with line counts and unified diff, scoped like git_history; binary, large or over-budget diffs are named only
• Deploy-Owned GitHub App — the engine can hold its own git identity instead of borrowing the host’s ambient SSH key: a GitHub App is registered through GitHub’s App Manifest flow — started by an agent’s git_request_app card or the dashboard’s Connect GitHub (git.authorize), both handing out the same link — and the App id, slug, client secret, and AES-GCM-sealed private key land in omnislash.git_apps (one row per provider). The PEM never leaves the engine and the tRPC surface exposes only appId/slug/htmlUrl; the manifest’s permission set is a brain-widenable floor (git.appPermissions) and its installability is git.appPublic (default true, so one App can hold installations on several accounts) — both in packages/connections/docs/connections.md § git_apps
  • Agent path — git_overview (runtime:read) reads the App, its installations and, for the brain repo and every attached repo, which lane authenticates it (the App’s token or the ambient GH_TOKEN) and why (ssh-remote, no-app, account-not-installed, repo-not-granted, …) — or lane unknown when the installations could not be read in time (read again before asking for an install). git_request_app (integration:execute) posts ONE card to the default HITL chat whose link takes a person through GitHub’s registration screen and straight on to its install screen (step: 'register'), or to the install screen alone (step: 'install') — register is refused while the registered App works and is installed somewhere, since a replacement drops every installation; the card goes to a person at once (never held for a parent agent), and no agent-facing reading of it carries the link; the card closes itself when GitHub confirms the installation and the agent wakes with the account and repository selection. Every App remedy — credential rows, the merge gate, doctor hints, omnislash git * — names this tool first and the dashboard’s Connections › Repos (/connections/repos) second
  • Installations — a person installs the App on an account or org from GitHub’s own install screen, which is the repository picker — reached from a registration (which always continues there), an agent’s install card, or the dashboard’s Add account (git.authorize({ step: 'install' })); GET /github/install-callback writes omnislash.git_installations from an App-JWT GET /app/installations/{id} read rather than from the redirect query, because a spoofed installation_id is expected there. One App, N accounts — a second org is a second row
  • Installation-token mint — getInstallationToken signs a 10-minute App JWT with the PEM and mints an hour-long token scoped to bare repository names, cached in Redis under git:token:<installation>:<scope> until 5 minutes before expiry and minted under a per-key lock, so N parallel agents cause one GitHub call; the token is handed out as a { username, password } credential pair and never spliced into a remote URL
  • Delivery to git, gh and agents — engine-side git (brain-sync’s brain-repo and attached-repo clone/pull/push, the repo-sync worker, the loop’s gh calls and revert push) and every sandboxed CLI agent resolve the credential from their own remote or checkout origin; it reaches git through GIT_CONFIG_KEY_*/GIT_CONFIG_VALUE_* (appended after any inherited slots, so a compose-level safe.directory=* survives) and gh through GH_TOKEN. A checkout the App cannot serve yields no credential, which is itself the signal that unmasks ~/.ssh in the jail. GH_TOKEN set by hand is the declared fallback lane for a deploy with no App — it needs the App’s own permission set (the list: operations.md § Infisical, GH_TOKEN row), which its Credentials row restates and the doctor’s GitHub merge gate probes for Commit statuses; omnislash doctor → Git identity says which lane is live and whether pullRequest: true can work at all; → Brain git remote says the same for BRAIN_GIT_REMOTE specifically
  • Event receiver — the manifest subscribes the App to every PR, review, review comment, review thread, conversation comment, check run/suite, status, push and issue event (plus the installation* events GitHub sends every App) and points hook_attributes at POST /github/webhook on the webhooks origin. The route is mounted unconditionally (a server-to-server receiver needs neither public origin — GitHub already holds the URL) and gated on nothing but the App’s sealed webhook_secret: X-Hub-Signature-256 is verified as HMAC-SHA256 over the RAW body with timingSafeEqual, and no secret on record means 401 rather than a trusted payload. Each delivery is recorded in the inbound sink as a typed github:<event>.<action> event (flat payload, sender-written text fenced, resource keys github:pr:<owner>/<repo>#<n> and friends, a fork PR’s checks joined to the PR by head SHA, a redelivery deduplicated by its delivery id) and fires hooks like any event — integrations.md § GitHub events. The loop’s merge signal (closed ends its merge wait, auto_merge_disabled turns an armed wait into a human one) and the installation list (suspend / deleted / created) are consumers of the same durable route job
  • Subscription drift is told, not guessed — no GitHub API changes an existing App’s events or permissions, so an App registered with fewer receives fewer until a person edits it. Doctor GitHub App subscription (Infrastructure) compares the App and every installation against the engine’s event set and the resolved permissions (checks: read + issues: read join the floor; git.appPermissions raises levels, the stronger wins) and the webhook URL against this deploy’s, and its hint is the message to forward: the App’s settings page (org- or user-owned as GitHub reports), the levels, the checkboxes by their GitHub labels, then each installation’s page to accept. The worker runs the same check at boot and daily and sends it to the status chat once per distinct drift. What the App CAN change itself — its webhook URL and secret — the worker sets without anyone (at boot and daily, before that check): an App with no secret on the deploy’s side (registered before the manifest carried a webhook, or imported without one) gets a fresh one on both sides, a missing URL is pointed at this deploy’s receiver, and a URL pointing elsewhere is left to its owner
  • Payload retention — a handled GitHub event’s payload is emptied after github.payloadRetentionDays (MANIFEST, engine 30 days); the row, its delivery id and its resource keys stay
  • Missed deliveries recovered from GitHub’s own log — GitHub never retries a failed delivery; every 5 minutes and at boot the worker lists the App’s delivery log back to where it last read (GitHub keeps three days), takes every delivery with no successful attempt (grouped by delivery id — a failed attempt a redelivery then got through is not a candidate) and no row in the inbound sink, and pulls its payload straight from GitHub (App JWT) into the same ingest the receiver uses. Direct, not a redelivery: a redelivery goes back through the ingress that just failed — a rotated secret 401s forever. Doctor GitHub webhook delivery warns when deliveries had to be recovered in the last day (with GitHub’s account of the newest failed attempt: 401, 413, a timeout) when the reconciler has stopped running — quoting the newest failed pass’s own error, so the reason reaches an agent without logs — and when GitHub listed attempts in a shape the engine does not read (skipped one by one, never a failed pass). An App with no webhook has no log at all: that is a recorded reason, not a failing job. Cadence is an engine constant, not a seam
  • Derived PR signals — github:checks.settled, github:pull_request.mergeability — what GitHub never sends: “every check on this head reached an outcome” (one signal per head and outcome set, once ALL of it is terminal; a re-run ending the same way is a new one; a head with no checks at all settles none after a 10-minute grace) and “this PR began / stopped conflicting” (on a transition only — a push to the base that leaves it mergeable wakes nobody). One GraphQL probe per PR reads both (check rollup with per-PR isRequired, mergeability), debounced 30 s after CI activity or a push to the PR, every 5 minutes for watched PRs and on pushes to their repository; recorded through the inbound sink with deterministic keys, so hooks and watches hear them like deliveries — integrations.md § GitHub events
• Multi-Repository Operations — agents work across multiple code repos beyond the brain, with scenario-level repo targeting and clone-on-attach
  • Attached repos are rows, not env — omnislash git attach <owner/repo>, or the Attach button on the dashboard’s Connections › Repos (/connections/repos), writes a code_repos row (slug, remote, installation, optional default branch, sync status); the repo map is read live on every call, so a repo attached at runtime shows up without a restart. D6: attachment is owner data — there is deliberately no repos field in omnislash.config.ts
  • Path resolution — one row works in prod and in local dev: /repos/<slug> if cloned, else a sibling checkout next to the brain root, else /repos/<slug> as the fallback the doctor warns on. The brain checkout is always the first entry of the map
  • Per-repo isolation — a workflow targeting an attached repo gets a per-run sandbox cloned from /repos/<slug>, whose origin is the real upstream, so write-back works exactly as it does for the brain
  • Skills stay out of the tree — skills are delivered to an attached-repo agent as a system-prompt catalogue under the absolute skills root, so git status in a third-party checkout is never dirtied
  • Doctor checks — every resolved repo path is validated on disk (missing = warn), and every scenario agent.repo must name an attached slug or an absolute path (unattached = fail); a DB the doctor cannot reach downgrades both to warn
• Inbound Repo Sync — a repeatable worker keeps /repos/<slug> current, the read-direction counterpart to the write-direction brain-sync daemon
  • Sweep — every REPO_SYNC_INTERVAL_MS (default 5 min, plus a startup kick), always registered, over the code_repos rows; a row whose checkout is missing is cloned first, each repo under a composed abort signal (shutdown or a per-repo operation timeout)
  • Self-heal a wedged checkout — rebase --quit (clears even a corrupted rebase that --abort cannot), hard reset onto the freshly fetched ref, stash clear — so an interrupted sweep cannot freeze a repo forever
  • Snapshot, don’t stash — dirty tracked edits are committed as a repo-sync: snapshot local edits commit (never pushed) and rebased forward, because a conflicted stash pop leaves a half-applied tree the next sweep cannot heal
  • Supervised conflict episodes — a rebase conflict aborts cleanly, warns the status chat once (dedup-keyed per repo), and spawns a non-interactive system:git-conflict-resolver against that repo with a structured report schema, while the sweep holds off the repo for as long as the resolver is busy
  • Episode lifecycle — a resolver past a 15-minute deadline is re-dispatched with restart: true, escalated at attempt 3 and every 10 after, and closed with a ✅ report only when a clean pull verifies it; in-flight resolvers are adopted after a worker restart
• Isolation Configuration — ProjectConfig.isolation { enabled, kind: 'bwrap' } (default off), plus BRAIN_BASELINE / RUNS_ROOT / ARTIFACTS_ROOT env paths that default to temp dirs in dev
  • Mode matrix — in prod a baseline always exists so run-scope always clones; in start it depends on a configured remote; in dev there is no baseline and every rung degrades to the live host tree
  • BRAIN_GIT_REMOTE is boot-validated — required in production and whenever isolation is enabled, so a gitless-agent deployment fails fast instead of silently
  • Persistence horizons — per-run clones, ~/.claude / ~/.codex session stores and the artifacts root live in named volumes or host binds so a HITL pause survives a container restart; the jail’s /tmp is a tmpfs and deliberately does not
• Why not git worktree — worktrees were removed outright: they share .git/objects, refs, stash, gc and prune, so they closed one of eleven real conflict classes while creating the illusion of isolation

Chat & Conversational Surface

• Telegram Bot — Grammy-based bot with commands, wizard flows, inline keyboards and live cards, running N personalities over one chat-core service graph
  • Polling or webhook — N polling runners restarted on unexpected stop, or one server multiplexing N secret webhook paths with TLS behind Caddy; either way allowed_updates is always an explicit list (Telegram persists a previously-set one)
  • Transport resilience — five API transformers, innermost first (a log of every 429 with its retry_after, autoRetry for 429s and 5xx, apiThrottler for rate limits, a log of every chat call slower than 5 s, scrubTokenErrors to keep the bot token out of the error that escapes), an update-dedup high-water mark per bot id (so a restart never reprocesses), and per-chat sequentialization with an explicit OVERTAKE_PREFIXES opt-out for HITL / approval / live-card callbacks that must never queue behind a slow handler
  • Send resilience — an HTML → plain-text → file fallback chain that only walks for format-degradable 400s (a 429, a blocked bot or an unusable chat surfaces directly instead of tripling traffic), plus in-place self-heal for group→supergroup migration and for a deleted forum topic
  • Error handling — Grammy transport errors classified for UI and Sentry, with harmless cases (bot blocked, “message is not modified”) swallowed
• Chat Access Frame — one frame per bot answers four questions about every inbound event — which role serves the chat, who the person is there, when the bot answers, what they may run besides talking — data first (constitution/access.yaml), code over it (bots[].policy); with nothing configured the bot serves only its owners — chat-access.md
  • Tiers ladder — engine default → access.yaml bots.<bot>.default → bots.<bot>.dm | chats."tg:chat:<id>" → policy.chat(), folded field by field by one resolver (context / limit replaced whole); keys are numeric SubjectIds (tg:user:<id>, tg:chat:<id>), a @username is refused with the way out
  • The role belongs to the chat — everyone in a chat talks to one role with that role’s tools and memory; an owner’s DM runs bots[].role, dm.role serves everyone else who may DM the bot, and a group has NO role until its own rule names one (fail-closed: the owner’s role never leaks into a room). chat() never sees the sender, so the role cannot jump between people. Every chat agent row follows its chat’s role on each message; an owner’s own DM keeps its /model tuning
  • A closed set of tiers — owner (global: env owners in TELEGRAM_ALLOWED_IDS, numeric only, plus identities: owner; every command, control buttons, HITL approvals), member (talks through engage, runs the rule’s commands), stranger (no turn; lines reach the context block only under context.from: all), blocked (dropped, not even logged). Resolved owner → on-behalf → identities → rule.members (owners · listed · everyone · { memberOf } checked through the platform) → sender(), which cannot mint an owner
  • A member’s turn is capped — the rule’s capabilities (capability ids, '*' = no ceiling; engine default none, so a member talks but uses no tool until a rule names it; sender() may name one person’s) is the ceiling of a non-owner’s turn: role ∪ live grants ∩ ceiling, a '*' role becoming the ceiling. Tools, Claude builtins, the capabilities prompt module, an agent the turn spawns or hands work to, a prompt it schedules all stay under it; hitl_request_grant refuses above it and points at access_widen; owners are never capped; a Secretary counterpart reads the bot’s default ⊕ dm ceiling
  • One gate, before the log — accessMiddleware decides before observe: blocked dropped, strangers refused (a DM gets the rule’s decline), a member’s closed command refused privately, and the turn carries the sender’s tier and capability ceiling as auth.access. A message sent on behalf of a chat (an anonymous admin, a linked channel’s auto-forward, a post as a channel) is that chat’s: it gets the tier identities gives the chat’s tg:chat:<id> (list your own journal channel as owner), else what members gives anyone unlisted — a stranger under owners / listed, a member under everyone — no admin rights needed
  • Unknown groups ask — my_chat_member records every chat a bot sits in (bot_chats, plus each bot’s getMe() health in bot_profiles); a group no rule serves follows unknownChats: ask (default — an owner card: Serve… → role → who may talk / Only me / Leave, answered in Telegram), ignore or leave. A group upgraded to a supergroup keeps its rule, its memberOf references and any open card under the new id
  • Menus and refusals follow the rules — command menus are synced per scope (group defaults, each served group’s commands, the full list for owners) on start and on every access.yaml change; a refusal is an ephemeral message only the person sees (an alert or their DM as fallback), never a public post
  • Per-member turn budget — limit.turnsPerHour (default 30, 0 = none) counts the turns the bot actually takes, per member and chat; over it the bot stays silent and says so privately once an hour; owners and Secretary counterparts are never limited
  • Hot, validated, explained by the same code — the file is re-read on every event; a file naming an unknown bot, role, command or capability fails the boot, a later invalid edit is logged and the last valid version stays in force. The runtime gate, the access_explain tool and the dashboard simulator all call one resolver (resolveChatAccess), so an explanation cannot drift from behavior
  • Business updates authorize on the connection — an owner connecting the bot is the grant (a non-owner’s connection is recorded but never served, checked on every message); a counterpart is a member of the counterpart’s routed role, outside access.yaml
• Messenger-Agnostic Chat Core — five ports define the whole contract between the chat framework and a platform adapter, so the Telegram app only routes updates
  • Ports — MessengerPort (reply / edit / delete / sendFile, optional sendVoice / sendSticker / setReaction / createThread / probeThread), StreamUIPort (status presentation, final answer delivery, typing presence), ChatStatePort (active agent + delivery cursor + binding reverse lookups), ChatAgentPort, MediaSourceResolver
  • Optional members are a capability probe — every decorator in the chain must delegate them and throw when the inner adapter lacks one, never silently no-op (the regression that made every voice_send fail)
  • Container lifecycle — createChatServices() wires the whole graph with ordered start() / stop() hooks (delivery recovery first, notification worker only after card handlers are subscribed, content hot-reload in every mode including production)
• Chat Command Surface — the /commands a chat user can run, most of them platform-agnostic in chat-core
  • Agent control — /agents (panel, with ✏️ Edit / Chat / Last Output / Stop / Clear / Compact / Delete per agent), /chat (back to the bot’s own agent), /clear, /compact, /model, /settings, /steer, /stop, /context, /stats
  • Loop — /idea <entity> <text> (post a hypothesis into an entity’s ideas bucket, with a Withdraw button while it is queued — see Evaluation & Self-Evolving)
  • Execution — /run (run list, adhoc and repo plans, in-place execution), /plan (adhoc plan wizard), /p (Restate pipeline runner), /hb (recent heartbeat runs and detail)
  • Platform-native — /start (menu + deep links), /restart (self-restart with a persisted ”⏳ Restarting…” message edited to ”✅ Restarted” on boot), /help (what the person may run where they are), /connect, /tg_auth, /tg_accounts, /tg_default, /tg_remove, /logs (owner-only recent logs, read from Loki across every service this deployment ships — requires the monitoring stack), /artifacts
• Per-chat Configuration — per-chat active agent, agent override and model override, backed by an LRU cache over a DB-persisted chat_state row keyed by (chat_id, bot_id)
  • Chat agent bootstrap — each chat lazily resolves its own chat agent (one row per chat and bot, looked up by persona name), so nova in three chats is three independent agents; its role is the chat’s route — the chief in an owner’s DM with the chief’s bot, the counterpart’s secretary role in a business chat, a rule’s role in a group
  • Free-form model switching — /model shows the current ref, the models.json entries and the ref formats with a Cancel button, then consumes the next message as the new ref, rejecting typos at parse with did-you-mean hints
• Editing an Agent in Words — ✏️ Edit on an agent card lists every editable field with its current value and one or two example values, then takes a free-form sentence in any language and applies it
  • One declared field set — AGENT_EDITABLE_FIELDS (name, displayName, groupKey, role, modelRef, repo, runIn, capabilities, systemPrompt) is what the chat hint prints, what the parsing LLM chooses from, and what the dashboard form renders, so no surface can offer a field the applier would refuse
  • Model maps, code decides — the value-role model only emits (field, value) string pairs against the brain’s real roles / repos / models; typing, list splitting, clearing rules and the closed-world runIn check are a pure toAgentPatch, and every value is re-validated at apply time — a hallucinated repo ends as “Unknown repo: X. Available: …”, never as a write
  • Reports what moved, not what was asked — the confirmation lists the fields whose stored value actually changed (a restated value reads as “nothing changed”), plus anything the parser could not map, and a session reset when the CLI harness changed
  • One-shot flow — a parse failure does not re-arm, so an armed edit never eats an unrelated chat message; Cancel retires the hint card in place
• Chat Settings — /settings shows the chat’s switches as one card of checkbox buttons; a press flips one and re-renders the card in place. Per (chat, bot), shared by the chat’s topics and threads; an owner’s press only; none in business chats
  • Voice replies (off by default) — every answer also arrives as a voice note right after its text: the engine synthesizes the answer’s speakable part (markdown dropped, code blocks and bare URLs left to the text) in the answering role’s voice (its speech: block, else the brain’s speech.chain), shows “recording a voice message” meanwhile, and sends it silently, threaded like the answer. The agent is not involved. Refused with the reason when no speech provider is configured; a failed synthesis drops that one voice note — see voice
  • Interrupt mode (off by default) — the dispatch mode below
• Chat Dispatch Modes — a per-chat switch (/settings → Interrupt mode) decides what a message sent mid-turn does
  • queue (default) — the message waits in the durable inbox and merges into the follow-up turn; the live status card is the queue’s acknowledgement, with previews and per-entry cancel buttons rather than a standalone “Queued.” message that would hang stale
  • interrupt — a new message preempts the in-progress turn (steer); the preempted turn’s message stays claimed and re-serves merged behind the interrupter
  • Mode-independent steering — a native reply to the live status card, or /steer <text>, always preempts; bare /steer flushes the queued inbox now
  • /stop — snapshots and clears the inbox first (so queued pokes cannot restart the agent), then cancels the live run, and replaces the status card with a stop record echoing what was dropped
• Live Turn Controls — the streaming status card is the control surface, carrying a derived control row recomputed at every transition
  • Buttons — ⏹ Stop, ⚡ Run queue now, and one full-width ✕ cancel per queued entry labelled with that message’s preview
  • Queue line — a live count plus previews, excluding the live expectation’s own entry (after a roll-over the head is being served, not waiting)
  • ⏸ pause anchor — when the bound agent suspends on a HITL question the card says what the chat is waiting for, so a queue behind a missed question card does not look like a dead bot
  • Durable actions, in-memory rendering — the buttons act on VO + pending_inputs state, so a post-restart orphan card still works; a card-identity guard makes a tap on a stale card act on nothing (never a Stop of a run it never belonged to) and retires its keyboard
• Chat Turn Lifecycle — ChatTurn is the single owner of chat-side turn liveness, with liveness derived from a phase enum rather than stored flags
  • Dispatch identity — the chat pre-mints the mailbox entry id before opening the turn, and every stream event and terminal carries the ids the agent turn serves, so acceptance is one positive membership rule (serves) rather than status, arrival order or an exclusion slot
  • What that rule drops by construction — a preempted turn’s trailing content, cancelled terminals any number of steers deep, a turn cancelled before its first delivered event, pre-restart leftovers on a fresh process, and programmatic turns on the same agent
  • Transitions — open (idempotent re-begin for a steer, with DM card reuse and group card re-threading), expectQueued (FIFO of queued follow-ups), dropQueued, resume (HITL continuation on a live turn only, safe to call twice; an idle turn declines so the turn’s answer is recovered from durable rows), the question-context handoff, the preempted-turn settlement, finalize, close with roll-over, closeStopped, abandon on dispatch failure
  • Zombie-turn reconciliation — a live turn whose expected entry no terminal will ever announce is detected from an unserved terminal plus a durable mailbox check (past a 30 s mint grace) and torn down or rolled over, so a frozen card with a growing queue line cannot accumulate silently
  • Single ordered channel — teardown rides only the agent’s serial stream consumer; the turn holds no raw pub/sub bell subscription, because that raced ahead of in-flight deltas and wiped turn state before the answer was read
• Final-Answer Delivery — one answer per turn: the last non-empty assistant text block the turn wrote, across HITL pauses, delivered once at its terminal; earlier blocks are narration and never become messages
  • Narration on the status card — assistant text deltas (like reasoning) feed the card’s thought slot while the turn runs, newest text winning, so the person watches the work without a message per block
  • A new, notifying message — at completion the answer (plus attachments) is sent fresh, threaded under the trigger in groups, and only then is the status card deleted; edits do not notify, so the card is never edited into the answer
  • Terminals — completed delivers the answer; failed delivers it followed by the ⚠️ line and [🔄 Retry] under the usual audience rules; cancelled / interrupted deliver nothing
  • Pauses — a HITL pause does not cut the answer: a resumed run that writes no text keeps the text written before the pause, so an approval mid-turn never swallows the answer
  • Question context — the text written before a question tool call (or, with none, the agent’s last reasoning) is taken on the ordered stream at that call and delivered ahead of the question card, to the card’s destination (the owner’s DM for a Secretary-Mode chat); the card waits for it at most 10 s and is never withheld; recovery after a restart never sends it a second time
  • Preempted turns — a steer or interrupt-mode message sets the running turn’s answer aside; that turn’s own terminal decides the owner: cancelled → delivered live under its own trigger, completed first → the durable settlement delivers it — one owner per answer
  • Reroute restart — a model.rerouted with a next step clears the pending answer (deduped per turnId/from/to), because the fallback model writes its own
  • Why — the CLI harnesses already treat the final message as the turn’s answer and between-tool text as narration; delivering every block fought that contract and shipped duplicate answers and trailing “saved a note” messages that no prompt rule reliably prevented. OpenClaw-style bridges converged on the same final-only + progress-draft split
• Status Presenter — one status message per turn with a slot model, throttling and back-pressure
  • Two slots — a thought slot (reasoning, rendered incrementally by a safe-prefix markdown renderer that holds back unclosed markers) and an action slot (tool calls, results, tasks, errors, retries, fallbacks, plan updates, warnings, progress)
  • Single-writer funnel — one private issue path owns every presentStatus call and every message-id assignment, with catch-up flushes for concurrent updates and a drain-then-issue path for explicit content
  • Generation fence — bumped on acquire/release/detach/delete so a slow edit from a finished turn cannot resurrect a stale message id; a gone message clears the cached id and the next present sends fresh
  • Throttling — a per-surface edit interval owned by the messenger adapter (Telegram: 1 s in a DM, 3 s in a group) with errors, retries, fallbacks and plan updates bypassing it
• Agent-Output Rendering — LLM text is treated as markdown intent and converted per surface at one chokepoint, never escaped into HTML
  • markdown-it IR pipeline — a real parser (not regexes) converts markdown to Telegram-safe HTML, including code fences, inline code spans and tables rendered as HTML or <pre> under a per-port width budget
  • Message splitting and chunking — HTML-aware splitting at the 4096-char limit (<pre>-safe) plus markdown-aware chunking on paragraph / newline / sentence boundaries with fence safety
  • One producer for verbatim agent output — renderAgentOutput emits platform-neutral markdown with an optional escaped label prefix and no truncation, locked by a class test; genuinely plain text (errors, ids, names) stays HTML-escaped
• Reaction Status Channel — the turn lifecycle stamps a reaction on the user’s own message: 👀 when the dispatch lands in the inbox (visible even while queued), then the terminal verdict — the 👀 retracted on success, 👾 on failure, cleared on cancel or interrupt (the message is already in the agent’s history)
  • Success retracts rather than stamps — a 👍 per handled message would mark the chat unread and queue a reaction badge the user has to dismiss, so the happy path ends with no reaction at all; a brain that wants the stamp sets reactions: { ok: '👍' }
  • Brain-overridable — defineProject({ reactions: { seen?, ok?, failed? } }), validated at startup against the platform’s fixed reaction vocabulary; null on any verdict means “clear, don’t stamp”
  • Presence-class traffic — sent through the un-throttled API and best-effort, so a platform without reactions simply no-ops
• Failed-Turn Retry — a failed turn’s ⚠️ bubble carries [🔄 Retry], so an outage someone has since fixed (expired CLI credentials, a rate-limited provider) costs one tap instead of re-typing the message
  • Replayed from the timeline, not a side store — the turn’s input row is persisted before the run executes, so the exact text and attachments survive a turn that emitted nothing; there is no TTL and no “retry data expired”, and the button still works after a restart
  • Verbatim replay — the stored assembled prompt is re-sent as-is (re-assembling would change what the agent is asked; that is what typing again is for)
  • Proven target — the agent comes from the surface’s lane and the turn is then looked up inside that agent’s conversation, so a stale button can never replay at the wrong agent; the button retires on tap, which makes it single-use
  • Only turns a human dispatched — a failed schedule/heartbeat gets its provenance header but no button: replaying it would re-send a note the agent wrote to itself as if the human said it, under the tapper’s chat auth instead of the scope its grants hang off
• Typing Presence — turn-scoped activity indicator: on at open and at a HITL resume, off at full teardown and across a HITL pause (when the human is the one expected to type), with the platform owning the keepalive cadence
• Chat Delivery Durability — a finished chat turn is guaranteed to deliver its answer, reconciled from the database rather than from the stream
  • Durable per-chat cursor — chat_state.delivered_event_id over the global conversation_events id space, advanced by exactly one owner per (terminal × chat) and stamped to the high-water mark whenever a chat’s active agent changes (so a newly bound agent’s history is never owed)
  • Four writers, one core — the live completion path, the unserved-terminal settlement, the cross-surface mirror and the boot recovery all run the same reconciliation: each completed turn’s answer — its last assistant message, the same rule as the live path — re-sent as a fresh notifying message, a trailing failed turn given the live path’s failed-turn message — its answer so far plus the ⚠️ line (with the same [🔄 Retry], on human-dispatched turns), cancelled/interrupted turns swept silently so a restart never resurrects a steered-away answer
  • Boot recovery — every chat with an active agent is reconciled before any subscription; a busy agent is armed (rebind) rather than settled, and re-read afterwards so a terminal that landed inside the subscribe-floor window is settled immediately instead of waiting for the next boot
  • Unserved-terminal settlement — a chat-dispatched, final terminal observed on its origin chat settles that chat from durable rows without touching a live steered turn, which also delivers the steer-vs-completion race’s answer live
  • At-least-once by construction — the cursor advances only after the send attempt, so a crash costs one duplicate, never a lost answer
• Cross-Surface Mirroring — a conversation continued on the dashboard shows up in the bound Telegram chats — the user’s messages and each turn’s answer (its last assistant message, never the narration before it) — delivered silently (no push) so the user is not re-pinged
  • Origin skip — the chat that originated the turn is served with a notification by the live path; every other bound chat gets the silent mirror
  • Non-completed terminals sweep — a failed or cancelled turn’s rows advance the cursor without delivery, so they cannot resurface later as a stale prefix
• Live Status Cards — real-time, debounced cards in chat for workflow runs, planning sessions and pipeline runs
  • LiveCardMessenger — 1.5 s debounce, immediate render for terminal statuses that preempts a live debounce timer, terminal stickiness (a finished card can never revert to its live keyboard), fire-once finalize on every path, Redis + DB message-id storage, per-run surface caching, and a bounded dead-entity set
  • Workflow card — rebuilt from the run detail on every lifecycle event, with a status-derived keyboard (Plan / Stop / Pause / Resume / Result / Retry / Recover)
  • Planning and pipeline cards — the same pattern with their own domain events, plus a single terminal-clamped status owner and a per-port character budget for pipelines
  • HITL cards — human-blocking interactions are rendered by a separate notifier off the HITL event bus rather than through stream callbacks, with cross-channel finalize so a dashboard- or MCP-resolved card loses its stale buttons in Telegram too
  • Recovery notice — one plain-text outcome message for a recovery that never spawned an agent to speak for itself, routed to the run’s surface or the status chat
• Engagement — the frame’s “when does the bot answer” for an admitted member / owner: the rule’s engage (addressed · always · never), with policy.engage() over it — one function from normalized signals to a verdict, resolved once per message and cached — engagement.md
  • Signals — surface, self and roster (persona names), scope, chat (tg:chat:<id>), chatTitle, sender (tg:user:<id>, username, name), tier, the resolved rule, memberStatus(), addressed, automaticForward, senderChat, text, media / replyToMedia kinds, threadRoot identity, messageId, and onBehalf for business messages; every field is a primitive or an opaque id, so no platform type ever reaches a brain policy
  • Verdict — undefined (defer to the rule’s engage), a boolean shorthand, or a decision carrying steer (an instruction injected into the turn), toolContext (a deterministic engine-opaque bag carried verbatim to every tool call of that turn, never through the model), agent: 'chat' | 'thread', context.thread (row cap or off), context.peers (other bots’ replies shown or hidden) and transcribe.autoPost
  • Per-chat knobs in the rule — the chat rule’s agent / context (thread rows, peers, from) apply to every turn the bot engages there, the rule’s own gate included, a decision’s own value winning field by field; bots[].engagement / bots[].engaged are retired and fail the load with their new home
  • Engine defaults per scope — DM always engages, a served group only when addressed with a 10-row context block of members’ and owners’ lines that includes the brain’s other bots’ replies, a channel-discussion thread or forum topic the same plus the root and a per-thread agent, a business chat always
  • Hard pre-dispatch gate — an ignore short-circuits before any cost: no typing indicator, no media download, no agent run
• Situational Envelope — every agent chat turn leads with a one-line context header rendered from Surface + Actor + inbound metadata (chat title, chatId, thread root identity, sender with their numeric id and tier, timestamp in the brain’s timezone), framed as context rather than instruction
  • Scope-shaped contents — the platform always leads; DM adds sender and time; a group adds title and chatId; a thread adds its root (“thread of channel post «Journal» #817”); sender_chat messages render as the channel or an anonymous admin
  • Dashboard chat envelope — a dashboard chat turn is prefixed with renderDashboardEnvelope() ([Context: Dashboard · <time>])
  • Directly actionable — because it names chatId and the thread root, the MTProto history tools are usable with no guessing
  • Turn assembly order — envelope → thread/chat context block → steer directive → reply-context quote → user text
• Chat Log (observe ≠ engage) — every delivered GROUP message a served chat admits is recorded after the access gate and before the engagement gate, as pure refs with zero extra API calls; a stranger’s line is recorded only where the rule says context.from: all, a blocked person’s never
  • What is stored — identity (chat_id, bot_id, message_id), raw thread root, author snapshot (or senderChat) with the author’s tier, text/caption, media download handles, reply-to, sent-at; edits re-observe onto the same key so the log never serves pre-edit text; DMs are not logged (business chats are, under their owner’s lane)
  • Outbound write-back — the bot’s own sends are logged by decorators around the messenger and stream-UI ports (the Bot API never echoes them), self-limiting in SQL to chats that already have observed inbound rows
  • Room view across a brain’s bots — Telegram never delivers one bot’s messages to another, so in a supergroup the context block reads every bot lane of the brain, deduplicated by message id: a persona summoned mid-thread sees the other personas’ replies under their names; context.peers: false hides them and the header says how many, from whom
  • Delta-based context injection, never a sliding window — the first turn in a scope gets the last K rows (a thread topped by its root), afterwards only rows the agent’s session has not seen, tracked by a per-(chat, bot, thread, agent) watermark advanced only at a served terminal, with an honesty line when rows are capped
  • Untrusted text is blockquote-fenced per line — a per-line > prefix rather than an open/close fence, because a multi-line message could otherwise forge one of the engine’s own turn blocks
  • Lazy transcripts — the thread root is transcribed at assembly time through the shared transcript cache; every other row is cache-read-only and renders an explicit “untranscribed” hint instead
  • Retention and honest limits — a 6-hourly reaper (30-day age cut, 500-row per-chat cap); the log holds only what the Bot API delivered, and a doctor check warns when privacy mode hides plain-group messages
• Thread-Scoped Agents — a discussion thread or forum topic gets its own agent with a fresh session on its first engaged turn
  • Same persona, fresh session — a per-thread lineage key and deterministic slug, warm-started from the chat log (root post plus the last K rows) rather than amnesiac, with brain memory still shared
  • Thread-first resolution — an existing binding wins regardless of scope; an unbound thread with effective scope thread bootstraps and binds (per-thread promise dedup in-process, cross-process races resolved by adoption); a dead binding is dropped in place
  • Auto-reaped — idle thread agents soft-delete under the same retention TTL and their bindings are swept in the same pass
• Topic-per-Agent — Forum Topics as Delivery Lanes — a Telegram forum topic binds to an agent (agent_topics), so inside a bound topic the thread is the agent selection and commands become thread-scoped
  • Parallel lanes — each topic has its own live turn, status card, queue and durable delivery cursor, so two agents stream simultaneously in two topics of one chat
  • Lane-stamped Surface — one coordinate (threadId + threadKind: 'topic' | 'root') makes every Surface-keyed mechanism work unchanged: turn registry partitioning, delivery gating, HITL card routing, stream rebinding, cursor fan-out
  • Wire translation in one place — topic lanes set message_thread_id, root lanes reply to the root message (the only way to address a non-forum thread), and a deleted topic degrades to the chat’s main stream
  • Callback mirroring — a card tap inside a discussion thread operates that thread’s turn and agent, not the chat’s
• Multi-bot per brain — one brain exposes N Telegram bot personalities, each with its own token and persona, sharing memory, skills, grants and database
  • Opt-in bots[] — each declaration carries name (the persona and chat-agent slug), tokenEnv (the env-var name, never the secret), optional role (what an owner’s DM runs; the one bot that omits it is the chief’s bot and runs chief.role — two bots omitting it fail the load), policy (the chat frame’s code tier) and secretary; omitting bots synthesizes exactly today’s single-bot behaviour
  • bots: [] — no Telegram surface at all — an explicit empty roster derives services.bot false (an enabled one throws), keeps the TELEGRAM_* trio optional and drops Grafana’s telegram-ops contact point; hasTelegramSurface(config) is the one predicate consumers ask
  • botId derived from the token prefix — computable in every process with no API call, so out-of-band delivery recovers the owning bot from a stored Actor
  • deliveryKey = chatId:botId — the chokepoint for all per-(chat, bot) state (chat state PK, Redis reply/HITL/grant/schedule keys, one live turn per personality), because in a DM the chat id is identical across every bot
  • The chief’s bot carries system messages — engine-internal, actor-less deliveries (the status chat, the owner channel and declared channels, HITL cards with no chat of their own, a scenario surface that names no bot, restart DMs) go through the chief’s bot — the bot whose role is chief.role — whatever token var it reads; per-entity routing is untouched (an interactive HITL card answers in its own chat, a scenario surface naming a bot keeps it). What an agent of a persona role (a role a bot runs that is not the chief’s) writes to the primary owner with no chat — the owner channel, headless voice_send, an approval card with no chat — is sent by that role’s own bot into its DM, so a persona’s heartbeat speaks as the persona and the owner’s reply reaches it. A brain whose bots all run other roles has no carrier for them: they are dropped while the personas keep chatting, and the doctor’s System messages check fails
  • Deterministic nobody-or-exactly-one ambient response — a group rule’s default gate still engages only when addressed; a brain that wants ambient chatter elects by persona name over the stable roster, evaluated independently per bot with no shared state
• Secretary Mode (Telegram Business) — a secretary: true bot answers the connected owner’s chosen private chats as the owner, with zero bot chrome visible to the counterpart; only an owner may connect it — anyone else’s connection is never served
  • Owner-scoped identity — businessOwnerId is a namespace coordinate on the Surface (in the delivery key, kept by chat-scope, compared by equality), so state survives disconnect, reconnect and credential rotation; the connection id is a credential resolved at send time, never identity
  • Owner-as-principal auth — business updates authorize on the connection rather than the chat frame, and the owner is the auth subject while the actual sender stays on the Actor
  • Rights gating with rotation-safe retry — a pre-check blocks before any API call, an invalid connection refreshes the credential for the next send and degrades this one (never a wholesale retry that would re-deliver already-sent parts), and a paused or inactive peer degrades in place with no retry storm
  • Owner-manual-reply back-off signal — the owner’s own messages are recorded into the bound conversation without a turn and stamp last_owner_reply_at, which a bot’s engage() reads as onBehalf.ownerRepliedAt
  • Zero chrome, silent failures — status cards, placeholders, keyboards, typing and reactions are all suppressed for business surfaces; a failed turn produces no ⚠️ bubble for the counterpart and exactly one plain failure note in the owner’s control DM
  • HITL rerouted to the owner’s DM — approval and question cards land on the owner’s control surface rather than in the counterpart’s chat
  • Business context bridge — a business-shaped situational envelope (as-owner framing, counterpart identity, owner’s last manual reply), chat-log lanes keyed by owner, and an owner MTProto bridge that auto-resolves the pool account matching the owner so counterpart history predating the connection is readable — under a blast-radius guard that refuses account-wide tools and any chat but the counterpart’s
  • One role per counterpart — a business chat id routes to its own role, so memory line, capabilities, model and persona body are all per person; the bot’s own role is the stranger’s, and a business row follows its route on every message — role switched, model and capability overrides cleared, so the role file alone decides
• Media & Attachment Ingress — photos, voice, video, video notes, animations, audio and documents flow from chat into the agent pipeline
  • Token-safe download — the file is fetched to the artifacts tree under a bounded fetch (timeout + byte cap, atomic write); the bot token never leaves the download helper, where it used to be spliced into prompts and third-party requests as a live credential
  • Voice replaces text, never duplicates it — all transcribable attachments of a turn are transcribed eagerly through the transcript cache and become the message text, and a pure-audio attachment is then dropped so the agent is not handed the same content twice
  • Albums — a media group arriving as N separate updates is collected behind a short debounce and folded into one turn on the carrier (which holds the caption, mention and reply)
  • Replied-to media — resolved into a separate field so reply context is never confused with what the user sent: transcribable media goes into the quote block, images and documents are appended and marked as coming from the reply, and a resolution failure degrades instead of dropping the turn
  • A file the bot cannot download never costs the message — past Telegram’s 20 MB getFile cap the ref rides into the turn instead of the bytes and the engaged turn re-fetches it through the media-source seam (MTProto); what no transport reaches is described in the turn text with its reason
  • Reply quoting — a reply always carries what it points at, including the bot’s own messages (marked as such), using the user-selected quote fragment when the platform provides one; the block is per-line fenced and transcripts of replied-to media are deliberately uncapped
  • MediaSourceResolver — resolves a media ref back into bytes, trying the Bot API first and falling back to MTProto download for files past the 20 MB cap. One seam for everyone who needs oversized media: the engaged turn’s own carrier attachments, the lazy thread-root transcription and the ambient auto-post
  • Ambient auto-post — when the brain enables it and the bot does not engage, an observed voice or video is transcribed and the transcript posted as a threaded reply, making a channel searchable text for free
• Outbound Delivery with Real Acknowledgement — out-of-band sends go through the ui-notifications queue, the only place a messenger exists for tool processes
  • Every branch returns the refs it produced — producers that must not lie about delivery (file_send, voice_send, notification_send and brain-tool context.notify) await the job and report the delivered message id, so a failed delivery is a failed tool call rather than a confident “sent” with nothing in the chat
  • Flood waits are waited out, not retried into — when the platform refuses a send for flood control (Telegram 429 retry_after), the job is deferred by exactly that long without spending a retry attempt and lands after the ban; an awaiting tool past its 60 s wait answers UNCONFIRMED with the next attempt’s time — do not re-send
  • Voice messages — synthesized server-side in the calling role’s voice (since 1.24.0: a role’s speech: block replaces the brain’s speech.chain whole, hot through brain-sync, written by role_update) and delivered as native voice bubbles via MessengerPort.sendVoice; a headless caller falls back to the primary owner’s DM resolved at enqueue
  • Stickers are turn-surface only — platform file ids are bot-scoped, so the branch reads the raw surface and throws rather than substituting a default persona, and the schema rejects a sticker aimed at a named channel or sent from a headless turn
• In-Chat Introspection — /context and /stats, the in-chat twins of the dashboard’s context meter and cost page
  • /context — what fills the active agent’s window right now: size vs the model’s window, the role’s policy marks and the distance to auto-compact, cache-prefix stability, session-envelope state (three distinct states, CLI only), conversation size, the tool / skill / MCP surface, the memory budget and the envelope the next turn would carry
  • Read-only by construction — it reports persisted state instead of rebuilding the prompt, so it neither clones a repo nor runs memory recall, and every reported surface goes through the same resolution the runtime uses rather than a card-local re-derivation
  • Mode-honest tool counts — in prompt · callable · caps on both modes: the grant selects the CLI agent’s MCP catalog exactly as it selects the API agent’s tool set, and in prompt is what of it rides turn 1 (on API what the role’s toolLoading keeps out of tool_search; on CLI what the harness keeps out of its search tool)
  • /stats — turns split into failed vs deliberately stopped, tokens, metered and subscription cost reported apart (never summed, sub-cent charges kept to four decimals), per-model breakdown, top tools, and a queue count that excludes the running turn’s claimed entries
  • Instruction and outcome are both reported — the header’s modelRef is what the agent was ASKED to run (a role, a chain, an effort suffix) and names no concrete model; /stats’ Last line and /context’ served by name what ANSWERED, taken from the last turn’s cost segments (the heaviest model once ABANDONED chain steps are excluded and the rest summed per model — otherwise a fallover’s burned spend, or a model that ran three times, would outvote the model that answered). /context takes its window denominator from that model rather than from the ref, since the snapshot it divides was taken by the model that ran
  • /stats reports fallovers as their own line — count plus the newest transition (from → to or chain exhausted), its reason and the provider’s own error, read back from the model.rerouted rows already in the ledger; silent on an agent whose chain has never moved
  • No invented denominators — a runtime that reports no context window gets a bare token count, never a made-up percentage; a turn counter counts turns still in context, and lifetime spend survives /clear while /context resets
• Wizard Flow DSL — a declarative, type-safe DSL for multi-step wizards in Grammy bots (steps, buttons, text input, multi-select, submit handlers) with Redis-backed payload storage
  • Shipped flows — agent creation (role, model, repo, runIn rung selector, free-form model input), adhoc plan authoring, the pipeline runner wizard, and blueprint run selection
  • One role list, one visible answer — the wizard’s role step and the context-budget report read listAgentRoles() (brain *.agent.md personas, role-*.md files and engine constants, unioned, identity only), the dashboard’s agent picker reads role.list (offering only the roles feature.list reports on), and every agent card prints the role its row carries
• /p — Run any Restate pipeline handler from chat — a thin chat layer over the same trigger helper the CLI and the MCP tool use
  • Direct grammar — /p <pipelineId> <handler> [<key>] [<json-input>], validated against the live Restate admin catalogue with the available names listed on a miss
  • Confirmation policy — read-only handlers (Restate-Shared, or a conventional read-prefix name) fire immediately; everything else gets a confirm card whose pending args are parked in Redis for 10 minutes and consumed atomically so a double-tap cannot fire twice
  • Wizard mode — bare /p walks pipeline → handler (badged by kind) → key (auto-skipped for stateless services) → input (auto-skipped for input-less handlers) → confirm
  • Surface propagation — the triggering chat rides along, so HITL approvals and notifications from the pipeline land back in the same chat
• Artifact Browser — /artifacts gives interactive file and folder browsing in chat with pagination and drill-down, and downloads
• Widgets — interactive pages for a person (since 1.25.0) — an agent, pipeline or hook opens a page for the person in its chat: a launch message whose button opens it as a Telegram Mini App, talking both ways while it is open — widgets.md
  • Widget files — features/<f>/<name>.widget.html (read verbatim, never env-rendered) + an optional strict <name>.widget.yml (policy tier, the tools allowlist — HITL-gated, agent-control and checkout (shell, files) tools refused —, csp origins, device permissions, inputSchema), addressed ui://<feature>/<name>; an HTML publication opens ad hoc as artifact:<id>, and a page not written yet as a draft (widget_create({ draft: { path } }) — a file in the agent’s artifacts directory up to 8 MiB, or inline HTML — stored as the widget’s own, no publication; a spec that widens the page needs feature:write); doctor Brain entities names a file or spec that does not load and a spec with no page
  • Ops — widget_create (this chat, a declared channel or one person’s private chat with the bot only, so no approval; any chat the bot talks in), widget_update (state snapshot with a version compare-and-set, or a named event — every push numbered, replayable — and publications granted to the open page), widget_close, widget_get, widget_list, widget_widen (more people, behind a person’s approval); an agent acts on its own widgets, the brain caps how many it keeps open (the oldest closes superseded)
  • Durable — the widget is a row with an explicit open/closed lifecycle and a TTL closed by a sweep; its launch message is posted and taken down by the bot process
  • Submits are inbound events — source widget, event widget:submitted, resource widget:<id>: hooks, resource watches and pipelines read them like any delivery; the person is verified and recorded by the engine, never taken from the page; one key, one event
  • Policy seam — engine → MANIFEST widgets → the file → the call: lifetime and its cap, launch-data age, delivery and debounce, size caps (state, events, maxMediaBytes per file made for the page), the push record a widget turn carries, submit rate, default audience, where code’s chat lines go (transcript), per-agent cap, retention
  • Turns and pipelines — with deliver: turn a burst of submits comes back to the chat’s agent that opened the widget as one turn, under the opening turn’s ceiling; with deliver: chat a pipeline, a hook or any opener that is not the chat’s agent hands each person’s submits to the agent serving the widget’s chat, as that person; every widget turn carries the record of what moved the page since its previous one — events and media one line each, state replacements collapsed into one line, each naming the tool that pushed — outside the untrusted fence, never the state (the page’s data: widget_get answers it fenced); pipelines get openWidget / updateWidget / closeWidget / widgetEvents (a durable stream of submits)
  • The page is an MCP App — the engine hosts it: a Mini App shell on widgets.<domain> signs the person in with Telegram’s launch data, the page runs in a sandboxed frame on the content origin with no network beyond its spec’s csp, and talks through the page SDK (/sdk/widget.js: input, state, ordered pushes with replay, submit, Telegram’s main/back buttons and haptics) or the official MCP Apps SDK; media grants published files as URLs alive only while the widget is open — at open or to the open page — and voice_render / elevenlabs_sound_effect / image_generate with widget: { widgetId, name } put what they make straight onto the page as the widget’s own file (gone when it closes, never in Artifacts), so no bytes ride a state, a journal or a transcript; without widget an agent gets a file in its artifacts directory
  • Code pushes to its page — every tool body gets context.widgets: push(widgetId, { state?, event?, media?, chat? }, { tx? }) on the tool’s own transaction (commits or rolls back with its writes; state derived under the widget’s lock, so snapshots never land out of order) and page, the widget whose page made the call; a page tool pushes its verdict during the call, a tool an agent calls keeps the page in sync without the agent relaying anything; who may push by caller (a page its widget and same-opener siblings, an agent its own, brain code any, an MCP session its own, the webhook door none); an ack with refusal codes, never a throw for the widget’s condition — widgets.md § 5
  • Chat lines — a push’s chat lines write the page’s session into the chat it was opened from, on the same transaction as the state: the brain’s lines in the bot’s voice, the person’s own words as echo lines quoted and named by the engine; the bot posts them as one silent message per widget run, ahead of any later answer in that chat, at least once; skipped (never refused) for a widget with no chat, a business chat or policy transcript: off; a page message shows as the person’s quote; a reply to the lines reaches the agent fenced as the page’s — widgets.md § 5 “Lines for the chat”
  • Gestures are the person’s — a submit, a page message into the chat (sendMessage) and an allowlisted tool call (callTool, within both the opener’s grant — none once that agent is gone — and the person’s ceiling, never an approval-gated, agent-control or checkout tool; run in the worker for at most the policy’s toolTimeoutSeconds; a failure shows the person only the tool’s own refusal(…), else an engine sentence) run as the verified person, share the per-person rate and land in the action log against the widget; a frame that navigates away from the page ends the session
  • Doctor — Widget hosting (a bot, both origins https, each hostname resolving), Widget browser sign-in (whether links open in a browser, with the BotFather step), Widget tools (every spec’s allowlist against the deployment’s tools), Brain entities (a file or spec that does not load)
  • A HITL card’s page — an approval action with widget, and every input request’s form (the engine’s ui://engine/form by default), open a widget bound to the card that answers it as the person, through the one HITL gateway (an approval’s data held to its responseSchema) and closes when the card is decided anywhere; the engine’s pages ui://engine/form and ui://engine/review (item-by-item approve / reject / edit) open with widget_create too; pipelines pass widget to awaitApproval / requestApproval / requestInput, agents to hitl_request_approval — widgets.md § 12
  • On the dashboard and in MCP Apps clients (since 1.25.0) — the dashboard hosts every widget (its chat panel lists the open pages; a request card’s widget action opens its page), and a turn with no chat that serves the dashboard or an MCP client opens a widget with no chat there; an MCP Apps client (Claude, ChatGPT, VS Code) on the bearer door gets your widget files as ui:// resources shown through their own tools, the page’s calls as app-only tools — widgets.md § 13–14
  • In a browser (since 1.25.0) — a widget’s link opens outside Telegram after a Telegram sign-in (OpenID Connect through one login bot, loginSecretEnv), admitted exactly as inside Telegram plus the chat rule’s browser:; widget_create({ to: 'tg:user:<id>', launch: false }) hands one person a link; widget_list_sessions / widget_revoke_sessions and a block in access.yaml end browser sessions; a HITL card’s page wants a fresh sign-in; doctor Widget browser sign-in gives the owner’s one BotFather step — widgets.md § 15
  • Preview (since 1.25.0) — widget_preview (feature:read) shows the agent a page the way a person will before anyone sees it: a widget file, an engine page, a publication (runtime:read) or a draft not written yet (a file in the agent’s artifacts directory, or { html, spec? } inline — pages up to 8 MiB; a draft that previews opens with widget_create({ draft })), rendered in the real host (the Telegram shell with a recording Telegram.WebApp, or the dashboard frame) under its own CSP in the browser service; screenshots reach the calling model only (modelMedia), a report lists problems first (errors, CSP refusals and stopped requests with the .widget.yml key that allows them, overflow, clipping, tap targets, contrast, dark-theme misses, the inputSchema check), then what the page sent, its state and its accessibility tree; variants (device × theme × host), scripted steps with element shots, mocks for page tools (with the event and state their code would push) and connectDomains (no real tool or network ever runs), a tall page in readable tiles, each screenshot compared with the same agent’s last preview of it; preview unavailable: … without the browser — widgets.md § 16
• Deep Links — /start run_<scenarioId>, /start pipe_<token> (short-lived Redis handle from the run list) and heartbeat detail links open the corresponding view directly
• Chat-Side Reliability Checks — omnislash doctor validates the chat surface itself, speaking with the chief’s bot (the one that carries system messages; System messages fails when there is none): Telegram privacy mode (warns when a plain-group log would be holed), and Telegram chat reachability (probes every TELEGRAM_*_CHAT_ID / TELEGRAM_*_CHANNEL_ID / NOTIFY_<NAME>_CHAT_ID, reporting migrated ids and unreachable chats with the same vocabulary the sender gives up on)

Tools & MCP

• Tool contract — defineTool() / createTool() — one ToolDef shape is the single source of truth for the LLM schema, authorization, UI grouping and routing decisions; createTool adds the Zod schema and a typed execute.

  • Required fields — name, description, schema, risk, providesCapabilities, label, category (the group key brains target in engine-tools.json)
  • Three audience flags, three questions — mcp: false (direct only, e.g. the bash/FS tools), webhook: false (off the HTTP door), agents: false (machine-only — stripped from every agent tool set including '*', and from MCP tools/list)
  • Runtime behavior flags — hitl (tool produces a HITL interaction), requiresHuman (stripped from non-interactive agents), alwaysLoad (the engine tier of eagerness: never deferred on API, _meta['anthropic/alwaysLoad'] on Claude CLI), enabled (default on/off)
  • MCP metadata — annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint) and outputSchema (JSON Schema for result.data, surfaced as structuredContent on success)
  • replay: 'live' | 'dry-run' — what the tool does in an execution the loop launched (a pre-merge replay and everything it spawns): dry-run makes the gateway answer a success marked dryRun without calling execute. Undeclared, an engine tool is live only when annotated readOnlyHint: true (fail closed), and a brain tool is live — its body reads context.auth.loopLaunched itself
  • source attribution — auto-stamped engine / project / integration at registration
  • Per-tool rate limits — rateLimit: { perMinute?, perDay? } enforced by the distributed limiter
  • Description budget 60–300 chars — held by review (expectDescriptionBudget checks a set on demand, with a documented exempt list), because every description is a permanent per-turn tax; three-tier guidance puts post-call prose in the result instead
  • Result contract — { success, data: string } plus optional metadata.attachments (media sent to the person’s chat) / metadata.externalContent and pauseData for HITL tools; helpers success(), failure(), classifiedFailure(code, message, classification)
  • Images for the model, not the person — a tool that declares showsModelMedia: true (and no outputSchema: over MCP a declared one would cost the images) answers modelMedia: [{ type: 'image', mediaType, data, key? }] (base64; png / jpeg / webp / gif; at most 10 images, 5 MB each, 20 MB together — a result past it fails as model_media_limit) shows the calling agent a picture: an API agent reads it as an image part of the tool result (a provider that takes no image in a tool result — OpenRouter, NVIDIA — gets a one-line note instead, per chain step), a CLI agent as an MCP image block. data still says in words what the images show. Only an agent’s call carries them: a pipeline’s callTool, the webhook door and a widget page’s tool call get the result without them, and no transcript, journal or event stores the bytes. Within one turn a later image of the same tool and key replaces an earlier one on the next step (it reads [superseded]); an unkeyed image stays for the turn

• ToolRegistry — one registration point, many read shapes — tools are registered once at startup (never in handlers) and every lookup funnels through one enabled-gate.

  • Two stores — executable tools and metadata-only defs; register, registerDefs, registerProjectTools (auto-stamps source: 'project')
  • Read surfaces — get / has, getDefinitions, getTools, getToolNames, count
  • Capability mapping — getToolNamesByCapabilities (raw match), getCapabilitiesForUI (wizard multiSelect grouped by domain), getCapabilityPlatformMap (planner prompt enrichment)
  • One selection predicate on every delivery — toolRefusal(tool, session, delivery) decides what an agent is offered from its ToolSession (effective grant — the role grant resolved at dispatch, plus the agent’s extras, ∪ live grants — + interactive + memoryEnabled): agents: false and (over MCP) mcp: false excluded, requiresHuman stripped when non-interactive, memory tools refused when the role declares no memory: block (even under '*'), then the grant — '*' everything, otherwise a matching capability; the two capability-less hatches always (AskUserQuestion subject to requiresHuman, hitl_request_grant on every session). toolsFor(session, delivery) serves the API tool set, the CLI MCP catalog, /context and the pricing; ToolsGateway.executeFor refuses every agent call outside it (not_offered, naming the tool’s capabilities and pointing at hitl_request_grant), for MCP, the fake harness and the API executor alike — a CLI role declaring [] sees only the two hatches, exactly as an API role, until an approval widens it
  • Every agent tool is grantable — registering an agent-visible tool with providesCapabilities: [] throws (only AskUserQuestion / hitl_request_grant are capability-less), so no tool is reachable only under '*'
  • callable vs in prompt — isEager(tool, eager) (mcp-wire.ts) is turn-1 eagerness: the alwaysLoad engine tier plus the role’s toolLoading.eager; it never selects a tool, it only decides whether an offered one loads up front, and deferredOnTurnOne applies it per delivery, so the /context report, the pricing, the API tool set and the MCP server agree
  • Deferred tool loading (API) — a role whose deferrable tools (offered, not eager) number more than toolLoading.deferAbove (default 30 — in practice '*' roles) gets only its eager tools plus one tool_search (the AI SDK’s provider-agnostic toolSearch(), so mixed failover chains work); every other offered tool stays callable once a search discovers it. Tuned per brain (MANIFEST.yaml § toolLoading) and per role (toolLoading: frontmatter): eager keeps a role’s hot tools loaded (and marks them alwaysLoad for direct Claude CLI), 0 defers everything not eager, false never defers (a chain of models that cannot drive a search). The step after a discovery re-writes the cached prefix once; the CLI harnesses keep their own deferral. tool_search is a reserved tool name
  • Composed engine surfaces — registerSystemTools, registerSkillTools, registerAgentControlTools, registerBashTools, registerWorkflowEngineTools (plan + schedule + execution + pipeline + eval in one call, mandatory in every tool-executing process), createIntegrationToolRegistry, registerIntegrationKitTools
  • Barrel defs.ts per package — metadata-only defineTool exports for consumers that want the static set without instantiating providers

• ToolsGateway — the single execution path for every tool call — lookup → rate limit → HITL gate → execute → metrics → interceptors, identical for chat, workflow, pipeline, MCP and webhook callers.

  • Distributed rate limiting — Redis-backed RedisRateLimiter keyed by tool category; it fails open on backend trouble (rate_limiter_results_total{result="error"} is the alert signal) so a socket blip never kills an agent turn
  • Classified error envelope — ToolErrorData with code + classification: unknown_tool/not_offered/hitl_config/missing_auth_context/missing_grant/validation_error (permanent) and rate_limit (transient, with retryAfterMs)/execution_error (transient); tool-authored envelopes pass through unchanged
  • Prometheus metrics — tool_calls_total{tool,status,risk}, tool_call_duration_seconds, tool_errors_total, denial recording, with the call source derived from auth (workflow / pipeline / chat / mcp / other)
  • Interceptors — fire-and-forget afterExecute(name, context, result) hooks for usage, logging and analytics; throws are logged and never block the result
  • Replay rail — under auth.loopLaunched a tool that acts on the world is authorized as usual and then not performed ({ success: true, dryRun: true }, no rate-limit spend, no grant consumed); context.notify validates and addresses, then delivers nothing; a HITL ask is refused (loop_launched) because no answer can be dry-run
  • ToolExecutionContext — the gateway is the single injection seam that upgrades a plain ToolContext with notify (channel-addressed delivery for tool bodies, awaits real delivery) and getServiceToken(providerId) (fresh OAuth bearer)
  • Per-call side channels — emitProgress(message) for MCP progress notifications and signal: AbortSignal for client cancellation, plus sessionId, repo and skillEnv
  • Live derived name-sets — hitlToolNames is a getter and the requiresHuman strip-set is computed per invocation, so a hot policy flip can’t leave a HITL tool executing without pausing the run

• Brain-owned tool policy (constitution/engine-tools.json) — the brain enables or disables engine and integration tools without touching engine code, through a layered { default?, categories?, tools? } document resolved most-specific-first.

  • Allowlist and denylist fall out of one mechanism — default: false + named categories/tools is only-mode; bare false entries are except-mode
  • One gate, no “hidden but callable” — ToolRegistry.isEnabled covers listing and resolution, so a disabled tool is rejected by name as unknown_tool on the gateway, MCP and webhook paths
  • Project tools exempt — the brain governs its own registrations in code, so default: false can never lock a brain out of its own tools; keys naming one warn as ineffective
  • Hot reload, and no silent keys — getToolPolicy() is cached and reset by the content watcher; malformed content and a renamed tool key fail fast at load (the error names what the tool became); a tool key no engine or brain tool answers to fails the boot with the nearest real name (logged as an error after a hot reload); an unknown category only warns
  • What the policy took away is visible — ToolRegistry.policyDeniedTools() reports the registered tools the file switches off, split into ones it names and ones that merely fell through "default": false; the doctor’s Tool policy check reads it and stays green, because an allowlist denying things is the allowlist working. Without it a denied tool has no surface at all: the published catalog is the enabled set by construction, so a brain on "default": false silently loses every category the engine adds after its policy file was written

• One naming convention for engine tools and capabilities — every engine tool is <namespace>_<action> (agent_call, file_read, notification_send, email_list), every capability domain singular and spelled as its namespace (db:read, access:widen, artifact:publish). Renames are data, never aliases: RENAMED_TOOLS / RENAMED_CAPABILITIES feed only the rejection text — a load error for engine-tools.json / toolLoading.eager, a refused grant request, unknown_tool naming the replacement — and the doctor’s Tool names / Capability names list every old name a brain file spells, with its file. Stored grants and live runs are rewritten by the upgrade’s migration. Table: brain-dev-guide.md § Renamed engine names

• Tool catalog mirror in Redis — the MCP server publishes a serialized ToolCatalogEntry[] under omnislash:tools:catalog at startup and on every content-watcher tick; the dashboard reads it per request (never at boot) so its bundle stays free of tool runtime deps.

  • The catalog’s negative space rides along — the same write publishes what the policy denied under omnislash:tools:denied, because the catalog is the enabled set and what it omits cannot be read out of it. One call for both, so the two keys cannot drift apart.

• Engine system tools — HITL & approval — the producer and admin side of the human loop, all reachable from any agent.

  • Ask, approve, escalate — AskUserQuestion (blocking question, alwaysLoad + requiresHuman, offered to every interactive turn; promptFlags.questions: false removes it), hitl_request_approval (detached card, hitl:request), hitl_request_grant (capability escalation — any catalog capability, held or not — offered to every agent), hitl_request_connection (OAuth consent for an MCP server or brain provider, integration:execute), git_request_app (one card whose link registers or installs the deploy’s GitHub App, integration:execute — § Deploy-Owned GitHub App), hitl_list, hitl_respond, hitl_cancel

• Engine system tools — agent management and observability — spawn, drive, inspect and stop other agents from inside an agent turn.

  • Write side — agent_create, agent_task (spawn-and-wait with timeoutMs + timedOut snapshot), agent_call, agent_enqueue, agent_await, agent_answer, agent_escalate; the session commands are agent.* ops — agent_send (the chat verb: the agent’s inbox, merged with its other chat messages, refs riding as the text’s <refs> block as on chat_send; agent_enqueue stays the programmatic turn), agent_send_command (a harness slash command), agent_compact, agent_clear, agent_flush_mailbox / agent_clear_mailbox / agent_delete_mailbox_item, agent_stop / agent_delete ({ id } or { ids }; never the caller itself), agent_update ({ id, patch }, the AgentPatch fields; a widening — a model whose harness ignores the grant, capabilities the caller does not hold, a less confined runIn — is refused, agent_widen makes it under role:widen; a rename is a person’s), agent_align (drop the row’s own model and extras: the role file decides; refused from an agent when that widens, as agent_update), agent_intercept / agent_release (agent:intercept, restricted, HITL: take a live workflow agent over and hand it back). agent_send, agent_send_command, agent_compact and agent_flush_mailbox refuse an agent a live workflow run owns (an active interception exempts agent_send — for a person, or the agent that opened it)
  • Read side — agent_list, agent_get, agent_history, agent_tail, used by supervisors and by the sub-agent-supervision skill

• Engine system tools — memory — memory_search, memory_read, memory_write, memory_edit, memory_delete; the whole family is registered alwaysLoad so a memory-enabled agent reaches for memory on turn 1 instead of fabricating “I couldn’t save”.

• Engine system tools — skills — skill_get (SKILL.md body without frontmatter) and skill_read_resource (a whitelisted file from scripts/ / references/ / assets/, or the overridden engine version under engine/), both skill:read, safe and alwaysLoad (the prompt names them), and both serve only enabled, eligible skills.

• Engine system tools — notification and delivery — the verbs an agent uses to reach a human without an approval card.

  • Direct delivery — notification_send (a named channel from project config, or — omitted — the turn’s own chat / status when headless; the delivery verb for headless/heartbeat agents, auto-chunked, returns after real delivery), voice_send (TTS + playable voice message into the conversation or owner DM), file_send (document attachment into the current conversation)
  • Publishing — artifact_publish / artifact_unpublish (artifact:publish) turn an artifacts-directory file into a titled web URL with optional expiry, private by default, revocable; the rest of a publication’s life is the artifact.* ops (§ Artifacts & Deliverables › Artifact publishing)

• Chat access tools — the access.* engine-api ops, each an agent tool and a dashboard procedure: access_overview (per bot, every tier of its rules — defaults, the DM, each served or only-seen group — with its own entry, the rule in force and the tier behind each field; identities and owners; the roles a rule may name; bot health; warnings; the file’s sha), access_identities (who is in a chat and the tier each one has there; with no bot, every identity — a person or a chat that speaks — the brain lists and where their tier is set; with identity, that identity across every chat and DM), access_explain (simulates one message — bot, chat (dm or a group), sender (an id or a @username) or senderChat, text, addressed, reply, a status stub — through the bot’s own resolver and the brain’s real policy code; an ordered trace setup → served → rule → tier → engage → commands → limit with decided, the step that said no; changes nothing), access_read_file (the whole file as written, an invalid one included), chat_history (runtime:read — what a bot saw in a group and said there, newest first; DMs are not logged), agent_list({ chat }) (a chat’s chat agent and thread agents), access_update / access_widen (one write in one of three shapes — typed edits (identity, rule on default / dm / a group, remove_chat, unknown_chats), one tier as YAML, or the whole file — validated as the bot loads it, classified for widening whatever the shape, dryRun + expectedSha, written by compare-and-swap with comments preserved, answering { sha, diff, consequences }; a @username resolves through the chat log, then the brain’s Telegram account). Each write is one action-log row. The chat-access engine skill carries the procedure — chat-access.md

• Engine system tools — runtime, health and diagnostics — runtime_overview (live agent execution across the deployment via Restate introspection, plus every invocation of any service Restate paused after its retries ran out), health_overview (the generated tool of the health.overview op since 1.23.0: worst, this process’s health probes, the service roster — heartbeats beside Prometheus’ scrape, with container restarts —, the brain-sync daemon’s state and the Prometheus / Grafana / Loki sections as { value } or { error }, which source answered (sources), with an explicit caveats list), doctor_check (engine self-diagnostics, including live LLM and embedding provider liveness read off the circuit-breaker record — the generated tool of the doctor.check op, so it returns exactly the report the dashboard’s Doctor page renders; maxAge (seconds) takes a report this process ran that recently, checkedAt saying when — what the dashboard’s badge polls with; only: "issues" trims it to the warn/fail results for triage), infrastructure_endpoints (HITL-gated endpoint discovery — the generated tool of the infrastructure.endpoints op since 1.24.0, output unchanged), brain_search (runtime:read, since 1.21.0 — free-text search over workflow runs, agents, scenarios, blueprints, skills, pipeline runs, self-evolving cycles, published artifacts and (since 1.24.0) requests, capabilities and tools (with governance:read), bots, chats and people (with access:read), ranked, one group per kind with truncated, each hit carrying the id the kind’s own tools take and the entity it belongs to; a kind that could not be searched is named in failed — the op behind the dashboard’s Cmd/Ctrl+K palette).

• Engine system tools — data and queues — db_query and db_execute (search_path pinned to public, so omnislash.* needs qualifying; ;-separated statements run as one transaction and every statement reports on its own, in order — {results: [{command, rowCount, rows?, truncated?}]}, rows present exactly when the statement returns a result set, so “returns nothing” and “returned zero rows” differ by shape, and one 1000-row cap shared by the whole call; values bind to $1…$n through params (scalars; JSON as a string cast with $1::jsonb; with params the call is one statement, Postgres’ own rule), so no value is ever quoted into the SQL text; db_execute takes dryRun to rehearse a write and roll it back; a failed statement comes back with everything Postgres diagnosed — DETAIL / HINT / CONTEXT / RELATION / SQLSTATE, each clipped on its own at 500 chars, and the error position as psql prints it, LINE n: with the line’s text and a caret under the character — not just the message, so an agent that mistyped a column reads Postgres’s own “Perhaps you meant …” and sees where instead of guessing again), db_schema (tables, views, materialized views, foreign tables and partitioned tables, read off the Postgres catalog; each column’s type spelled exactly as a cast takes it — text[], numeric(10,2), omnislash."ExecutionStatus" — and an enum column’s (or enum array’s) labels as values, in the enum’s own order; covers public and omnislash by default, one optional schema to narrow, each entry tagged with the schema it came from, each table and column carrying its own DB comment as note, and a reported truncated when the description hits the column cap), kv_get / kv_set / kv_delete (kv_get the generated tool of the kv.get op since 1.25.0, its name, input and answer unchanged), queue_get, queue_create_job (ships enabled: false), event_ingest (records an external event in the durable inbox — hooks and dispatch react asynchronously — deduplicated permanently by (source, idempotencyKey), optional resources; engine-reserved sources refused; since 1.24.0 the generated tool of the event.ingest op: reemitOf: <eventId> alone records a stored event again under a fresh key, so it routes to its hooks and dispatch once more, and the answer names its source; the webhooks door keeps its own event_ingest at POST /tool/event_ingest for an external system — fresh events, the answer { eventId?, status }), brain_sync (force an immediate bidirectional brain git tick — the generated tool of the brain.sync op since 1.23.0: { outcome: 'synced' | 'skipped', durationMs, conflicts, message }, skipped when no brain-sync daemon runs).

  • AI-first, because an agent MODELS in these tools and does not just read — db_execute’s description names the DDL vocabulary of state.md (CREATE TABLE, ALTER TABLE … ADD COLUMN, CREATE OR REPLACE VIEW, DROP VIEW) and says the ;-batch is one transaction returning every statement’s rows in order, so RETURNING works and a DROP VIEW; CREATE VIEW swap can never leave neither; db_query’s tells the agent to qualify omnislash.*, to bind values via params, and to read the retention notes db_schema carries before it treats engine rows as history; all three kv_* descriptions redirect agent state to tables and keep KV for pipeline cursors, dedup and last-seen markers
  • db_schema answers the three questions a column list cannot — kind (table / partitioned / view / materialized / foreign, from relkind), the definition of a view or materialized view (pg_get_viewdef(oid, true) — the only way to check the view you just wrote says what you meant) and a table’s constraints[] (pg_get_constraintdef over PK / UNIQUE / CHECK / FK, so an invariant the schema already enforces is not re-derived in prose every turn). The whole answer is one pg_class ⋈ pg_namespace ⋈ pg_attribute read — information_schema could produce none of the three, named every enum USER-DEFINED and every array ARRAY, and did not list matviews at all — run under the same search_path = 'public' as db_query, so every type, default and definition is spelled the way it compiles there
  • One pg type mapper, shared by all three paths — applied per column inside the executors from fields[].dataTypeID, so db_query, db_execute and the <agent-state> render can never disagree about what a column is: date → YYYY-MM-DD (built with the LOCAL getters, the exact inverse of how the driver parses it — toISOString() loses a day east of UTC), timestamp[tz] → ISO, numeric / int8 / COUNT(*) → number, interval → its Postgres text form. Not pg.types.setTypeParser, which is process-global and shared with Drizzle. Recorded trade-off: int8 / numeric → number loses precision past 2^53, chosen because the consumer is a model reading a JSON value or a markdown cell, where a "3" costs every reader a coercion and a lost digit past 2^53 costs nobody anything — and a “safe string fallback for big values” is rejected outright, since two representations of one column type is worse than either
  • Per-transaction settings carry the caller’s identity — both executors take an optional settings bag applied as set_config(name, value, true) with name AND value bound (SET LOCAL takes no parameters), the name checked against a qualified namespace.name pattern so only custom GUCs are settable and the built-ins that ARE the executor’s promises (search_path, statement_timeout, role) cannot be smuggled through it. The tools fill it from auth.agentId, never from a tool argument

• What is in the brain’s tables and key-value store (since 1.25.0) — db_overview (db:read): every table and view of public (the brain’s migrations, the tables agents create, the <namespace>_* state views) largest first, each with its kind, estimated rows (Postgres’ statistics — n_live_tup, the planner’s reltuples when that reads 0 — never a count(*)), size (pg_total_relation_size) and the rows inserted / updated / deleted since the statistics reset (statsSince) — churn without a history table; the key-value scopes with their live keys, stored size and last write; totals, and the whole database’s size for scale. No row data and no values. db_tail (db:read): one table’s or view’s columns (name, type as a cast spells it, nullable) and latest rows — limit ≤ 50, default 20 —, newest first by created_at / createdAt / updated_at / updatedAt when it has one, else physical order (ctid; a view unordered, and a table past ~100k rows with no index on that column unordered too — the sort would hit the read timeout), each cell its text form (jsonb compact) cut at 500 characters with …; the name is looked up in the catalog, so one that is no table or view of public is not_found and never reaches SQL as given, and an agent’s call binds its id like db_query, so a state view scoped to it reads the same. kv_list (db:read): one scope’s live keys, newest written first, each with its value’s stored size, when written and when it expires — never the value (kv_get reads one); at most 200, truncated. All read-only, on the read path db_query uses (read-only transaction, the read timeout). The dashboard’s System › Data reads them.

• Engine system tools — filesystem and shell (API agents) — bash, file_read, file_write, file_edit, registered mcp: false because CLI harnesses ship built-in equivalents.

• Engine read ops — capabilities, the atlas, repos (since 1.23.0) — capability_list (governance:read: every capability as the tool gate merges it — engine set, the brain’s two policy files — with its risk, gate, source, the brain’s change to an engine default (policy), its providing tools and how many grants hold it and requests ask for it, plus each policy file’s state and the sha a policy write swaps against; since 1.24.0 toolsKnown — false when the tool catalog could not be read, so every tools is then unknown, not empty), capability_get (since 1.24.0, governance:read: one capability in full — its row, which tier each of risk / hitl / description comes from (provenance: engine, brain — your engine-capabilities.json changed it —, or project), the policy file a write of it lands in, every providing tool, the scenarios whose plan requires it, the entities whose grants: names it, its grants per status and open requests), capability_read_file (since 1.24.0: a policy file as written with its state and sha — a missing engine file reads as the engine defaults), atlas_structure (feature:read) / atlas_timeline (run:read, { from, to } epoch ms, ≤ 7 days; a reader that polls passes the at of the answer it holds as since and gets only the traces that moved, with ids — every trace of the full read — to merge them by) — the Brain Atlas read model (@omnislash-ai/atlas) as ops, and repo_list (config:read, a new safe capability: the brain checkout — the default — and every attached repo with its slug and remote). The dashboard binds the same ops; Home, /permissions, /permissions/tools, /atlas and the repo pickers read them.

• The boundary and the repos as ops (since 1.24.0) — endpoint_list (runtime:read): every address the deployment is reached at (inbound — the brain’s event sources at /event/<source> with today’s events and errors in the brain’s zone, the tools the webhooks door serves at /tool/<name> with their risk, the MCP server, the engine’s public services) and every one it reaches out to (outbound — dispatch webhooks with the events they subscribe to, notification channels and whether their chat resolves, the engine’s dependencies), each by an endpoint id <direction>:<type>:<name>, with the tool door’s HTTP contract, today’s traffic per source and the dispatch summary — public addresses only, never an internal host or port, and a dispatch webhook by its origin alone (its path or query often holds its secret); endpoint_get: one endpoint with what it takes and who listens — a tool’s schema and a sample body, an event source’s subscribers (hooks on its events, dispatch targets forwarding them) and newest event, a dispatch webhook’s last deliveries (delivered, rejected by a 4xx, blocked, skipped — nothing sent, the target was not configured when the job ran —, failed after its retries, still queued) with what the read covered (coverage: jobs scanned, the oldest seen, whether older ones were left unread — the queue keeps a bounded history) and its first event’s sample, the MCP server’s health, live sessions, exposed tools, resource templates and OAuth clients; endpoint_history: an event source’s events newest first, keyset-paged; endpoint_send (endpoint:send, moderate, no approval): a test to a dispatch webhook (its first event’s catalogue sample, test: true in the body and X-Omnislash-Test: true, through the same queue) or a notification channel (one fixed line); event_ingest({ reemitOf }) re-emits a stored event. Since 1.25.0 a tool row names its source (engine / brain), an event source’s today and bySource count the events its hooks processed, and http.baseUrl is never null — the public origin, else the webhooks app’s loopback port, which answers only on the webhooks app’s own host (a curl a person runs there; another container, an agent’s included, cannot reach it — the one non-public address the op names). repo_list rows carry each repo’s GitHub repository and visibility, sync state, attach time, the lane that authenticates it and outside (no installation serves it); repo_create / repo_delete (config:write) attach owner/name under a slug (a slug in use is refused, never re-pointed) and detach one (the checkout stays on disk); git_overview adds each installation’s status and createdAt and every repository the installations reach (available, with the slug it is attached under or would get — that walk is cached five minutes and dropped when GitHub reports an installation change, so repo_list and git_overview share it); git_authorize (integration:execute) is the App registration / install link for a person — an agent calling it is refused toward git_request_app, whose card carries the link (the link never lands in a tool result). The dashboard’s Connections pages read the same ops.

• The tool catalogue as ops (since 1.24.0, governance:read) — tool_list: every tool this deployment’s agents can be offered, with its label, category, platform, source (engine or brain), declared risk, every capability it provides and whether one waits for a person (gated), what brings it (provider: an engine platform, a brain defineIntegration bundle, the brain’s own tools), webhook and MCP exposure and whether it loads up front (loading); filtered by q, source, risk, category, exposed: "mcp", capability, provider (the tools one provider brings), with counts over the whole catalogue, the engine tools constitution/engine-tools.json switches off (switchedOff) and the brain’s tool loading (loadingDefault). tool_get: one tool with its input and output JSON Schema, annotations and each capability’s risk and gate (an unknown name is refused with the nearest real one). tool_summary: how tools were called over 1h, 24h or 7d — Prometheus’ totals, call trend (five-minute buckets over the hour, hours over the day and, since 1.25.0, hours over the week too — its own step, never folded), breakdowns by risk, source and error type, and per tool — with prometheus.state (up, unreachable, or failed — it answers but the query failed) and its retention said, every Prometheus section null unless it is up, and calls by agent from the conversation log beside it (which answers either way, with its own coverage); tool scopes it to one tool. The dashboard’s tool pages read the same ops

• Logs, events, configuration and the emergency stop as ops (since 1.25.0) — the reads an agent had no way to make: log_overview / log_list (runtime:read) — the deployment’s container logs as Loki holds them: the services and levels it has lines of and how long it keeps one (retention — a window older than that reads empty, not quiet), then one window’s lines (default the last 15 minutes) by service, level, the run / agent / pipeline-run / task id a line carries and a literal search, newest first, a page at a time; polled, not followed — ask again with from moved for what came since; precondition where no Loki runs (omnislash dev); event_tail (event:read) — the events themselves as they went over the bus, newest first, by name and since, from the capped tail of the last 20,000 (tailFrom says where it begins: a debug window, never a record) — every payload on the bus, every chat’s Telegram messages included, so a turn answering one chat (a secretary’s counterpart, a chat-scoped hook) is refused, and a role that serves anyone but an owner should not hold event:read; config_get (config:read) — the configuration as the engine runs it, each value with its tier: every MANIFEST key (brain where the file sets it, engine where the default fills in), the data sections of omnislash.config.ts and every declared environment variable with whether it is set — never a secret value: a secret variable answers by presence alone and its current value is scrubbed out of every string; system_stop / system_resume (system:stop — restricted, a person approves, granted to no role but a '*' one; system_status under runtime:read) — the emergency stop: ONE command brakes the scheduler, pauses every queued, running or retrying workflow and pipeline run — and one that needs you while its other tasks still work — and cancels every agent turn in flight (the caller’s excepted), recorded as one action; resume undoes exactly what that stop did — a brake or a paused run that was there before stays; a run that will not resume keeps the stop standing for it alone until a resume brings it back. The dashboard binds the same ops and its own click needs no approval

• Engine system tools — schedule, workflow and evaluation — schedule_overview, schedule_create_prompt (scheduler domain, below), the scenario and plan ops (scenario_*, blueprint_*, below) plus the workflow-engine group registered by registerWorkflowEngineTools (run_diagnosis, run_update_blueprint, pipeline_list); run_list / run_get, the eval_* tools and every loop_* tool (loop_status, loop_get, loop_trace, loop_summary, loop_list_agents, loop_history, loop_get_cycle, loop_get_proposal, loop_policy, loop_join, loop_set, loop_widen, loop_hold, loop_release, loop_rearm, loop_analyze, loop_create_idea, loop_cancel_idea, loop_ack_failure) are engine-api op tools generated from the run.*, eval.* and loop.* ops (Run read tools, Eval tools, below) — the workflow surface itself belongs to the workflow slice.

• MCP server — one HTTP process serving every agent — Streamable HTTP on /mcp (default port 3100) with all heavy DI shared across sessions, plus a --stdio transport for Claude-Desktop-style single-parent use.

  • Session lifecycle — one (Server + Transport) pair per initialize, Mcp-Session-Id on every subsequent request, DELETE to terminate; a 15-minute idle reaper (60 s sweep) skips any session with in-flight requests
  • Session URL parameters — identity (agentId, blueprintId, scenarioId, taskRunId, runId, pipelineRunId, pinnedRunId, planningSessionId, conversationId, role) via parseAuthFromUrl (pinnedRunId = the replay pin a turn on pinned content hands to every sub-agent it spawns), the run the session’s work counts toward runRef= (JSON { runKind, runId }, what a brain tool records as lineage; malformed reads as absent), the execution the session’s turn runs inside execution= (JSON { id, entity } — what its sub-agents inherit and what a workflow / pipeline it starts records as its parent; malformed reads as absent), the boolean flags unattended=1 / loopLaunched=1 (only the literal 1 reads as set), plus execution traits via parseSessionOptionsFromUrl — interactive=false / memory=false (closed-loop: only the literal false is recognized; memory=false = the role declares no memory: block, so the memory tools are refused) and the agent’s memory lines memoryScope / memoryReadScopes / memoryWriteScopes (open-valued, re-validated against MemoryScopeSchema — the writable set keeps lines only and drops '*' or an authored corpus — unrecognized → default line; memoryWriteScopes is always emitted for an agent, and an EMPTY value means writes nowhere — a replay’s turn, or an agent without memory — while an absent one means home line only)
  • Per-session catalog filtering — mcp: false never exposed, agents: false never exposed, requiresHuman: true stripped and rejected in CallTool for non-interactive sessions; CallTool re-checks all three flags so a harness cannot call a name it never saw
  • Resource-exhaustion caps — MCP_MAX_BODY_BYTES (4 MiB → 413) and MCP_MAX_SESSIONS (1000 → 503)
  • Security — loopback MCP_BIND_HOST default, MCP_ALLOWED_ORIGINS allowlist enforcing 403 on browser origins (DNS-rebinding defense), SDK-delegated MCP-Protocol-Version validation, MCP_ADMIN_TOKEN-gated /admin/sessions
  • JSON-RPC error envelopes — every /mcp guard (403/400/404/405/413/503/500) answers in the spec’s error shape; /health, /ready, /metrics keep plain JSON
  • Progress and cancellation — notifications/progress driven by ToolContext.emitProgress with a monotonic counter, and notifications/cancelled wired to ToolContext.signal; opt-in per tool with a documented catch-and-translate pattern
  • MCP logging primitive — logging: {} capability plus a pino→notifications/message broadcast with per-session level filtering
  • Telegram log transport — optional INFO+ log mirror into a channel (TELEGRAM_MCP_CHANNEL_ID), buffered at 500 entries and flushed every 2 s with serialized sends
  • Bearer door — bearer-keyed public access at mcp.$DOMAIN/mcp in domain mode (Caddy proxies only /mcp, refusing keyless requests at the edge): a request carrying Authorization or X-Forwarded-For must present MCP_TOKEN and is pinned to subjectId: 'mcp:default'; docker-network callers stay keyless
  • Self-serve grants through the door — hitl_request_grant from a bare-principal context routes through the mcp HITL producer, and the Telegram/dashboard approval card names the standing subject scope, so approve mints a grant covering every session of that key
  • Deliberately not implemented — the MCP Tasks primitive, resources/subscribe, resumability/EventStore, and OAuth on the bearer door (static bearer only)

• MCP resources — read-only data by URI — omnislash://skill/{name} (eligible skills, text/markdown) and omnislash://hitl/{id} (own pending interactions only; cross-agent reads return -32002 without disclosing existence), with RFC 6570 templates for late fetch.

  • listChanged fan-out — ResourceRegistry.notifyListChanged() debounced 250 ms, fired from hitl:requested / hitl:responded and from the skills content watcher; per-session unsubscribe on server close
  • Extension point — implement ResourceProvider (prefix + list + listTemplates + read) and register it in registerSystemResources

• Per-agent external MCP servers — an .agent.md declares mcpServers: { name: { type: 'http' | 'sse', url, headers? } } and resolveMcpServers interpolates ${VAR} / ${VAR:-default} in URL and headers, then reshapes per harness (Claude McpHttpServerConfig, Codex http_headers with SSE upgraded to HTTP, OpenCode type: 'remote').

  • Merge order — .mcp.json in cwd (Claude only) < agent-level < the engine’s own omnislash entry, which always wins and cannot be renamed
  • Unauthorized by the engine — external MCP output bypasses ToolsGateway, so no HITL, no rate limit, no per-tool metrics and no prompt-injection wrapper; authorization is the external server’s problem
  • Playwright sidecar — an official playwright-mcp service ships enabled by default (services.playwright), reachable at http://playwright-mcp:8931/mcp in Docker, probed by omnislash doctor, with two documented traps (pin a cli: model ref; give every ${VAR} a default)
  • Preview browser (since 1.25.0) — a browser service (Chromium headless-shell, chromedp/headless-shell) ships enabled by default (services.browser): the webhooks app renders widget previews in it over CDP, on a preview network only the two share (internal in production — the browser has no way out; every request a page makes is answered from memory, a mock or a guarded fetch of its resourceDomains); doctor Widget preview says whether a preview can render now

• Client configuration recipes — ready-made .mcp.json ("type": "http" required), Codex config.toml and OpenCode opencode.json snippets, plus buildOmnislashMcpUrl(url, auth, traits) used by every CLI harness launch.

HITL (Human-in-the-Loop)

• Unified HITL Gateway — every human-blocking interaction in the engine flows through one HitlGateway, one hitl_interactions table, and one event pair (hitl:requested / hitl:responded); parallel HITL channels are banned.

  • Two orthogonal axes — kind × producer — kind owns the response Zod schema and card renderer, producer owns required context and resume/dispatch side effects. A missing (producer, kind) cell throws HitlError.unsupportedCombo at request() time
  • Six kinds — question, grant_request, approval, input_request, oauth_consent, interception; response shapes live in HITL_RESPONSE_SCHEMAS_BY_KIND and are re-validated on every respond() because they cross a serialization boundary
  • Producers — agent, planner, workflow, schedule_manual, schedule_cron, pipeline, connection, mcp, loop, rating, chat (the unknown-group admission card, answered in Telegram only), budget (a spent money budget’s raise card — budgets.md); each owns its validate() invariants and per-kind handler cells in a closed PRODUCERS registry
  • Who may answer a card from chat — not configurable — approvals and grants only an owner; a question its addressee (the person the asking turn served) or an owner. authorizeResponder runs inside respond() / cancel(), so a refused press leaves the card pending and the presser gets a private alert. A question stays in its chat for its addressee; any other card raised by a turn serving a non-owner is delivered to the HITL chat (with a “raised by … in …” line), never into a group where anyone could press it; pending reply modes are keyed by (chat, person), and the agent inbox never merges two people’s messages into one turn
  • Gateway API — request(), respond(), respondByAgentId(), cancel(), cancelPendingForRun(), cancelPendingForAgent(), cancelPendingForReapedAgents(), sweepForInterception(), cancelExpired(), getById(), reconcileUndispatched(), dispatchPendingForAgent(), releaseDue(), forwardToHuman()
  • Narrow facades — HitlGatewayRequester (produce only) and HitlGatewayAdmin (respond/cancel/getById) so a container can wire one side without the other; HitlGateway structurally satisfies both
  • Injected side effects — HitlGatewayDeps extends Partial<HitlCallbacks>; createHitlCallbacks() (agents-api) plus createWorkflowHitlCallbacks() (workflow-engine) supply the full set, and an unwired callback leaves the row for reconcile instead of failing
  • respondedBy: Actor — a single discriminated union (telegram / dashboard / agent / mcp / webhook / system / …) replaces the old {responderType, responderId, respondedVia} triple
  • Surface routing — delivery surface is req.context.surface ?? <lineage surface> ?? deps.defaultHitlSurface (the lineage surface: below, under Sub-agent questions); TELEGRAM_HITL_CHAT_ID names a dedicated HITL chat separate from the status chat, and is optional — unset falls back to the primary owner (the first id in TELEGRAM_ALLOWED_IDS)
  • Conversation binding — each row is bound to an agent_conversations row (caller-supplied conversation id reused, otherwise a placeholder minted in the same transaction); conversation_events rows (hitl_request / hitl_response) carry the full interaction snapshot so timelines render without a join

• AskUserQuestion — one question channel across API, Claude, Codex and OpenCode — a single tool name and a single canonical tool_use sentinel guarantee “question visible to the model → run paused → exactly one hitl_interactions row”.

  • Exactly-once producer table — API/Claude-MCP/Codex-MCP/OpenCode-MCP produce the row from execute(); OpenCode’s native question tool and Claude’s bare builtin are covered by parser/queryRunner safety nets
  • Generic HITL-tool pause — ToolsGateway.hitlToolNames is derived from ToolDef.hitl === true (today AskUserQuestion + hitl_request_grant); API pauses via processApiStream’s wrapped executor, CLI via per-harness MCP-prefix stripping + processCliStream. Adding a HITL tool needs zero execution-code changes
  • Runaway guards — a model that ignores the “execution paused” hint and emits another tool call gets a synthetic terminal result and a closed/aborted harness stream; the guard is disarmed by an error tool_result so a self-healing retry is not killed
  • Failed-call pause withdrawal — an error tool_result for the armed toolId withdraws the pause, because a failed call created no row and pausing would strand the run in unresolvable awaiting_input
  • Question keyboards — single-select option buttons, multiSelect toggle chips with the selection bitmask carried in callback_data (no Redis, no TTL) plus Submit, multi-question fallback to typed text; the dashboard mirrors the same { answer } contract
  • Non-interactive agents — interactive: false strips requiresHuman: true tools by the one selection rule on both paths (the API tool set; the CLI MCP session’s ?interactive=false filters tools/list and refuses CallTool), and swaps the prompt module to without-questions.md
  • Per-provider prompt nudges — with-AUQ-claude.md / -codex.md / -opencode.md / with-AUQ.md routed by SystemPromptBuilder.withQuestionPolicy

• Sub-agent questions — the parent first, then the person, on the person’s chat — a question from an agent another agent spawned (agent_task / agent_call / agent_enqueue / agent_create) is routed by the delegation tree instead of landing context-free in the owner’s HITL chat.

  • Lineage surface — a sub-agent runs surfaceless on purpose (its stream must not talk into the parent’s chat), so for a surfaceless request naming an agent the gateway walks the asker’s ancestors (agents.created_by, nearest first) and delivers to the first one’s chat — the chat its current turn serves, else the chat it is scoped to — before the default HITL chat. Applies to questions, grant requests and OAuth consent alike; a business chat still reroutes the card to the owner’s DM
  • Parent head start (delegation.parentFirstMs) — a delegated QUESTION waits for its parent before a person is asked: engine default 120 s → constitution/MANIFEST.yaml § delegation → the asking role’s delegation: frontmatter; 0 = ask a person at once (e.g. a role operating the person’s live desktop). The row is held (deliver_after) with no card pushed; the reconcile tick (60 s) releases it when the head start is over. Grant requests and OAuth consent are never held — a parent cannot approve them
  • The parent’s view — agent_task / agent_call / agent_await return awaiting_input with pendingHitl: { hitlId, kind, questions, deliverAt } (agent_get under current); the parent answers with agent_answer, escalates with agent_escalate (note shown on the card), or does nothing and the card reaches the person at deliverAt. No grant card for the parent: both tools ride agent:execute
  • Card context — the person’s card names the asker (displayName · role), delegated by <parent> with an excerpt of the task, and the parent’s escalation note when there is one

• Detached approvals — hitl_request_approval (agent tool) and requestApproval (pipeline SDK) fire a decision card and return the hitlId immediately, so a batch producer never freezes on human latency.

  • Custom actions — payload.actions: ApprovalAction[] (1–8, id /^[a-z0-9_-]{1,32}$/, reserved ids custom/cancel/chat rejected, label ≤ 64 chars, style ∈ primary|success|danger|muted); omitted → default Approve/Deny
  • Structural response union — { actionId, note? } from a button tap (the note: a short why a surface with a text field may attach), { customReply } from a Telegram native reply on the card or the dashboard “✏️ Custom…” input; isApprovalAction narrows
  • Three composable consumers — a *.hook.md on hitl:responded filtered by kind + tags, a later poller via hitl_list, or onReply: 'conversation'
  • onReply: 'conversation' — a free-text reply is recorded on the row first, then handed to the surface’s conversation-owning chat agent as a normal chat turn, the text as written: the card’s reply link attaches the raising feature’s reply contexts and the quote names the card; button taps never converse, and dashboard replies stay data-only
  • Card identity is durable — a native reply finds its card through the message’s origin row (message_origins.hitl_id, on every message the card became), not a 24 h cache: a reply routes to the card while it is pending, however old, and is an ordinary message once it is decided
  • tags lifted onto the event — copied from payload.tags to the event body so hook matchesFilter can use array-contains semantics without nested paths
  • cancellable: false — hides the ✕ Cancel button on both surfaces and rejects forged hitl:{id}:cancel callbacks; a caller holding hitl:write can still force-close via hitl_cancel
  • Auto-layout — Telegram renders 1 button/row when any label exceeds 20 chars, else 2/row; the dashboard bulk Approve/Deny bar excludes custom-action cards

• Blocking approvals and questions for pipeline steps — awaitApproval / askQuestion / requestGrant / requestInput create rows carrying context.pipelineAwakeableId and suspend on the Restate awakeable, resolved by the producer cell’s unblockOnResponse (pipeline runtime itself is the workflow slice’s).

• A pipeline’s approval expires by default — an awaitApproval card gets a deadline when the call names none: 168 h (engine) → pipelines.approvalExpiresInHours in MANIFEST (0 = no default deadline; read live at each approval) → the call’s own expiresInMs (null = never). A waiting run keeps its journal across every deploy, so a card nobody answers must end; expired, the helper throws ApprovalCancelledError with an expired: reason. requestApproval (detached — nothing waits) keeps no default. — pipelines.md § HITL helpers

• Structured input collection (input_request) — blueprint and pipeline entry points collect schema-validated input from a human before anything runs.

  • Pre-run workflow forms — an input-less submitFresh against a blueprint declaring inputSchema opens the card and returns { kind: 'input_requested' } with no run row created; the response re-enters submitFresh via enqueueWorkflowFromInput
  • Pre-run pipeline forms — a workflow-primitive scenario with inputSchema intercepts Telegram /run and triggers the Restate ingress only after the form is filled (enqueuePipelineFromInput, tryOpenPipelinePreRunInput)
  • Mid-run pipeline input — requestInput() inside a handler, resolved through the awakeable
  • InputSchemaTranslator — turns a blueprint inputSchema into a prompt and parses a free-text (or voice) reply back into structured fields, both derived from the ZodFieldMeta[] introspectJsonSchema gives the dashboard input drawer
  • No TTL by design — the single-responder workflow.input_request cell coalesces re-triggers indefinitely so exactly one card lives until answered or cancelled

• Interception — take the wheel mid-run — a dashboard user opens a live chat with a workflow agent, steers it with ordinary agent.send turns, then hands it back; release and cancel both re-dispatch a continuation turn and resume the run.

  • The pending row IS the session marker — a partial unique index on hitl_interactions(agentId) WHERE kind='interception' AND status='pending' enforces single-active at the DB level
  • Resume choke point — submitResume rejects every user-initiated resume with RUN_INTERCEPTED while an interception row is pending, so no question/grant wake re-drives the run mid-session
  • Session inherits the intercepted task turn’s auth — the interceptor’s turns and the release continuation turn keep the run’s scenario-scoped grants (no missing_grant mid-task); an agent parked awaiting_input on a question is interceptable (the main case), and because the pause is COOPERATIVE, Release is admitted only from a resumable-or-terminal run

• Chat supersede for pending questions — a plain (non-reply) chat message to an agent parked on a question card cancels that card and wakes the agent with the supersede reason in its resume prompt; card replies still answer the card, and grant_request cards are never dissolved by unrelated chatter.

• Custom grant flow (Telegram) — the “✏️ Custom…” button on a grant card opens a three-stage flow (init → LLM-parsed text/voice reply → confirm/change/cancel) that overrides the default TTL and call budget via customOverrides: { ttlHours, maxCalls }, routed through InputRouter so voice replies work.

  • Duration rows — 4h 12h 1d 2d / 3d 1w 2w 30d under Approve/Deny: a one-tap full approve at an explicit lifetime (same customOverrides.ttlHours shape, no text round-trip). Floor is MIN_DECLARED_GRANT_TTL_MS, ceiling MAX_GRANT_TTL_HOURS, so no button can mint a grant the next coverage probe can’t see or the response schema rejects; the resolved card’s verdict names the lifetime it bought

• Durability — terminal state is not dispatched — the gateway commits the human’s decision first and remembers whether the consequences ran, so no crash window loses an answer or double-applies one.

  • Two-phase dispatch / outbox — status (pending → resolved|cancelled) and dispatched_at (null → ts) are independent monotonic axes; a failed dispatch bumps dispatch_attempts + last_dispatch_error and stays in the undispatched pool
  • Apply/unblock split — a HandlerCell’s fallible applyResponse (today only grants.issue) runs in try/catch and the mandatory unblockOnResponse always frees the waiter, degrading per producer (GRANT_ISSUE_FAILED_PROMPT / grants_issue_failed / resolve-anyway)
  • Reconciliation loop — hitl-reconcile BullMQ job scheduler (60 s, scheduler-produced, concurrency=1 worker) releases delegated questions whose parent head start is over (releaseDue), then drains terminal-undispatched rows older than 30 s, backed by the partial index hitl_undispatched_idx
  • Opt-in TTL + sweep — expiresAt on request(); cancelExpired() routes overdue rows through the normal cancel() lifecycle with a 'expired:' reason prefix so cards finalize as ⌛ Expired
  • First-writer-wins + dispatch replay — an already-resolved row with a matching payload is returned for replay, a differing payload is an idempotent no-op, a fully dispatched row is a silent no-op (responsesEqual)
  • Barrier defer (soft) — a responder who answers before the agent VO commits resumeAwakeableId triggers HitlError.barrierNotReady, which is a defer (no markDispatched, no attempt bump, no caller-visible failure) re-driven by the agent:input_request lifecycle event
  • Eager validation — unknown producer, per-producer context invariants, unsupported (producer, kind), and unregistered grant_request capabilities all fail before any DB write
  • Boot backfill for card delivery — HitlNotifier.start() re-drives pending rows with dispatch_card IS NULL (a question still held for its parent excluded — nobody was asked yet) through the same render path, closing the hitl:requested pub/sub drop window across a bot restart
  • Guarded task-run CAS on resume — enqueueAndResume flips the owning task_run awaiting_input → pending only when the run holds no live attempt, reporting three-way readiness (task_dead / not_parked → soft defer / ready)
  • Retention sweep — amortized prune (5 % of request() calls) keeping the newest 5000 rows plus every pending row and every row referenced by grants.hitl_id

• Cell-level request coalescing — a HandlerCell opting into dedup joins concurrent same-key requests onto one pending row via the partial unique index hitl_dedup_active_idx, so N producers show a person one card.

  • Grant fan-out — stableGrantKey = [subjectId, scopeKind, scopeId, sortedCaps] (producer deliberately absent) with a shared grantRequestCell that iterates interaction.subscribers and wakes each by its own producer
  • Single-responder input — stableInputRequestKey = [subjectId, scenarioId], arity-disjoint from the grant key; its subscribers array is intentionally unread so one card enqueues exactly one workflow
  • Per-subscriber wake idempotency — every wake job’s dedup key (BullMQ jobId, Restate idempotencyKey) must include the subscriber id; first-writer wins on expiresAt

• Agent-driven HITL triage — the hitl.* engine tools let an agent observe and resolve interactions through the same CAS + dispatch + event path as Telegram and the dashboard, with no parallel resolve surface. They are engine-api ops: the dashboard’s inbox binds the same ops, so a page and a tool answer with one guard set and one wording, and each records its caller (the dashboard, the calling agent, the MCP session) as the responder.

  • The request row (since 1.24.0) — every row says requestStatus (pending · answered · cancelled), requestKind (question · permission · approval · input · sign_in · admission — REQUEST_KINDS), risk (a grant’s riskiest capability under the brain’s engine-capabilities.json; an approval moderate, the rest safe), allows (the verdicts it takes now: approve · deny · answer · edit · reply · cancel), bulkable and expiry ({ at, consequence? }, the producer’s word for what an expiry means). An interception is not a request: never listed
  • hitl_list — hitl:read, read-only; filters by status, kind, producer (each a list), conversationId, agentId, runId (any execution: a workflow or pipeline run’s own requests and every one a turn inside it raised — a tick’s or fire’s agent’s during that tick or fire only), responder, capability, ids, q (id, title, message, questions, reason, capabilities, the asking agent’s name, its run’s slug or title, its scenario’s name), personFacing, stuck (decided, never delivered), closesWithinHours, feature / entity, a window (default all; it holds the requests decided in it and never hides a pending one; window or wall-clock from / to + tz, answered back as the resolved window); sort: oldest | newest | expiry | risk | decided (default oldest for status: ['pending'], else newest; decided — newest decided first, closed requests only); pages by cursor (a cursor of another sort, or of risk across a capability-policy edit, is refused), limit ≤ 200, detail: 'compact' | 'full' | 'count' with kind-aware summaries — full adds the payload, the response and what each request belongs to (run, plan, agent, task, grant) — and facets: true (counts per kind, producer, agent, responder, capability and status, the stuck ones and the ones closing soon, each under the other filters); every row says whether it is stuck, a grant’s grantTerms (the scope approving mints and its life when none is set) and, once closed, its outcome (verdict, label — “Approved 2 of 3”, the card’s own action, “Expired” —, approved, the quoted answer or reply, responder)
  • hitl_get (since 1.24.0) — one request whole: the row, what it links to as refs (the person, the session that opened and the one that answered it, its run, scenario, task, thread, planning session, pipeline run and awakeable) and its delivery (attempts, the last error, a timeline, stuck)
  • hitl_summary — what waits on a person per kind, feature and age (pendingAge: under 1 h · 1–4 h · 4–24 h · 1–3 d · over 3 d), the requests opened per bucket, answered per bucket with the median and p90 wait (latency) and who answered (byResponder: a person, the dashboard, the Boss, another agent)
  • hitl_respond — hitl:write, restricted + HITL-gated; flat response object whose fields the request’s kind picks (answer / actionId (+note) or customReply / approvedCapabilities+customOverrides / input); a sign-in or an interception is not answered here. A request no longer pending is refused, never answered twice. Approving a grant_request takes a person: the gateway refuses every non-person [unauthorized_responder] — the active boss run inside its approvableCaps aside (never its own card, never a principal-wide subject grant) — and the card stays pending; denying (approvedCapabilities: []) is open to any responder
  • hitl_respond_bulk — hitl:write; up to 50 { hitlId, response } items, each answered as its own hitl_respond (one failure does not stop the rest) → { answered, skipped, failed }; a pending request that is not bulkable is skipped and named in skipped with why — an admission (answered in its chat), a question, an input, a sign-in, an approval with no one-tap pick
  • hitl_cancel — hitl:write, restricted + HITL-gated; reason bounded to 500 chars; a refusal leads with the gateway’s code ([already_resolved]-style discriminators) so agents branch without string-parsing. The caller is passed as the canceller, so a producer that keeps its cards for a person (the loop’s decide and retry cards, a rating card) refuses a non-person [unauthorized_responder] and the card stays pending — the same check hitl_respond already ran
  • agent_answer / agent_escalate — the parent’s side of a sub-agent’s question (agent:execute, descendants only): answer it (the answer prompt is wrapped as Agent’s answer… rather than User’s answer…), or forward it to the person now with a note; grant requests are not answerable there — a person approves them

• Boss agent — a meta-agent that works the HITL queue — a person starts a time-boxed boss run whose BossRunConfig fixes every security knob: expireAt (must be future), hitl.forwardingDelayMs head-start for the human, hitl.allowedKinds, initialCaps, and approvableCaps.

  • boss_status / boss_start / boss_stop (since 1.24.0) — Boss mode as engine ops, the dashboard’s and an agent’s: the active run and the MANIFEST boss: defaults (boss:read), start on a full BossRunConfig (dryRun checks it) and stop (boss:execute — restricted, HITL, granted to no role: an agent starting Boss mode asks a person first)
  • BossHitlBridge — mirrors hitl:requested into a delayed per-run wake-up enqueued on the boss agent, collapsing bursts onto one deferred invocation; the human always gets first refusal via the delay
  • Run terms in the wake-up — the bridge renders expireAt, allowedKinds, initialCaps and approvableCaps into the turn body, so the boss reads its own authority instead of discovering it from a failed hitl_respond; deliberately absolute (not “expires in 47m”) because the idempotency key collapses a burst onto one deferred invocation
  • Brain-tunable run defaults — constitution/MANIFEST.yaml § boss: (ttlMinutes, hitl.*, initialCaps, approvableCaps) seeds the start form over engine .default()s; an omitted cap list still falls back to preselecting every restricted capability, a declared [] starts the picker empty
  • Brain-authored prompt — constitution/Agents/system/role-boss.md overrides the engine’s copy whole, modelRef included (nothing is pinned by boss_start); brain-facing spec in docs/brain-dev/boss-mode.md
  • Loop guard — a boss can never respond to or cancel an interaction it produced itself, enforced in hitl_respond / hitl_respond_bulk / hitl_cancel, not just at enqueue
  • Approvable-caps guard — every approvedCapabilities entry must be in the run’s approvableCaps allowlist; the list is the security boundary, the role prompt is only documentation
  • Expiry + run summary — bossExpireScheduler / bossExpireWorker end the run (user_stopped / expired / crashed) and emit boss:run.expired with a BossRunSummary (duration, turns, tools by count, HITL by kind and status)

• HITL events on the per-agent output stream — hitl_request / hitl_response envelopes carrying the full row snapshot are written to agent:{agentId}:output alongside the EventBus emit, so live agent views upsert the card in place by hitlId instead of refetching; pipeline HITL (agentId === null) skips the stream write, and stream failures never fail the mutation.

• Cross-surface card synchronisation — every consumer subscribes to the same two events, so a resolve on the dashboard finalizes the Telegram card (verdict footer, keyboard cleared) and vice versa; the notifier handles both race orderings (response before card sent, already-terminal at render time).

• Chat stream rebind after an agent resume — AgentStreamRebinder re-binds the chat presenter on hitl:responded for (resolved, producer='agent', kind ∈ {question, grant_request}) when the resumed agent is still the surface’s active chat agent, gated so a batch of N workflow grant approvals cannot clobber the live chat session.

• Headless HITL consumer for tests — TestHitlChannel subscribes to both events and exposes waitForRequest(predicate) / respond(), backing 21 *.integration.ts suites covering CAS, per-cell side effects, dedup, reconciliation and stream broadcast.

Policy & Security

• Capability model — one vocabulary for “what may this agent do” — a capability is a domain:capability string carrying { risk, hitl, description }, declared by tools (providesCapabilities) and by plan tasks (TaskSpec.requiredCapabilities).

  • Three layers, merged at runtime — hardcoded ENGINE_CAPABILITIES, brain overrides in constitution/engine-capabilities.json (risk/hitl/description only), and brain-new capabilities in constitution/project-capabilities.json; unknown or colliding keys warn and skip
  • Engine domains — runtime, artifact, agent, queue, governance, feature, skill, db, event, brain, infrastructure, hitl, schedule, planning, workflow, loop, episode, pipeline, integration, research, email, drive, sheets, calendar, tasks, messaging, contact, access, telegram, notification, docs, design, media, writing, engineering, file, memory
  • Risk levels — safe < moderate < dangerous < restricted (compareRisk / maxRisk / deriveRisk), informational for UI and logging; real authorization is the hitl flag
  • hitl: true gate — engine defaults are email:send, messaging:send, access:admin, access:widen, telegram:invoke, drive:delete, infrastructure:discover, hitl:write, memory:delete, loop:analyze, loop:auto_accept; a brain may flip any of them
  • ADMIN_ONLY_CAPABILITIES — an engine-owned closed set (today loop:auto_accept) that GrantService.issue rejects from every source but admin/admin_extend and that prompt builders strip from the planner’s vocabulary; deliberately not a CapabilityMeta field so a copied-forward brain file cannot silently un-restrict it
  • Admissibility rule for notification:send — a send-class capability may be hitl: false only when the destination is never a free-form argument (no destination at all, or a closed enum of owner-declared channels); anything taking a raw chat id is messaging:send territory
  • Package API — getCapabilities, getCapabilityMeta, getCapabilitiesByDomain, isValidCapability, deriveHitl, requiresApproval, getCapabilityRisk, parseCapabilityString(s), extractCapabilities, getCapabilitiesForPrompt, getEnrichedCapabilitiesForPrompt, classifyDeclaredCapabilities, getCapabilityProvenance / diffCapabilities, resetCapabilitiesCache / reloadCapabilities
  • Agents and the dashboard write the values — capability_set_policy / capability_delete_policy / capability_write_file (governance:write, restricted, approval by default — a write can remove any gate, its own included) edit risk / hitl / description in both files; the dashboard’s Permissions page (/permissions) calls the same ops. capability_set_policy / capability_delete_policy answer consequences on the dry run and the commit alike (since 1.24.0): each changed field before → after with its direction, and widening: true when the write turns an approval off or lowers the risk — a reset to an engine default looser than the brain’s value included. Dry run → expectedSha → compare-and-swap on the file’s sha (conflict when it moved), a file that would not load (a renamed key included) is invalid; the writing process reloads its catalogue, the others pick the change up through their content watchers, brain-sync commits it. An invalid file is refused for a value edit, never rewritten — same rule as regen; only a whole-file capability_write_file replaces it. One audit row per write
  • omnislash regen sync — ensureEngineCapabilities (a regen materializer, so init / regen / upgrade all produce it) adds new engine caps, drops removed ones, and preserves brain overrides; a MISSING file is written with engine defaults, while a policy-shaped-but-invalid one is left byte-identical and reported converged: false (never silently overwritten — see packages/capabilities/CLAUDE.md). omnislash doctor reports the state read-only and writes nothing

• Grant model — one grant, exactly one durable scope — omnislash.capability_grants rows carry NOT NULL (scope_kind, scope_id), a text[] of capabilities, optional max_calls, a TTL and an audit link to the approving interaction; a grant attached to nothing is unrepresentable.

  • Six scope kinds — scenario (slug), agent (agents.id), heartbeat (definition slug), hook (definition id), role (role slug), subject (SubjectId); heartbeat and hook exist so one approve survives a row-per-tick / row-per-fire agent; role covers every turn run as that role and is never minted from a request — only grant_create issues one (a person on the dashboard, or an agent with a person’s yes)
  • Visibility = scope equality — grantScopesOf(auth) derives one entry per populated axis and buildGrantVisibilityWhere ORs them into index lookups; an empty set compiles to false (deny everything)
  • grantTargetOf mint precedence — heartbeat > scenario > hook > agent, never role, never subject, so a runtime request can never escalate itself to principal-wide authority
  • Per-kind default TTL — 24 h for scenario/agent, 30 days for heartbeat/hook/role/subject, clamped into [30 s, 365 d], and into [30 s, 720 h] for an agent’s grant_create / grant_extend (source command); a card’s customOverrides.ttlHours overrides either way
  • Lifecycle — active → revoked | expired | exhausted; consume increments atomically under WHERE used_calls < max_calls, an expired row stays expired (status is derived, never swept), revoke keeps the row, and probabilistic GC (5 %) reaps rows older than 30 days
  • Nothing cascades — deleting an agent row leaves its agent-scoped grants as unreachable rows until retention GC; a grant is never re-pointed
  • Events — grant:created on every successful insert (HITL approve included, carrying source) and grant:revoked

• GrantService — one read primitive, one write path — authorize / computeCoverage answer coverage, issue is the only insert, and consume / revoke / listActive cover the rest.

  • requiresApproval filtered inside the read path — callers pass raw capability lists; ungated names are dropped once, in one place, so a card can never ask a human to approve fs:read
  • IssueSource discriminates replay safety — hitl_approval requires hitlId and writes INSERT … ON CONFLICT (hitl_id) DO NOTHING + SELECT; admin / declaration / bootstrap are plain inserts; admin_extend revokes and inserts in one transaction
  • Boundary validation — issue re-parses the scope through GrantScopeSchema and every capability through parseCapabilityString, because both cross tRPC input and HITL JSONB before landing

• provisionGrants — read-then-ask orchestrator — one primitive replacing per-producer coverage+request boilerplate: probe computeCoverage, return 'covered', else open a grant_request and return { status: 'pending', hitlId }; coalescing is the gateway’s job, and it never mutates run state.

• issueDeclaredGrants — pre-authorize an automation with a grants: block — a *.hook.md / *.heartbeat.md / *.scenario.md declares capabilities + optional ttlSeconds / maxCalls in frontmatter and the engine mints exactly what an approve in the same context would mint, with no card.

  • Five materialization seams — hook fire (HookRunner), heartbeat tick (heartbeatWorker), workflow run (materializeDeclaredGrants, at every run re-entry, before the gate), schedule-time gate (scheduleWorkflow), and every pipeline invocation (handler-instrument, so a pipeline that never calls requestGrant is still covered)
  • Same scope, capped lifetime — scope from grantTargetOf(auth); ttlSeconds bounded to [MIN_DECLARED_GRANT_TTL_MS = 4 h, MAX_GRANT_TTL_HOURS = 720 h] at file load, default DECLARED_GRANT_TTL_MS = 24 h as a refresh cadence
  • Classification before write — classifyDeclaredCapabilities drops unknown, ungated and admin-only names per entry so their grantable siblings still get a row; never throws — a bad entry degrades to missing_grant at the tool gate
  • One engine-wide coverage window — every probe uses DEFAULT_GRANT_DEDUP_MIN_REMAINING_TTL_MS (2 h), so a 1-minute heartbeat writes ~1 row per 22 h rather than 1440/day
  • Two standing-scope consequences — maxCalls on a heartbeat/scenario scope is a per-refresh budget, not a total; and a dashboard revoke does not stick while the declaration is live (the file is the kill switch)
  • Visibility without a card — grant:created carries source: 'declaration', and omnislash doctor → Declared grants inventories every block and flags admin-only / no-approval-needed capabilities and cross-entry duplicates (an unknown name is Capability names’)
  • Trust precondition — the authority of a declaration rests on the constitution file being human-reviewed; a brain whose agents can commit their own constitution/ has delegated capability issuance to them

• Two-level authorization through one primitive — plan-level (checkGrants in the workflow-run handler) and tool-level (ToolsGateway) both call grants.authorize, so the two layers cannot disagree on visibility, exhaustion or the slack window.

  • Plan level — union of requiredCapabilities across task specs, missing → provisionGrants → run parked in awaiting_approval; a subsequent approve resumes, any partial or denial fails the run (rehab is binary)
  • Tool level — fail-fast, never blocking: deriveHitl(providesCapabilities) → require a non-empty grantScopesOf(auth) (else missing_auth_context) → authorize → on success consume(grantIds), on failure a structured missing_grant payload
  • Auth-derived remediation — the failure sentence names a path the caller can actually take: agent → hitl_request_grant, scenario-only pipeline step → requestGrant(ctx, …), bare principal (MCP bearer door) → hitl_request_grant for a standing subject grant, none of those → ask an administrator
  • Runtime escape hatch — hitl_request_grant is offered on every session and alwaysLoad: true puts its schema on turn 1; it asks for a gated capability after missing_grant and for one the role never listed (a refused tool, a missing shell) alike — and refuses, before any card, a request approving would not change: a capability whose every tool engine-tools.json switches off (no grant turns a tool on), or, from an MCP session, one that needs no approval (a subject grant authorizes gated calls, never adds a tool)
  • A grant widens the agent it covers — each turn segment’s effective capabilities are the role’s pinned capabilities: ∪ every capability on a live grant for the agent, its heartbeat, hook, scenario or role (GrantService.grantedCapabilities, same liveness as the gate; a principal’s standing subject grant authorizes but never widens), read by the MCP tool list, the API tool set, the Claude built-ins and the prompt; an approval’s tools appear on the agent’s next step and leave when the grant expires or is revoked. Ungated capabilities on a grant widen without ever consuming maxCalls
  • Capabilities prompt module — every agent not holding '*' whose ask a person can answer (not unattended, not a loop round or replay) is told what it could still ask for (catalog minus held, minus admin-only, minus memory:* without a memory block; on Claude, the built-in groups it lacks) and to ask rather than make a person do the work; with-capabilities.md, overridable, priced on /context as Requestable capabilities
  • Partial approval semantics — the agent producer degrades gracefully (issue the approved subset + partial prompt), schedule_* issues with nothing to resume, pipeline resolves the awakeable with the subset, workflow rehab fails the run

• Grant producers, catalogued — schedule_manual, schedule_cron, workflow rehab, agent runtime escape and pipeline reach a grant through a human approve; declaration, bootstrap (boss start) and admin / admin_extend (a person on the dashboard) bypass HITL entirely; command (since 1.24.0) is grant_create / grant_extend called by anyone but the dashboard — an agent’s call waits on the governance:write card. Only admin / admin_extend can issue an admin-only capability; command never issues governance:write (the gate on its own card); a Boss run’s own grant is refused to grant_extend / grant_revoke; a subject scope only those and a HITL approve whose card names it.

• Grant administration — the grant.* engine ops (tools grant_*; reads governance:read, writes governance:write — restricted, HITL, granted to no role by default). grant_list (since 1.23.0) reads the standing grants: filtered by computed status active|expired|revoked|exhausted, by one entity, by feature (the grants of the entities it ships), by one session (agentId) and (since 1.24.0) by capability and scopeKind, sorted newest / ending / used, keyset-paged, each row with its derived status and its holder’s name — the agent’s for an agent scope and (since 1.25.0) the scenario’s for a scenario scope —, plus facets that each count under the other filters: counts per status, byScopeKind per holder kind and expiringSoon (active, lapsing within the hour). Since 1.24.0: grant_get is one grant in full — the request that minted it (with its status), its holder as a ref (the entity; session: for an agent scope; person: for a person’s) and replacedBy once it was extended; grant_list_declarations lists every grants: entry of a scenario, heartbeat or hook (inline hooks included) with the row it minted; grant_create issues a grant for any holder (dryRun answers the row and what it widens — the capabilities that wait for approval today, any admin-only one), grant_extend replaces a live, lapsed or used-up grant atomically with more time or calls (a revoked one stays ended), grant_revoke ends one (id) or up to 50 (ids), the record kept. An agent (source command) can never grant an admin-only capability or a person’s whole principal and gives at most 720 h; the dashboard (source admin) can. Each write is one action-log row against its holder or its grant.

• Standing delegation without an agent-visible ask — loop:auto_accept is a capability no tool provides: the loop reads it with grants.authorize and, absent a grant, always degrades to the human Accept card; being admin-only is what keeps an agent from requesting removal of its own oversight.

• Prompt-injection defense on external content — wrapExternalContent / wrapWebContent fence untrusted text (emails, web pages, webhook bodies, tool results marked externalContent) with cryptographic boundary markers, strip invisible characters, fold fullwidth/homoglyph angle brackets that could spoof a marker, and log detectSuspiciousPatterns hits without blocking the content.

• SSRF protection on outbound fetches — a guarded undici dispatcher blocks private/link-local IPs, validates DNS resolution and re-checks across redirects on web_fetch, remote-media fetches and outbound dispatch deliveries.

• Agent filesystem sandboxing — path containment and repo-boundary enforcement for file operations, with bwrap-based isolation for jailed dispatch (agent-isolation ladder is the agent-runtime domain).

• Secrets stay out of committed config — omnislash.config.ts never imports env; secrets and private values are read through env.* inside packages/apps, so the config file is public committed brain code.

  • Per-skill env is filtered — collectSkillEnvVars gathers declared requires.env values for the child process, and isDangerousEnvVarName blocks PATH / LD_PRELOAD / NODE_OPTIONS / HOME and friends into a reported blocked[]
  • Token redaction — a token embedded in a skill source URL is redacted from every error message before it can reach a CLI or CI log
  • Chat-bound error scrub — scrubForChat (@omnislash-ai/utils/security) rewrites URL credentials, auth headers, bearer tokens, sk-/gh*_/xox*/AIza keys and JWTs, redacts every whitespace-free process.env value of 12+ chars as [redacted:VAR_NAME], then truncates at 1000 chars
  • Admin surfaces are token-gated — MCP_ADMIN_TOKEN (≥32 chars, SHA-256 + constant-time compare) gates /admin/sessions, and artifact_publish refuses private publishing unless ADMIN_USER + ADMIN_PASS_HASH are configured

• Agent DB access with schema isolation — db_schema / db_query / db_execute let agents work with the brain database while PG-level search_path=public keeps engine tables (omnislash.*) invisible without explicit qualification. Introspection is the deliberate exception: db_schema reads the catalog across public + omnislash and tags every entry with its schema, because an agent that cannot see the engine table cannot learn to qualify it — the isolation is about what resolves unqualified, not about what is knowable.

  • A table states what its rows are, not only what shape they have — db_schema carries each relation’s own DB comment through as note. omnislash.agents uses it to say the one thing its column list cannot: it is a sliding retention WINDOW, not a journal. The sweep runs in the pipelines service (so services.pipelines: false stops it) and removes rows in TWO phases: hb:% / hook:% rows are hard-deleted outright once idle past agentRetention.ttlHours, while transient rows (run_in <> 'live', thread:%, or an agent-spawned row whose parent is gone or tombstoned) are first TOMBSTONED and hard-deleted one window later — so a tombstone is on disk for up to TWICE the window and every “live agents” query must say deleted_at IS NULL (the column carries that as its own comment). Only live non-thread chat agents, the loop’s own agents and agents holding a resource watch outlive the window at all. Rows older than it do not exist, so “first occurrence”, “only case in N days” and per-beat run coverage over a wider window are all unanswerable from this table however confidently the SQL returns. Fingerprint history belongs to a durable source (a memory line, Loki, BullMQ). The prose owner named in that comment is packages/infra/src/queries/agents.ts (softDeleteIdleTransientAgents, findExpiredAgentIds, hardDeleteAgentsByIds) — drizzle-kit models no COMMENT ON, so the two move together by hand.

• Chat access is governed like any other write — who may use a bot is constitution/access.yaml, edited by agents through access_update (access:write, no approval: it refuses any change that widens access) and access_widen (access:widen, hitl: true: admitting people, serving or opening a chat, granting members commands or capabilities — the owner approves the exact edits), read through access_overview / access_identities / access_explain (access:read); owner is a global tier no code can mint, and HITL approvals stay owner-only wherever the card hangs — chat-access.md

• Infrastructure endpoints behind a grant — internal service URLs (Prometheus, Loki, Grafana, DB, Redis, Bull Board, Restate UI) are only reachable through infrastructure_endpoints, whose infrastructure:discover capability is restricted + hitl: true; the public boundary (endpoint_list / endpoint_get, runtime:read) never names an internal host or port.

Cascade Planner

• Staged planning pipeline — planning is split into up to 12 focused LLM stages instead of one monolithic call; each stage gets an agent, reads only the files it needs, emits structured JSON, merges into PlanningState and rewrites blueprint-state.json for the next stage
• Stage inventory
  • 1 — Analysis — extracts slug, goal, successCriteria, assumptions, ambiguities, priority, researchNeeded and an optional inputSchema; an optional stateOverview is appended to scenario.md
  • 2 — Clarification (interactive, optional) — up to 4 questions in 2 rounds, asked only when the answer would change task structure, then rewrites the analysis so downstream stages see only the post-clarification version
  • 2.5 — Research (conditional) — codebase/filesystem/DB enumeration producing summary, enumerations and keyFacts, run with elevated capabilities (agentCapabilities: ['*']); included always / never / runtime-skipped by PlanningOptions.research, with a stub written on skip so downstream inputFiles always find a consistent shape
  • 3 — Deliverable — decides description, filename, format and schema; scenario config can pin format as a HARD CONSTRAINT, and storage is injected by assembly rather than chosen by the LLM
  • 4 — Decomposition / Task Extraction — Cascade decomposition into primitive tasks, or direct extraction from scenario text when decompose: false
  • 5 — Decomposition Review (interactive, optional) — the user confirms or revises the task list
  • 6 — Capability Mapping — assigns domain:capability strings plus a rationale per task
  • 7 — Task Refinement — adds definitionOfDone and the optional flag per task
  • 8 — Context Group Assignment — assigns contextGroup (or independence) and compactAfter per task
  • 9 — Phase Organization — organizes tasks into sequential phases; the merge enforces that every task appears in some phase or throws RetryablePlannerError
  • 10 — Artifact Planning — assigns outputArtifacts filenames for cross-group data flow (deliberately exempt from the coverage check)
  • 11 — Final Review (self-correction) — a separate reviewer model reads a pre-assembled blueprint and may correct only contextGroup, compactAfter and outputArtifacts — no task creation, deletion or other field edits
• Progressive task enrichment — tasks start as {id, title, description, recommendedSkills?} from stage 4 and accumulate capabilities → definition of done → context groups → artifacts → final corrections, with assertTaskCoverage() guarding every id-keyed enrichment stage
• Two-phase execution for interactive stages — an interacting turn runs with no outputSchema so the model can call AskUserQuestion without JSON-mode bias, then auto-transitions to a producing turn that emits the structured output
• Auto-recovery — every stage but clarification carries a validate(); a failed validation fires onRecoveryAttempt, clears the stream namespace, sends a correction prompt and re-runs the same agent once, tracking the outcome on the session
• Retry with progress preservation — a RetryablePlannerError sets retryPending and reports; retryLastStage() re-runs from the failed stageIndex with all prior stage files intact
• Session persistence — PlanningSession owns all mutable state and persists to Redis (planner:session:<id> + planner:meta:<id>, 24h TTL refreshed on save) after every stage transition, so a worker restart resumes via PlanningSession.fromSnapshot(); the snapshot shape is Zod-validated on load
• Configurable pipeline shape — clarification, decompose, review and research flags select which stages are built, changing pipeline length and the number of agents created
• Agent groups — stages sharing an agentGroup share one agent (capability mapping + task refinement share enrich); all other stages get a fresh agent with role system:planner and default capabilities ['file:read', 'research:read']
• Model selection & overrides — resolution order stage.modelRef > session modelRef > planner role modelRef > system:general; final review pins the reviewer model
  • Session model override — planning.modelRef overrides the planner agent model for a single planning session from chat, without changing defaults
• File-based stage IO — each run gets a temp /tmp/planner-XXXXX/ workdir holding scenario.md, blueprint-state.json, the numbered per-stage outputs and assembled-blueprint.json; preserved across retries, cleaned up on completion, with opportunistic sweeping of planner-* dirs older than 2 hours
• Blueprint assembly & validation — assembleBlueprint() hydrates PlanningState into a full Blueprint (injecting storage, execution and loop config), then validateBlueprint() runs Zod plus business rules (unique task-N ids, non-empty context groups, capability-string refinement, deliverable filename present in artifacts, traversal-safe artifact filenames)
• One-shot planner — a single prompt → single structured output → Blueprint path for simple scenarios, with retry + recovery resilience (up to 2 retries × 2 recoveries) and no stages, Redis state, interactive mode or resume
• Planner registry & introspection — createPlanner(method, deps) plus isValidPlannerMethod() / listPlannerMethods() back the scenario method picker; PLANNER_EXECUTION_MODE splits legacy in-process methods from Restate-durable ones so a new durable planner auto-routes
• Planning cancellation — an AbortSignal per session threaded through runAllStages (checked at stage boundaries) and into the in-flight agent.call, driven cross-process by planner:cancel.requested → planController.cancel(sessionId); the planning queue runs attempts: 1 so BullMQ cannot resurrect a cancelled session
• Live planning cards — PlanningChannel reduces planner:session.started / stage.started / stage.completed / blueprint.ready / session.failed / session.cancelled into a Redis planning:session.snapshot (schema-validated on read, active vs terminal TTLs), which chat and dashboard render as a live progress card with the current stage, questions being asked, and the assembling plan. The planning.* engine ops (since 1.23.0) read and stop them: planning.list({ status: 'active' | 'recent', id? }) (planning:read — the live sessions, the ones that ended in the last 24 h, or one session by id whichever it is), planning.cancel({ id }) (planning:write, recorded against the planning session — asks the planning worker through planner:cancel.requested; an ended session is refused) and planning.list_methods (planning:read — the methods a scenario’s planner.method names)
• Planner HITL — planner-stage questions ride the unified HITL gateway with context.planningSessionId; responding re-enqueues the stage agent with the answer, and multi-round questions work because each respond is a fresh enqueue against the same CLI session
• Free-text execution overrides — plain-language tweaks to how a plan will run (priority, PR, timeout, model ref) are LLM-parsed into a typed ScenarioExecutionOverrides payload, validated (parseAgentRef for the model ref), echoed back for confirmation and applied at launch
• Prompt corpus — every stage prompt is a brain file under constitution/Planner/Methods/Cascade/Stages/, with a separate one-shot prompt directory, so a brain can override any stage’s instructions

HTN Planner

• Real hierarchical task-network planner — a third planner method (htn) doing genuine recursive, data-dependent decomposition into typed nodes, run as the durable Restate service planning-run in apps/pipelines; it produces the same Blueprint contract as the legacy planners, so downstream execution is unchanged
• Selection — set method: htn in the scenario’s planning options; the planning worker routes Restate-planner methods to triggerPipeline('planning-run', …) while cascade / one-shot stay on the in-process controller
• Node model — five concepts, nothing more
  • Typed nodes — every node is compound (must be decomposed) or primitive (a directly-executable BlueprintTask)
  • Method with rationale — a compound node records the rationale of the decomposition it chose plus the excluded rationales already tried and rejected
  • Recursion to primitive — children replace a compound node until every leaf is primitive; the loop terminates on that invariant, not on the model declaring itself done
  • State-gated applicability — each decompose call receives the threaded plan state (ancestor goals + already-decided preceding-sibling specs + the frame), so the same goal decomposes differently under different accumulated context
  • Subtree-local backtracking — a reopen re-decomposes exactly one parent’s subtree with the failed method excluded; siblings and ancestors are untouched
• Two LLM steps only — a Frame step (slug, goal, assumptions, questionsForHuman, successCriteria, deliverable, optional inputSchema, rootGoal) and one Decompose call per node; capability mapping, DoD and artifacts are emitted by the primitive-emission step itself
• Deterministic tree → Blueprint linearization — series-parallel composition maps the tree onto the 2-level Blueprint with no LLM phase stage: a primitive leaf becomes one task, a sequential node concatenates its children’s phases, a parallel node merges them by index
• Bounded by construction — maxDepth and maxNodes force a node primitive at the bound and a per-node reopen cap stops a pathological decomposer, so the loop always terminates
• Durable, journaled decomposition — every LLM call is its own runAgent durable step, so a crash resumes from the journal without re-issuing completed decompositions; node ids are derived from tree position (never random) so the tree rebuilds deterministically on replay
• Inline HITL clarification — a node can suspend the same invocation on a Restate awakeable via askQuestion and resume when the user answers
  • Explicit routing — engine built-ins are served raw with no handler ALS, so the handler reads surface / subjectId off its durable input and passes them explicitly, keeping the card in the originating chat instead of the owner fallback
  • Answers change the plan — the answer is folded back into the scenario text and runFrame re-runs, so the resolved ambiguity actually reshapes the plan rather than merely unblocking it
  • Bounded multi-round — MAX_CLARIFICATION_ROUNDS caps the loop; past the cap planning proceeds with whatever frame survived
  • TTL-bounded card — a journaled expiresAt (CLARIFICATION_TTL_MS, computed once inside ctx.run for replay determinism) lets the reconcile worker sweep an unanswered card to terminal failed with no person present
• Real cancellation — the method-agnostic planner:cancel.requested event is honored on both paths; for htn the worker resolves the live invocation from sys_invocation by idempotency-key = planSessionId and issues a graceful admin cancel, the handler catches CancelledError and emits planner:session.cancelled, and cancelPendingClarification sweeps the pending card so a late answer no-ops against its CAS
• Self-emitted, journaled observability — engine built-ins bypass pipeline auto-instrumentation, so the handler emits planner:session.started, planner:stage.started/.completed per decomposition node, planner:blueprint.ready, planner:session.failed and planner:session.cancelled itself, each inside ctx.run so a replay cannot re-fire and corrupt the order-sensitive PlanningChannel snapshot
• Structured-output wire encoding — the decompose schema (HtnDecomposeSchema) is a flat root z.object() with a kind enum discriminator and .nullable() branch fields, because a z.discriminatedUnion renders as a root-level oneOf that both Claude and Codex reject; parseDecomposeResult validates the flat shape and narrows it back to the discriminated union, rejecting a branch missing its required field
• Brain-owned prompts — constitution/Planner/Methods/HTN/frame.md and decompose.md, mirroring the cascade stage prompts, with a working set shipped in the engine’s dev brain

Workflow System

• Restate-native run engine — a workflow run executes as a workflow-run Restate Virtual Workflow keyed per attempt (${runId}::a${n}), the single durable owner of the run
  • Sole writer — the EXCLUSIVE run handler is the only writer of workflow_runs + workflow_task_runs; the agent VO stays sole writer of agents and the run only READS agents.status
  • Crash-resume is free — a worker/pipelines crash mid-run is Restate journal replay, not a recovery path; every DB write is a journaled ctx.run step
  • live_attempt claim CAS — claimLiveAttempt(runId, attempt, {stealFrom?}) admits at most one attempt across distinct attempt keys (Restate’s per-key lock cannot span them); the loser no-ops instead of becoming a second writer
  • Release-at-seam — releaseLiveAttempt clears the claim at the single runBody() return seam on terminal AND resumable returns, so the next attempt finds a clean slate; a killed attempt’s stale claim is taken over by a value-named stealFrom recover
  • Terminal-CAS clamp — the only remaining CAS on normal writes: transitionRunStatus(ACTIVE_EXECUTION_STATUSES, derived) stops a lagging projection resurrecting a clamped-terminal run
• workflowRunClient — typed ingress API — every driver (worker, dashboard, mcp, chat, scheduler, pipelines) reaches the handler through one client keyed on the stable runId
  • submitFresh(scenarioId, createdBy, runConfig?, opts?) — mints runId + slug and submits attempt a1; opts.delay schedules via a Restate timer, opts.idempotencyKey dedups the run row via a partial-unique index
  • submitAdhoc(...) — the fresh attempt of an ad-hoc run: a plan made from an inline brief rides the create input instead of a .blueprint.yml, keyed by its planning session
  • submitResume(runId) — new attempt from any RESUMABLE_EXECUTION_STATUSES, re-driving off DB-projected progress (skips completed phases, re-attaches live agents); the single choke point where a pending interception HITL row rejects with RUN_INTERCEPTED
  • submitRetry(runId) — new attempt from failed; the handler’s failed → running CAS is the single-winner guard, so concurrent retries run the agent exactly once
  • requestStop(runId, reason) — drives the control channel; returns { acted } so a pause against a no-live-attempt orphan stops reporting a false “Paused”
  • status(runId) — live derive-on-read status of the in-flight attempt, null when none is live
  • resumeForRecovery(runId, stealFrom?) — deliberately ungated re-drive used only by the deterministic orphan reconciler
  • enqueueWorkflow* facade — result-shaped adapters (enqueueWorkflowExecution / Resume / Retry / Redrive) over the client for HTTP / tool / dashboard callers
• Ad-hoc runs from an inline brief — a planning job with source: 'brief' plans the brief with nothing read from or written to the brain; once planned, the plan starts one run with no scenario (scenario_id null, the executions row with no entity) that keeps the brief and a title. It is never graded and never feeds the loop — it belongs to no entity. A capability grant it needs is asked by the task agent at its tool gate and approved for that agent only, never as a standing grant for the requester. The plan card says the run started instead of offering a schedule. In this release nothing produces a brief job yet: the bot’s /plan still writes a features/adhoc/ scenario and shows the schedule card, and moves to briefs in the next release
• Phase execution model — tasks are grouped by phase number; phases run sequentially, tasks inside a phase run in parallel
  • Context groups — a named contextGroup runs its tasks sequentially on one chained shared agent; contextGroup: null gives each task its own agent in parallel. Distinct groups and ungrouped tasks all race concurrently
  • Cross-phase agent chaining — the agentMap is built once per run, so a named group keeps the same agent session across phases; buildAgentMap() reconstructs it on resume from completed tasks (last completed per group wins)
  • compactAfter — a blueprint task can request agent-context compaction after it completes, before the next task in its group — a compaction turn queued on the group’s shared agent ahead of the next task
  • Optional tasks — optional: true failures don’t fail the phase or the run; the group continues with a fresh agent (the chain breaks at that point)
  • currentPhase persistence — advanced on phase completion; a resume skips phases below it
• Derived run status — run status is computed from the lifecycle marker + task rows, never stored independently
  • Priority order — first match wins: all required tasks completed (optional ones settled) > cancel clamp (outranks a failed task) > a required task failed > pause clamp (never masks a failure) > awaiting_approval > awaiting_input > running > pending
  • Journaled lifecycle marker — run / pause / cancel lives in the attempt’s Restate journal state (ctx.set(LIFECYCLE_KEY)), not a column; it clamps the bottom-up rollup so a sibling completing during a pause re-derives to paused
  • awaiting_retry is explicit — set by the handler at the phase aggregate through an ACTIVE-guarded CAS, not derived
  • PR-finalize hold — a pullRequest: true run is held off completed while its finalize window is open; the hold is required and threaded to every projection, and intent-aware (a pause mid-push projects paused, never a terminal that would drop the PR)
• Model B suspension semantics — every pause / awaiting_* state RETURNS the attempt instead of holding a durable invocation open; resume is a fresh attempt key that re-reads DB-projected progress, which is what lets a run wait days on a human without pinning a sandbox or a permit
• Control channel — pause / cancel / interrupt — a durable resolve-once control promise per attempt, raced inside the phase loop
  • pause — sets the lifecycle clamp and returns paused with task rows untouched (running stays running); resume re-attaches live agents off agentId
  • interrupt (graceful) — drops control and runs to the next phase boundary, then pauses; it never stops an in-flight agent, and a single-phase run absorbs it into completed
  • cancel — lifecycle clamp + stopRunAgents + applyWorkflowCancel terminal-CAS + pending-HITL cancel, emitting workflow:run.cancelled exactly once
  • a0 clamp attempt — cancelling a non-live (paused / awaiting) run submits a reserved kind:'cancel' attempt on key a0 that runs the terminal cascade directly; concurrent cancels dedupe onto it
  • Agent teardown, two layers — stopRunAgents invocation-cancels every live task agent (and the named PR finalizer) and awaits their honest terminal rows; the agent VO’s run-liveness guard-on-wake independently self-aborts any turn whose owning run is already terminal, covering the startup-transit / backing-off / re-attach windows the scan misses
• Task dispatch & the observe seam — the handler decides per task from the row’s agentId: completed → skip, no agentId → dispatch, bound agentId → re-attach without a duplicate dispatch
  • Run-owned awakeable — a dispatched task fires a fire-and-forget VO turn carrying pipeline.callbackId; the VO resolves the awakeable on terminal AND on awaiting_input, so a HITL pause arrives event-driven
  • One deterministic race — observePhase runs a single RestatePromise.race per loop turn over each advancing group’s awakeable, a shared ctx.sleep(500ms) poll tick, and the control promise
  • Journal is O(transitions), not O(elapsed) — the poll tick is armed only when a re-attach group (no live awakeable) is advancing, so a long continuously-running phase suspends with zero per-time journal growth
  • adoptTask re-attach — a HITL wake CASes the task awaiting_input → pending keeping its agentId; adoption marks it running (no task.started re-emit) so the run column doesn’t lie and downstream from-guarded CASes still match
• Post-completion pipeline & task auto-recovery — settling a completed agent runs save-task-result → artifact validation (DEFAULT_CHECKS) → complete, or one dispatchRecovery re-prompt (emitting workflow:task.retried), or fail
• Failure resilience — categorized errors with bounded retries at every layer
  • RetryableError → awaiting_retry — a retryable agent failure exits the phase carrying retryAfterMs + category; a fresh attempt resets non-completed tasks and re-drives
  • Bounded setup — pre-mark-running setup steps (prepare-read / read-slug / mkdir-artifacts / setup-sandbox) are bounded by SETUP_RETRY and settle the run failed on exhaustion instead of being silently killed
  • Per-task timeout — executionConfig.taskTimeoutMs is an optional per-task safety-net timeout declarable in scenario frontmatter and carried on the blueprint
  • Terminal-FAIL seam — both failure terminals (required-task phase fail, PR-finalize fail) route one finalizeRunFailure seam that stops live agents, cancels pending HITL and emits the terminal, so they cannot drift on cleanup
• Per-run sandbox — the run creates and owns a kind:'run' worktree checkout whenever a brain baseline exists; a single idempotent cleanup-run-sandbox chokepoint fires on terminal return or escape-throw and is deliberately skipped on a resumable return so the resume re-clone lands in the same path-stable checkout
• Engine-managed Pull Request finalize — with executionConfig.pullRequest: true the engine opens a finalize window after the phase loop rather than letting the planner decompose PR creation
  • Tracked finalizer agent — a deterministic pr-finalizer-<runId> slot dispatched through the same enqueue+awakeable bridge as a task agent, so replay reattaches one slot and a cancel reaches it by name
  • Honest-failure contract — prFinalizerOutputSchema (Zod-derived, flat outcome discriminator) returns {prUrl, prSummary} or failed + reason; the engine validates the URL and fails the run rather than completing with a null prUrl
  • Safety rails in the prompt — refuses to push the default branch, commits uncommitted work as a safety net, then git push -u + gh pr list/gh pr create
  • Planner directive — PR_PLANNER_DIRECTIVE is injected into the Cascade / one-shot prompts so the planner emits no “create PR” tasks that could push a different branch
  • Not shared by the loop — the loop’s implementer opens no PR of its own; the engine lands the gated files and opens the PR itself (createPr, @omnislash-ai/git-ops), so no agent ever holds the gh token there
• Entry points — every trigger converges on the same handler; fresh runs ride a durable BullMQ trigger inbox, control verbs call the client directly
  • Telegram schedule card — Now / Tonight / Custom time / Cancel / Delete, with grant pre-check and input pre-collection before enqueue
  • HITL gateway dispatch — grant-rehab approval resumes the run, input_request response re-enters submitFresh with collected input, schedule-side approval re-runs collectInputOrEnqueue
  • Cron — schedule: frontmatter on the scenario file, reconciled into cron-{scenarioId} BullMQ repeatables; workflowTriggerWorker bridges to submitFresh with a defensive gate that reaps schedulers leaked past a disabled scheduler
  • scenario_start (run:execute, since 1.23.0 — replaces the two engine-specific start tools; brain-dev-guide.md § Renamed engine names) — one start for either engine: id + optional input + optional idempotencyKey (pipeline only: service, default the scenario id — its primary — or an auxiliary <id>-<suffix> service one of the scenario’s own *.pipeline.ts registers, any other refused invalid; handler, default run; and key, default the primary’s pipeline.targetKey; the input schema and the input request are the primary run handler’s); refused for a scenario that does not load or is switched off (itself or by its feature — the scheduler brake stops clocks only). A scenario that declares input fields (a workflow’s blueprint; a pipeline’s inputSchema, for its run handler), started without input, opens the input request instead of running and answers inputRequested: { requestId } — the run starts when a person answers it; a keyed call never parks on it (a keyed input-less workflow starts with {}), and on a workflow it is idempotent per scenario for the life of the run row — a repeat answers the existing run with existing: true. Fire-and-forget: it answers run: { id, kind, existing } and does not wait (a pipeline that waits on the run uses runWorkflow); a pipeline’s id is the Restate invocation id, its run row appears as the handler starts
  • Dashboard tRPC control plane — run.pause / run.cancel / run.resume / run.retry / run.recover (the run.* ops, one guard set with the tools and the Telegram card) and scenario.start
  • scenario_plan (planning:write, since 1.23.0 — one tool for the in-process planner call and the planning job) — one planner door: dryRun: true plans now, in-process (Cascade, person-facing stages off, the planner’s 5-minute timeout) and answers the blueprint with its diff against the plan file — from the scenario (id, the same planner input the planning job builds) or a goal no scenario holds (brief); a commit (id) queues the reconciler’s own auto-plan-<id>-<hash> job so a manual re-plan coalesces with the automatic pass, and answers its planningId. Planning ignores enabled; a locked plan is refused on commit; a pipeline scenario has no plan
  • Scenario ops (since 1.23.0) — scenario_get (feature:read: the switch in words — own, effective, heldBy —, the engine, the schedule in words with the next fire, the frontmatter as written and the body, the owned files — definition, .blueprint.yml, *.pipeline.ts —, the plan’s state, the inline hooks; a file that does not load answers scenario: null + broken), scenario_read_file (one owned file with its sha), scenario_update (feature:write, the scenario’s typed keys — name, description, enabled, schedule, skills, agent, chatbot, inputSchema, planning, execution, deliverable, pipeline, the body — never budget / evaluation / inline hooks), scenario_write_file (the definition or an owned file whole: a .blueprint.yml validated as a run reads it, a *.pipeline.ts size-checked, taking effect on the next pipeline build), scenario_widen (feature:widen, a person: the update / write that adds to the scenario’s grants:), scenario_delete (the definition, its blueprint, its pipeline modules and its loop module <id>.loop.ts). Every write is D30 (dry run → diff, grant delta, consequences → commit on the dry run’s sha): a change of schedule / enabled queues the schedule reconcile (scheduleReconcile), switching a pipeline scenario off or deleting it kills its live runs (liveRunsKilled, counted on the dry run), a delete names the inline hooks and the clock it takes (inlineHooksRemoved, scheduleRemoved)
  • A pipeline scenario’s handlers (since 1.23.0) — scenario_get answers pipeline for a pipeline scenario: its Restate primitive, the key a keyless start uses (targetKey, the scenario’s pipeline.targetKey) and each handler with the key it needs and the input it takes (the run handler’s falling back to the scenario’s inputSchema) — what scenario_start’s handler, key and input name; null when the module does not load. Every entity get (scenario_get, heartbeat_get, hook_get) also answers the id it was asked for, so a file that does not load still names its entity
  • Blueprint ops (planning:*, since 1.23.0) — blueprint_get (a scenario’s plan file — YAML, sha, lock, freshness, the verdict a run acts on, the task specs — or, with run, the snapshot that run froze), blueprint_list (every workflow scenario’s plan with its state, phases and tasks; complete), blueprint_write (a structured plan, refused while the plan is locked, or raw YAML, which locks it — consequences.locksBlueprint; validated as a run reads a plan, invalid with each issue at its field), blueprint_set_lock, blueprint_delete (the plan file only)
  • Blueprint freshness — the planner stamps scenarioHash into every plan it writes, and resolveBlueprintFreshness turns that into current / stale / unknown (no stamp, or no scenario file). Surfaced by blueprint_get, which is what makes the plan→poll→execute loop terminate: after an edit the OLD plan is still on disk and answers instantly, so stale is the only signal the re-plan has not landed
• Workflow input parameters — a blueprint may declare inputSchema (JSON Schema); provided input is validated and injected into every task prompt
  • Pre-run input HITL — collection lives inside submitFresh, the point every fresh entry converges on: an input-less submit on a field-bearing blueprint opens a producer='workflow' kind='input_request' interaction and returns { kind: 'input_requested' } without creating a run row
  • Typed forms, not free text — the collected schema is rendered as a typed form in Telegram / dashboard; free-form replies are parsed by InputSchemaTranslator
  • Delay survives collection — a delayed submit stamps targetTimestamp and the response side re-derives its submit delay
• Blueprint-level authorization — the handler’s grants gate (checkGrants → provisionGrants) blocks the run to awaiting_approval before any sandbox or agent work, using the same grants.authorize primitive as the runtime tool gate (grants/HITL mechanics owned by the policy layer)
• Workflow Q&A during execution — an agent question mid-run parks the task awaiting_input and the run returns; answering through the HITL gateway wakes the same agent in place and a fresh attempt re-attaches to it — resume never re-prompts a live task
• Self-healing runs (remediation dialogue) — a failed run (or a manual “Recover”) spawns a system:remediation agent that diagnoses the failure, patches the frozen blueprint and re-drives the run — failures become edits, not post-mortems
  • Outside the FSM — the run stays failed/paused/awaiting_input for the whole dialogue; only the agent’s run_retry call moves it
  • Agent toolkit — run_diagnosis (full root-cause report), AskUserQuestion, run_update_blueprint, run_retry
  • run_update_blueprint semantics — shallow top-level replace over goal / assumptions / successCriteria / phases / deliverable / executionConfig, with a hard invariant that every existing taskSlug must still resolve (task ids are immutable once a row exists; the tool rejects listing the orphans)
  • run_retry covers the whole recoverable triple — enqueueWorkflowRedrive dispatches on status (failed → retry, paused/awaiting_input → resume) so a Recover on a paused run is not a dead end
  • Attempt cap + slot idempotency — config.workflow.maxRecoveryCount (default 3) enforced inside the same CAS that bumps recoveryCount; recovery-<runId> is a unique name slot so duplicate triggers collapse to one spawn, and every leg that bails before dispatching refunds the claim
  • Lifecycle events — workflow:recovery.started / .completed / .failed, the last carrying a closed-world reason and the agent’s own final report (the only delivery path its diagnosis has); RecoveryNotifier posts only the failure
  • Triggers — automatic on workflow:run.failed; manually through run_recover (the dashboard’s Recover binds the same op) and the Telegram ”🛠 Recover” button — a workflow-recovery job deduplicated per (run, recovery count) while it waits or runs, so a double click or a redelivered request is one dialogue (a redelivered request whose crashed attempt took the slot but never created the agent resumes that claim rather than dropping it), and a Recover after a dialogue that ended without re-driving the run starts a new one; running runs must be paused first
• Orphan reconciliation (lost-run sweep) — a separate deterministic sweep that re-drives run rows nothing is going to advance, routed through the handler and never writing the row
  • Two candidate classes — running/pending whose Restate invocation is GONE (30-min indexing grace) and PARKED rows with no waker left (awaiting_input/awaiting_approval with no pending HITL row, plus awaiting_retry once its retry_at has passed — a run a money budget parked waits for the next local midnight — 2-min grace). paused is excluded: that suspension is the owner’s to end
  • Status-filtered liveness — sys_invocation retains a terminal attempt as completed for ~24h, so the sweep filters it out; otherwise a finished attempt would mask a genuinely lost run for the whole window
  • False-resume-proof — every candidate the service-wide batch misses is re-verified individually before any verdict, so a stale batch read skips rather than mass-resumes; skippedStillLive > 0 is always logged at info. The batch + recheck is the same classifier (classifyWorkflowRunLiveness) every reader of a run’s liveness uses, so the engine has one definition of “this row’s invocation is gone”
  • Three drivers — a ~5-min scheduler pass under withRedisLock, a best-effort sweep on pipelines startup, and omnislash workflow reconcile (dry-run by default, --apply, --json)
• Lifecycle events — the handler is the sole producer and each emit is journaled so it fires exactly once across replays: workflow:run.started / .resumed / .paused / .cancelled / .completed / .failed, workflow:phase.started / .completed, workflow:task.started / .completed / .failed / .retried, plus agent-side workflow:task.progress. Every workflow:run.* event carries the run’s scenarioId, so a hook can filter one scenario’s runs (filter: { scenarioId: '<id>' })
  • Ordering contract — an event fires after the ctx.run that produced the state it describes, so “if I see run.paused, the row says paused” is safe to rely on
  • Journaled terminal finalization — emitTerminal runs finalize-summary → finalize-deliverable → terminal emit → enqueue-eval as ordered ctx.run steps owned by the run’s sole writer, replacing the old lossy pub/sub worker subscriber that dropped finalization in restart windows and ran it once per replica
• Live run status card — a burst of task/run beats coalesces into one light findCardRunView(runId) read and renders the run handler’s projected row.status directly, so a reordered non-terminal beat can never resurrect a settled card (restart-safe, no in-memory seen-set)
• Workflow-scoped hooks — hooks: declared in scenario YAML fire only for that run’s events, auto-filtered by runId
  • Registry lifecycle — registered at attempt start outside ctx.run so a replay re-attaches, keyed-replace so replays never stack duplicates, unregistered only on terminal exits (resumable returns keep the subscription across a human wait), with a grace delay so the just-emitted terminal still lands
  • Available events — every workflow:* event carrying runId; frontmatter fields mirror global hooks plus a required id: and an inline promptTemplate (agent defaults to general)
• File-first blueprints — .blueprint.yml written next to the scenario is the single source of truth; no DB blueprint table
  • Frozen snapshot per run — blueprintSnapshot is captured at run creation and never re-read; task specs are derived in-memory from it by taskSlug via buildTaskSpecs / deriveTaskSpecFromSnapshot
  • Auto-plan reconciliation — BlueprintReconciler watches MANIFEST.yaml, scenario files and sibling .blueprint.ymls, hashing content (computeScenarioContentHash / computeBlueprintYamlHash) and enqueueing planning jobs on change, with recently-modified and stale-active-job guards
  • Run slug minted from the run id — deriveRunSlug gives <blueprint-slug>#<runId[0:8]>, unique by construction (no count(*), no TOCTOU) and stable forever, so artifacts/runs/<slug> and the wf/<slug> git branch stay valid
  • LLM-generated run title — a nullable human-readable title column alongside the slug
• Cost & usage analytics — per-task usage JSONB carries per-model token/cost segments; run-level costUsd is aggregated by summing segment costs across the run’s task agents, and rolls up per model / scenario / agent
• Tool metrics & run report — buildToolArtifacts backward-scans the agent output Redis stream, pairs item.started/item.completed by itemId and flags side-effect tools; RunReportBuilder.buildRunReport derives per-task and total tool counts into a RunToolReport
• Result summary — buildResultSummary produces a ~1000-char emoji-prefixed per-task summary (side-effect tool results > task result snippet > error) written at terminal by the run’s own finalize-summary step
• Run control tools — run_cancel, run_pause, run_resume, run_retry, run_recover (run:execute) and run_kill (run:kill, pipeline force-stop) act on any workflow (run_…) or pipeline (pinv_…) run by its id, with one guard set: the same request is refused with the same code and sentence from an agent’s tool, the dashboard and the Telegram run card — not_found, precondition (the run’s state forbids it, e.g. cancelling a finished run) or invalid (a verb the kind does not have: kill on a workflow, retry / recover on a pipeline). run_recover queues one keyed request per (run, recovery count) and returns at once; the dashboard’s run controls bind these ops
• Run read tools — run_list, run_get and run_summary (run:read) read every kind of run in one vocabulary — workflow and pipeline runs, heartbeat ticks, hook fires, evals and cycle steps — from the executions record: status (queued … cancelled, with needs_you / paused reasons), trigger, entity, parent and the run it re-runs. run_list filters by entity, feature (the entities it ships today), kind, status and a window (1h, 24h, today, yesterday, 7d, 30d, 90d, mtd, all, or wall-clock from / to with an optional tz — default 7d; the answer says the window it read) and finds a run by q (an id prefix, or text in its entity id, its entity’s name, a workflow run’s slug or title or a pipeline run’s slug); newest first, or sort oldest first, longest first or most expensive first; cursor-paged; an entity’s list holds its own runs and the evals and cycle steps about it, entity: "none" the runs of no entity. Since 1.24.0 a row says what went wrong as error: { class, head } (was errorClass): the failure class and its error head — the message reduced to its cause (ids, numbers, times, paths and quoted values collapsed), so two failures of one cause read alike (class:head is the cause’s fingerprint; written by every failure, filled for older failures on the worker’s first boot after the upgrade); startedBy lists the runs an agent started, fingerprint the failures of one cause, and group answers groups instead of rows — per entity (each with its run_summary figures — since 1.24.0 those groups carry live, spendUsd, evalPassRate and p50Duration — an entity’s median settled duration, null for a feature group — too), per re-run chain (rerun) or per cause (error, failures and give-ups) — each with its count and newest runs, newest group first. run_get takes a run id or a workflow / pipeline slug and adds the detail: a workflow run’s input, output (result summary, deliverable file), tasks (what the blueprint asks, definition of done, phase, result cut short) and progress, a pipeline run’s steps (each with its error class, journal entry and where its output is kept), Restate kind and key, stored input and result (each shown up to 4000 chars of JSON) and live Restate state, a heartbeat tick’s or hook fire’s agent turn (turn: its agent, role, model, result, error with its stack and category, failed tool calls, provider, exit code, job, tokens, cost and turns — absent for a skipped or gate-failed fire), every task and step’s start, end and agent; step (a task or step id) reads that one task’s result uncut and that step’s output value; reruns — the runs that re-ran it — and brainSha — the brain commit the run started on (a replay: its pinned commit), null when unknown; since 1.25.0 feature — the feature shipping its entity today (engine for a system: role), null for a run of no entity or of one no feature ships any more. run_summary takes the same scope and window (since 1.25.0 also status: only runs in those statuses — the runs still going with window: "all" count what runs now without reading the whole record) and answers its figures — runs, success rate, median duration, spend, each beside the window before — with the outcomes per hour or day, the duration distribution and the counts per status and kind; it says how much of the window is on record (honesty) and answers null, never 0, for what the record does not cover (spend over runs none of which is priced is null: unknown, not free). Runs started before the executions record existed (an engine before 1.20) are absent from run_list; run_get still reads a workflow or pipeline one from its detail row
• Run timeline (since 1.24.0) — run_timeline (run:read) lays runs out one lane per entity (a heartbeat that ticks every minute is one lane): each lane’s runs in the window (each run by its start and status, or — past 300 runs — counted per bucket of bucketMs, aligned on the window’s zone), its clock (cadence), its Late / Down now (marks, judged as health_entity judges them from expected_at) and its next fires up to ahead (24h / 48h / 7d; at most 300 — forecastFires is the total); beside the lanes what listens instead of firing (listening: every enabled hook on its event, scenario-inline hooks included, every live resource watch on its resource), the scheduled prompts that fire within ahead and the engine passes on a clock. feature narrows it to one feature, entity to one lane; honesty says how much of the window is on record
• Run trace, compare and history (since 1.24.0) — run_trace, run_compare and run_history (run:read) read inside one run of any kind. run_trace answers a tree of timed spans — a workflow’s phases and tasks, a pipeline’s steps, the runs it started, every request it waited on and every turn its agents billed (cost and tokens) — with one span per attempt of a retried task or step (attempt, attemptOf) and the back-off between them (a workflow task’s earlier attempts are kept by the reset that retries it, workflow_task_attempts), and honesty: the agents reaped since (their spans keep their timing, their cost the spend ledger’s), whether the ledger still holds all the run billed, whether turns were left out. run_compare aligns a run with another — by default the previous finished run of its entity and kind (against names any other) — by label path, with the deltas (duration, cost, tokens, status), the input diff leaf by leaf and the two brain commits. run_history is the run’s log: its agents’ transcript rows (only while each worked for the run — a step agent reused across runs or a tick’s long-lived agent shows this run’s work alone), the pipeline’s lifecycle events and Restate’s journal transitions in one order, cursor-paged, narrowed by log, agent or text; a request’s rows (its payload and answer) only for a caller holding hitl:read. A sub-agent the run’s agents spawned counts as one of its agents: its turns sit under its spawner’s span. The dashboard’s run log reads it (agent-observability.md § Reading a run)
• Re-run, purge and a run’s files (since 1.24.0) — run_rerun (run:execute) starts a finished workflow or pipeline run’s entity again — with the input the run started with or an edited input — as a new run linked by rerun_of (run_get lists it under reruns); the input is checked against the schema the entity takes now, which run_get answers as inputSchema; dryRun: true answers the input, its schema and what running it again does (sideEffects: the plan’s tasks, a pull request, the deliverable) without starting anything. A live run is refused (cancel or reset it first), as are an ad-hoc run and a scenario that is switched off; a heartbeat tick or hook fire passed to run_rerun or run_purge is refused invalid (it starts again with heartbeat_start / hook_start). run_purge (run:kill) drops a finished pipeline run’s journal from Restate to free its space — the run’s record, steps and log stay. run_files (run:read) lists what a workflow run produced — its deliverable (once completed), each task’s stored output artifacts with the task that produced them, its PR — and run_read_file reads one by its ref (text as utf-8, anything else base64, bounded at 2 MB: past it a text file is cut and a binary one comes without its content, truncated, its blob unread when its size is on record); only the run’s own recorded files are readable, never a path
• Pipeline reset — run_reset (run:kill): force-kill a pipeline run if it is still live, then start the same handler again with the full stored input; the new run’s rerun_of names the old one. The dashboard binds it as Reset on a live pipeline run, also over a selection of runs (one confirm); a finished run takes Run again (run_rerun) instead. A Restate workflow-keyed run is refused — a workflow id runs once — with the run_kill + scenario_start under a new key route in the refusal. The same reset is what the engine applies to a run a code change breaks under onCodeChange: restart (§ Durable Pipelines › Editing a live pipeline)
• Workflow inspection & execution tools (MCP) — scenario_start, run_list / run_get (every kind of run, below), run_diagnosis, run_update_blueprint, scenario_plan, blueprint_list, blueprint_get — each capability-scoped and routed through the tools gateway

Durable Pipelines (Restate)

• Code-defined workflows (Tier 3) — a brain developer writes flow control as a typed TypeScript Restate handler and inherits the whole engine runtime (agents, tools, skills, HITL, grants, memory, events, notifications, monitoring) as callable infrastructure; every step, branch and error handler is code rather than an agent’s decision
• Escalation path — a scenario starts Tier 1 ({id}.scenario.md only), gains a locked blueprint (Tier 2), then a {id}.pipeline.ts (Tier 3) with no configuration change; resolveScenarioEngine() picks the engine by file presence, overridable with execution.engine in frontmatter
• All three Restate primitives — restate.service (stateless), restate.workflow (bounded signalable run with ctx.promise + shared handlers) and restate.object (long-lived single-writer entity) are accepted as the module’s default export; the kind is detected structurally (detectPrimitiveKind) and stamped on every invocation row, and discovery/instrumentation/registration are uniform across them
  • Primitive decision guide — a documented decision tree (addressability, then lifetime), worked examples, and reference implementations in brain-example/features/{service,workflow,object,composite}-example/
  • Cross-cutting recipes — Virtual-Object token-bucket rate limiting and self-tail-calling cron, documented as compositions rather than new primitives
• Auto-discovery & registration — one loader (loadServedPipelineModules) takes the enabled pipeline scenarios, resolves {id}.pipeline.ts plus auxiliaries, dynamic-imports them and checks every discovery rule, collecting every failure rather than stopping at the first; a scenario with a broken module is left out and the rest is served (partial boot — chat and workflows never go down with a bad module); registerWithRestate() POSTs the deployment to the admin API with retry and force: true on reload, non-blocking so the service starts first
  • omnislash doctor --check pipelines (CLI Pipeline modules) — the same loader without a server: every enabled module imported and validated on the author’s machine or in CI, failing on any module that would not be served and warning on a module that reads env at import time; an engine-owned step of the generated CI and deploy gates
  • Pipeline build (runtime doctor check) — the live endpoint’s own verdict on its newest build, read from the record pipelines publishes: red while a module is not served (naming each module and its error, and what still serves), in doctor_check and on the dashboard; pipeline_list points an agent at it
  • pipeline_build_state (pipeline:read, the pipeline.build_state op) — the same record as data: serving / degraded / down, what serves and which modules did not load since when; unknown when no record could be read — never healthy
• Multi-pipeline per scenario — one user-facing scenario can own a primary pipeline (name == scenarioId) plus auxiliaries named ${scenarioId}-*, so a feature that genuinely decomposes into a fan-out service + per-id workflows + per-entity objects stays one scenario
• Hot reload in every mode (including production) — a *.pipeline.ts edit detected by ContentWatcher resets the scenario cache, closes the HTTP/2 server, re-discovers, rebuilds and re-registers with force: true; constitution JSON edits reload their own caches without triggering a rebuild. What is hot and what waits for a restart: contract.md § 2.1
  • Failed reload surfaced — a reload never takes a serving scenario offline: one breaking a scenario that serves now keeps the previous build serving, one breaking only scenarios not served anyway goes live without them; either way it records the failure (Pipeline build, the pipelines_build_failed gauge → Pipeline Build Failed alert); the next successful build clears it, and while it is recorded any scenario or FEATURE.md edit retries the build
• Pipeline SDK (@omnislash-ai/pipeline-sdk) — the brain-facing helper surface, each helper journaled through ctx.run, all working identically in all three primitives
  • runAgent / safeRunAgent — durable agent turns via a parent awakeable settled by the agent VO; runAgent throws TerminalError on agent failure, safeRunAgent returns the failure as a typed value (the safeParse mirror) for fallback / retry / branching
  • Typed structured output — outputSchema is a Zod schema: the model gets its JSON Schema, each constraint its provider refuses (.max(4), .regex(), .email()) said in words in the field’s description, and the answer comes back parsed and typed as structuredOutput; a missing or non-matching output gets correction turns — the same agent is sent the issues and its rejected output (outputCorrections: 1 → MANIFEST pipelines.outputCorrections → the call, 0 = none) — then throws terminal in runAgent and returns outputError in safeRunAgent; runtime-only shapes go through z.fromJSONSchema
  • runAgentWithFallback — cross-mode agent chains that advance on any non-completed status or on output failing the shared outputSchema once an attempt’s correction turns are spent
  • runWorkflow / safeRunWorkflow — a Tier-1/2 scenario as one durable pipeline step: launches the blueprint run (created by the pipeline invocation, idempotent on an optional key shared with scenario_start) and waits for its terminal across every attempt — parks on a person or a retry included; runWorkflow throws on a failed / cancelled run, safeRunWorkflow returns the WorkflowRunOutcome; cancelling the pipeline cancels the run; refused under ctx.loopLaunched
  • awaitApproval / requestApproval / awaitApprovalDispatch — blocking approval (suspends on an awakeable, returns the tapped actionId, supports custom action sets; the card expires after 168 h unless pipelines.approvalExpiresInHours or the call’s expiresInMs says otherwise) and detached approval (returns hitlId immediately for hook-driven follow-up)
  • askQuestion / requestGrant / requestInput — the other three HITL kinds, each awakeable-backed and typed
  • callTool — full ToolsGateway execution (authorization, rate limiting, risk-based HITL) with scenario and surface resolved from the invocation context; since 1.24.0 { role } makes the call speak as one of the brain’s roles — voice_send / voice_render in its speech: voice, a surfaceless delivery through its persona bot — while the step keeps its scenario’s grants (an unknown role fails the call)
  • notify — Telegram delivery with a precedence chain opts.surface (a delivery target the caller already holds whole, persona included — the escape hatch for RAW-served handlers that have no invocation context) → opts.chatId (persona borrowed from the status chat) → the run’s own chat picked by opts.to (ops, the default: the pipeline’s ops surface, else the invocation surface; invocation: the chat the run was started from, where its HITL cards go) → engine status chat
  • emitEvent — typed emission of any pipeline:* event onto the engine bus; emits nothing under ctx.loopLaunched
  • reportProgress — validated {percentage?, stage?, message?} written to pipeline_invocations.progress (replace, not append) plus a liveness heartbeat, emitted as pipeline:run.progress, and deliberately excluded from step rows
  • reportRunSummary — a synchronous ALS-only human-facing one-liner shipped on pipeline:run.completed; display metadata that is never journaled and cannot break determinism
  • subscribeResource / waitForResource — durably wait for events about a resource key (a PR, an issue, your own source’s key): subscribeResource(ctx, resource, { name, expiresAtMs, sinceMs?, policy?, createdBy? }) returns a subscription whose next({ timeoutMs }) answers { kind: 'events', events } or { kind: 'timeout' } — events recorded while the pipeline was busy elsewhere are handed over by the next next, nothing falls between waits; close() it in a finally. waitForResource is one open-wait-close. A timeout is mandatory, and an event is a signal to re-read the resource, never its state. Pipelines hear everyone, their own App included ({ authors: 'all', dropEcho: false } unless the policy says otherwise); the loop’s merge wait runs on it
  • kvGet / kvSet / kvDelete — PostgreSQL-backed persistent key-value storage namespaced by scope, with an optional expiresAt TTL, for cross-invocation state; kvSet / kvDelete write nothing under ctx.loopLaunched
  • recordSpend — books money the pipeline paid outside any agent turn (a metered API it called) on the spend ledger as a kind: 'external' row attributed to the invocation; recorded once across replays and retried writes
  • runtime() escape hatch — direct access to the injected DI bag (agents, toolsGateway, hitlGateway, notificationQueue, evalQueue, redis, kv, statusSurface, blobStorage, updateRunProgress, restateAdminUrl) for capabilities not wrapped in a helper
  • Restate re-export — the SDK re-exports @restatedev/restate-sdk as restate so brain and engine share one module instance and therefore one HANDLER_SYMBOL identity
• Per-handler input schemas (withInputSchema) — withInputSchema.{service,exclusive,shared,workflow,workflowShared}(schema, fn, opts?) attaches a Zod schema that becomes both the Restate ingress serde (validated at the edge, published in the admin JSON Schema) and the engine’s PipelineHandlerMeta.inputSchema used to render trigger drawers; an optional describe string becomes the owner-facing handlerLabel on the run card
• Handler serde + kind preservation — the engine re-wraps every handler for instrumentation, and rewrapPreservingOptions re-applies the original HandlerWrapper.{kind, options} through the matching SDK factory, so input serde survives and a VO shared handler is not silently downgraded to exclusive
• Declarative pre-run input collection — a workflow-primitive pipeline scenario declaring inputSchema in frontmatter gets a HITL form before the pipeline starts on the Telegram /run deep link, and an inline schema-rendered drawer in the dashboard; the handler signature is unchanged and no SDK helper is involved
• pipelineConfig.opsSurface — a named export beside default lets a pipeline declare the chat for everything it emits by itself (its live run card and every notify without a surface / chatId / to: 'invocation'; botId optional, the chief’s bot by default), winning over trigger meta and scenario surface and inherited by its child invocations (null declares the engine status chat); HITL cards, agents and tool calls stay on the invocation surface, so approval cards and ops notices can live in two chats. An unknown pipelineConfig key fails discovery
• Automatic causal-tree propagation — the engine wraps the handler ctx and injects trigger meta (rootRunId / parentRunId) into all six client methods, so child invocations spawned with plain ctx.workflowClient / objectClient / serviceClient (and their send variants) render inside the parent’s card with no manual wrapping
• Live agent progress in run cards — runAgent bridges the agent’s Redis output stream from the pipelines process (outside ctx.run, idempotent per agentId, self-stopping on turn.completed) and republishes non-terminal events as pipeline:step.agent_event carrying (pipelineId, runId, stepId, agentId), so tool calls and retries render as nested children under the step instead of one static line
• Durable observability tables — pipeline_invocations (one row per invocation across all three primitives, with slug, kind, objectKey, status, input/result/error, totalStepCount, progress, lastProgressAt (progress liveness), pause/resume/cancel timestamps), pipeline_steps (one row per user-visible ctx.run, with monotonic stepIndex, error class, duration, journal index and an agentId FK), pipeline_events (timeline audit trail written synchronously alongside the live emit) and pipeline_journal_events (1:1 mirror of Restate’s per-attempt failure timeline)
  • Best-effort vs durable split — step/event rows are best-effort (a DB failure is logged, never thrown), while run create/complete/fail are journaled ctx.run steps; Restate’s own journal stays the source of truth
  • Replay-safe step rows — persistence and step events execute inside the Restate ctx.run they describe, so a replay returns the cached result and produces no duplicates; an explicit retryPolicy deliberately yields one row per attempt
  • Large-payload blob offload — a step output over config.pipelines.blobThresholdBytes (64 KB) is written to pipeline-runs/<slug>/steps/ and persisted through BlobStorageRouter, stored as a StoredPayload blob ref; non-serializable values degrade to a sentinel rather than aborting observability
  • Derived current step — findCurrentPipelineStep(runId) computes the newest running step on the fly instead of storing a currentStepId, because RestatePromise.all legitimately runs several steps at once
  • Restate SQL mirror — on completion the wrapper journals one enrichment pass over sys_invocation / sys_journal / sys_journal_events, patching retry count, completion result, journal sizes, pinned/last-attempt deployment, parent invocation and flattened last-failure attributes, correlating Run journal indices onto step rows, and bulk-inserting journal events; failures are swallowed as enrichment, bounded by a 5s admin timeout and guarded against SQL injection
  • Query API — findPipelineInvocationById, findPipelineInvocationWithSteps, findPipelineStepsByInvocationId, findCurrentPipelineStep, plus typed Restate introspection wrappers (queryRestate, queryRestateInvocation, queryRestateJournal, queryRestateJournalEvents, mirrorRestateInvocation)
• Pipeline lifecycle events — pipeline:run.{started,completed,failed,cancelled,paused,resumed,killed,progress} and pipeline:step.{started,completed,failed,retried,agent_event}, auto-emitted by discovery-level handler wrapping so a brain pipeline gets them without writing any
• Lifecycle control tools (MCP) — scenario_start on a pipeline scenario (optional idempotencyKey, passed raw as Restate’s idempotency key: a repeat within the service’s idempotencyRetention answers the first invocation with existing: true; a Workflow run dedups on its key), pipeline_list, and the run tools shared with workflows (run_list, run_get — a pipeline run’s steps, Restate kind and key, stored input and live Restate state; run_cancel — graceful, compensation runs, cascades to nested invocations; run_pause, run_resume, run_kill — run:kill, dangerous, no compensation; run_reset — run:kill: kill, then a new run on the full stored input, linked by rerun_of) — all keyed on the DB run id, resolving the Restate invocation id internally, with PipelineLifecycle applying status CASes so pausedAt/resumedAt/cancelledAt stay in sync with Restate
• Deploy-spanning retries that end in pause, never kill — the endpoint sets DEFAULT_INVOCATION_RETRY_POLICY (maxAttempts: 70, 1s→60s backoff, ≈1h, onMaxAttempts: 'pause') for every service, object and workflow bound to it: a deploy’s endpoint gap is outlived, and a failure no retry fixes parks the invocation with its journal intact instead of destroying it. A service’s own options.retryPolicy replaces the default whole (Restate merges service options shallowly)
• Paused invocations surfaced — the orphan reconciler projects Restate’s paused onto the pipeline row (running ↔ paused, with the card’s pipeline:run.paused/resumed), and restate_invocations_paused{restate_service} feeds the critical Restate Invocations Paused alert, counting only pauses caused by an exhausted budget (a deliberate Pause is not counted). Every such pause of ANY service — a brain pipeline, an agent turn, a workflow attempt, an engine handler — is listed by runtime_overview (paused: service, key, failure, journal mismatch or not; summary.paused) and by the runtime doctor’s Paused invocations (doctor_check, the dashboard’s Doctor page) (runtime preset, beside Pipeline build), whose hint names the tool that ends each kind (run_resume / run_reset / run_kill for a pipeline, agent_stop for an agent turn, run_retry for a workflow attempt)
• Replay-stable agent dispatch — every agent turn a durable handler sends (runAgent, workflow tasks, loop turns) journals its built request before sending it, so a prompt, skill or role edit landing while the invocation waits never breaks its replay (RT0016); turns not yet sent pick the new content up
• Error model — a plain throw inside ctx.run is retryable and replays from the failure point; a throw that leaves the handler fails the run on that attempt (the engine settles it failed and reports it terminal), while a restate.RetryableError replays it; restate.TerminalError stops immediately; a documented compensation/saga pattern unwinds executed steps on terminal failure or cancel
• Restate SDK pinned at 1.14.5 — an exact pin (not neglect): from 1.15.0 a CancelledError rejects the await over ctx.run, which breaks the agent VO’s post-cancel “death certificate” write and wedges the whole workflow cancel cascade; the migration to explicit-cancellation mode is tracked, and the pin is verified by a cancel integration suite
• Test-server version parity — the SDK test harness boots the same pinned Restate server image as the compose templates, enforced by an image-pin test so a drift breaks the build instead of silently testing a different server
• Engine built-in services — workflow-run, planning-run, the agent Virtual Object, the agent-limiter Virtual Object and the greeter / agent-demo / approval-demo demos are served from the same endpoint; ENGINE_BUILTIN_SERVICE_NAMES is the single allowlist and drift against getEngineServices() is a boot-time fail-fast assert; a brain pipeline named like one of them is not served (a discovery failure) rather than silently replacing it
• Orphan reconciliation — reconcilePipelineOrphans closes the three holes the terminal write cannot: a deleted .pipeline.ts with in-flight invocations, a handler that died between Restate completion and the engine’s terminal write, and an invocation Restate has forgotten
  • Removed-service drain — every live invocation (sys_invocation, not yet completed) whose service is absent from the current discovery snapshot and is not an engine built-in is killed, and its row then settles as cancelled; found by invocation because the endpoint’s forced re-register already dropped the service itself from Restate; idempotent, so a converged world produces an empty report
  • DB row sync — every running/paused row is reconciled against sys_invocation (success → completed, a Restate cancel/kill ([409]) → cancelled, other failure → failed, in-flight → only its running/paused split mirrored, unknown past a 30-min heartbeat TTL → failed (orphaned))
  • Three drivers — pipelines startup, every hot reload, and a 5-minute scheduler pass, plus the manual omnislash pipeline reconcile (--dry-run default, --apply, --json)
• Editing a live pipeline — Restate’s in-place update: in-flight invocations continue on the NEW code; prompt/skill/role edits are safe (engine helpers journal what they resolved), while a change to the order or inputs of a pipeline’s own ctx operations breaks replay
  • A code change settles the runs it breaks (since 1.27.0) — on every start (a deploy, as it comes up) and every hot reload (before the new build serves), each live run’s journal is replayed against it offline, nothing executed; a run the new code cannot replay is settled at once by onCodeChange: end (engine default — killed as run_kill kills it, pages, watches and cards included) or restart (reset as run_reset — the steps before the wait run again, started as the original was: same person, same chat; a keyed restate.workflow run and a run another run started are ended instead) → MANIFEST pipelines.onCodeChange → the scenario’s execution.onCodeChange; no card — the reason on the run’s error, the action on the action log, one message per settle to the status chat
  • Undecided runs keep the wake-time path — a run the check could not decide pauses visibly at wake (RT0016, reason on the run) instead of vanishing, and the agent repairs it: a journal-compatible fix + run_resume, else run_reset (a workflow-kind run: run_kill + scenario_start under a new key)
• Developer CLI — omnislash pipeline run <name> [input] (with --handler, --target-key, --idempotency-key) and omnislash pipeline status <key> --name <name> drive the Restate ingress directly
• Container & runtime — a dedicated pipelines service (HTTP/2 on PIPELINES_PORT, health/metrics on HEALTH_PORT) with its own DI container (agents facade, tools, grants + HitlGateway + ToolsGateway, memory, skills, queues, KV, blob storage, status surface), health-checking the Restate admin /health, and a documented startup/shutdown sequence

Artifacts & Deliverables

• Run artifacts — file-based context passing — planner-declared outputArtifacts are ordinary files an agent writes into $ARTIFACTS_ROOT/runs/<run-slug>/; later phases receive a lightweight manifest and pull what they need with native Read/Grep/Glob, so no new agent tools, no runtime storage service and no dependsOn graph are needed (phases already give ordering)
  • Pull, not push — only a manifest of filenames and sizes goes into the prompt, which scales to hundreds of tasks; the agent decides what and how much to read
  • Manifest assembly — buildArtifactsManifest(dir) scans the directory and formatManifest(entries, dir) renders the markdown section, injected into the task prompt only once files exist (phase 2+)
  • Engine-runtime, not brain source — artifacts live under $ARTIFACTS_ROOT (prod /var/lib/omnislash/artifacts), a sibling of the runs root and brain baseline, and are bind-mounted RW into the per-run sandbox at the same absolute path so agent writes and engine reads hit one inode
• Declared artifact subtree layout — ARTIFACT_SUBTREES names every subtree and its lifecycle (store vs scratch), and every writer resolves its directory through getArtifactSubtree(key): blobs/ (store), blobs/.tmp/, runs/<slug>/, agents/<id>/, telegram/<bucket>/, conversation-uploads/, pipeline-runs/<slug>/steps/
  • Derived coverage — retention, the /artifacts browser’s hidden roots and getReapableArtifactDirs() are all derived from that one table, so a new subtree cannot silently escape the reaper; a test fails any call site that joins onto the root instead
• Artifacts retention reaper — the scheduler sweeps every scratch subtree under a brain-configured artifactsRetention policy in omnislash.config.ts
  • Two independent optional dimensions — ttlHours (age cut, runs first) and maxSizeMb (a single oldest-first budget over the union of reapable subtrees); with neither set nothing is deleted — there is no implicit default cut
  • Cadence & robustness — fires once at startup then every 6h, walks each root with a streaming opendir so memory stays bounded, skips a single unreadable root instead of aborting the sweep, prunes emptied directories, and skips eviction entirely when undeletable TTL-expired bytes already meet the cap
  • Deliberate exclusions — blobs/ (referenced by DB rows) and runs/ (interleaves with in-flight runs, needs a lifecycle-aware sweep) are excluded; omnislash doctor warns when the whole tree exceeds 5 GB
• Content-addressed blob store — $ARTIFACTS_ROOT/blobs/ behind every persisted blob ref, with the durability properties a long-lived reference needs
  • Persist copies, never links — persist(path) copies the source into blobs/.tmp/, streams a sha256 of that copy, then renames it to blobs/<sha[0:2]>/<sha>-<name>; the rename is what stops a reader seeing a partial blob, and copying (not hardlinking) is what keeps the blob immutable while agents rewrite artifact files in place
  • Honest naming & idempotency — hashing the copy rather than the source means the digest always describes the bytes stored, and identical content lands on the same destination so a repeat persist() drops the staged copy — dedup and retry-idempotency for free
  • sizeBytes from the stored copy — measured on what the ref will actually serve, not a separate stat of a source someone else may have rewritten
  • maxBytes enforced during staging — an oversize file throws BlobTooLargeError before anything is promoted, which is the only point where a refusal costs nothing (the store is never age-cut and a written digest may already back a live publication)
  • Symlink containment — the source is opened O_NOFOLLOW so a symlink at the final component fails instead of being followed into the store; every caller hands persist() a realpathWithin result, and the inline (non-blob) text paths canonicalize the same way
  • retrieve() refuses any path outside the store root — canonicalized through realpathWithin, so a blob ref can never be made to name an arbitrary file on disk; a missing blob still surfaces as ENOENT
  • Refs are absolute paths, not bare hashes — deliberately, so the API stream reader and CLI agents can Read them natively and the original filename stays visible; content addressing lives in the directory layout
• Blob store GC — refcounted mark-and-sweep — the scheduler’s BlobStoreGc (6h cadence + startup fire) snapshots the live reference set from every durable DB site (collectLiveBlobRefs over LIVE_REF_SITES: published artifacts, run deliverables, task artifacts, pipeline step outputs, conversation-event attachments, agent inbox attachments) and LocalFileBlobStorage.sweep() quarantines unreferenced blobs older than the grace window (blobGc.graceHours, engine default 72h, brain-tunable) into blobs/.trash/, purging quarantine a full second window later
  • Liveness by basename — refs match on the content-derived <sha>-<name>, so a moved ARTIFACTS_ROOT cannot orphan the store
  • Dedup-hit touch — persist() refreshes mtime when it dedups onto an existing blob, closing the re-publish-vs-sweep race; the grace window covers every transient ref carrier (queued deliveries, journal entries, a browser holding an upload ref)
  • Quarantine as backstop — a referencing site the collector missed becomes a recoverable 404 with an undo window, not a silent loss; a quarantined blob a live ref names is restored to its shard on the next sweep (self-healing for every known site), and blob-ref-coverage.test.ts source-scans the schema so a new ref-bearing column fails CI until classified
• BlobStorageRouter with pluggable providers — refs carry a URI scheme (local://, future s3://) that routes retrieval, so old refs keep resolving when the default provider changes; a persist failure on an external default falls back to the local provider, and createBlobStorage() is the single construction site where an R2/S3 provider registers
• Per-task stored artifacts — as each task completes, storeTaskArtifacts() reads the files the task actually produced and persists them onto workflow_task_runs.storedArtifacts (text inline as {storage:'inline', content}, binary as {storage:'blob', url}), so long-lived consumers (eval, dashboard) keep working after the run directory is gone
  • Bound to task completion, not run completion — the column reflects real files even when the run later fails, and the dashboard shows produced files rather than planned outputArtifacts
• Task outcome envelope — EVERY task is dispatched with one structured-output schema (buildTaskOutputSchema): {success, error, summary, artifacts}. artifacts[].filename is an enum pinned to that task’s real artifact names (null-typed when the task declares none), so the agent must measure each file with a real tool call instead of claiming it wrote one; the deliverable itself is NOT in the envelope — it is the file, and deliverable.schema is applied to that file afterwards (checkDeliverableContent); success:false + error is the honest-failure arm, so an agent never has to fabricate a result to satisfy the schema
  • Hard failure is terminal, not retried — a success:false verdict fails the task immediately with the agent’s own error as the reason, in its own branch past the infrastructure-failure branch so classifyError never reads it; a blocker that happens to say “rate limit on the vendor API” can no longer push a business verdict into awaiting_retry and re-drive a task that already established it cannot be done
  • A turn that reports nothing is a validation issue, not a verdict — a missing or unparseable envelope emits an unreported-outcome issue into the same list checkMissingArtifacts fills, so it inherits that seam verbatim (one recovery re-prompt, then fail); buildRecoveryPrompt branches on the key, keeping the file-oriented “do NOT start over” wording to missing-artifacts
  • optional: true still wins — the brain author’s declaration outranks the agent’s verdict: an optional task’s hard failure fails that task and the run continues; on the deliverable task it fails the run before the PR-finalizer window
• Artifact validation & auto-recovery — checkMissingArtifacts (part of DEFAULT_CHECKS) probes each declared file on disk after a task’s agent completes and, on a miss, emits a missing-artifacts issue with a ready-made prompt that triggers one recovery re-prompt
• Deliverable — the run’s primary output — the planner decides what (description, filename, format, schema), the scenario decides how it is stored, and assembleBlueprint() injects storage so it is never an LLM decision
  • Storage strategies — inline (text content in a JSONB column, the default), blob (URI ref + sizeBytes recorded at persist time so senders can gate on platform limits before materializing) and none (the action itself is the result; resultSummary is the only user-facing output)
  • Format-driven routing — the closed TEXT_FORMATS set decides text-vs-binary; anything outside it (including unknown formats) goes to blob storage
  • Scenario configuration — deliverable: { storage, format } in scenario frontmatter, both optional; format becomes a HARD CONSTRAINT injected into the planner’s deliverable stage, while filename is always the planner’s job
  • Execution — resolveDeliverable() builds a ”## Final Deliverable” prompt section with the full path (and parses a JSON Schema into an outputSchema for format: json), given only to the last task
  • Completion — the run handler’s journaled finalize-deliverable step runs resolveAndStoreDeliverable(), storing a blob ref or inline content on workflow_runs.deliverable; a missing file logs a warning and skips rather than silently falling back to the last task result
  • Consumption — consumers read the DB only: the dashboard retrieves and base64-encodes blobs for download, and the Telegram path gates on size before retrieving (messenger.maxFileBytes)
  • Typed union — storedDeliverableSchema is a Zod discriminated union on storage whose shared meta (description, filename, format) is derived from DeliverableSchema; storedArtifactSchema mirrors it at task granularity
• Run output channels — a run produces six distinct, non-interchangeable outputs: taskRun.result (the task agent’s own prose summary of its turn), run.resultSummary (short notification summary), the deliverable file on disk, the agent Redis output stream (~7d TTL, ~1000 entries), in-memory tool artifacts extracted from that stream, and taskRun.storedArtifacts
• Artifact publishing — artifact_publish(path, …) snapshots a file into the blob store and returns a browser-openable link on a dedicated content origin; artifact_unpublish(id) revokes it
  • Publications as ops (since 1.24.0) — everything after the publish is an artifact.* engine op, one agent tool and one dashboard procedure each: artifact_list (every publication, expired and revoked included; filters status, visibility, publisher actor kind, agentId, q; keyset; counts and whether private links are servable), artifact_get (the row and its trail — published / replaced / meta edited / revoked, each actor with its session), artifact_read_file (the content, bounded at 1 MB), artifact_update (retitle, lifetime from now — 0 expires now, null permanent, extending an expired one serves it again — make private), artifact_widen (make public or rename — artifact:widen, restricted, a person approves), artifact_unpublish (converted, contract unchanged) and artifact_delete (drops the record, frees its name — artifact:widen too); every write is an action-log row against artifact:<id>. The dashboard downloads a publication whole at /artifact-file?id=
  • Readable names, not secrets — every publication carries an alias served at /a/<alias> (derived by the fast model chain from title ?? filename stem, slugified, suffixed until free, or caller-pinned and validated against ARTIFACT_ALIAS_RE); the cuid2 /p/<id> URL remains the mutation handle and the unlisted escape hatch
  • Private by default — visibility: 'private' serves only past an app-side admin Basic-auth gate (ADMIN_USER/ADMIN_PASS_HASH), returning 401 + WWW-Authenticate so the browser prompts once per origin; 'public' is the deliberate, guessable-by-name opt-out, and on a credential-less deployment the default falls back to 'public' — announced in the tool schema, at registration, and by omnislash doctor
  • Snapshot semantics — the row references an immutable copy, so the agent may keep rewriting or lose the working file while the link keeps serving the bytes as published
  • Living documents — replaces re-points an existing publication at new bytes keeping the URL (refused on revoked or expired rows, and refused when the file extension differs, since the extension picks the renderer); expiresInHours stamps a deadline that replaces re-stamps
  • Derived visibility, never swept — expiry and revocation take effect because the serving lookup stops matching, not because a cron flips a status; a revoked or expired link is a 404 indistinguishable from one that never existed, and the row survives as an audit trail
  • Names are held until deletion — uniqueness spans the whole table, so neither revoking nor expiring returns a name to circulation; only a delete (artifact_delete) or a rename (artifact_widen) releases it, which is what makes the URL worth bookmarking
  • Capability-scoped, not publisher-scoped — any caller holding artifact:publish and the id may replace, edit or revoke (and holding artifact:widen rename or delete), which is what makes cross-actor revoke work; published_by / replaced_by / revoked_by and the action log are audit, never authorization
  • Widening is a person’s — a content replace never moves the name or the audience; artifact_update edits title and expiry and makes a publication private, and refuses to make one public or rename it — a freed name can be claimed by a new public publication, serving the old link to anyone — both artifact_widen under artifact:widen (restricted, hitl: true), which artifact_delete sits under too; the private direction is refused when admin credentials are unset
  • Rendering table — .md/.markdown render to HTML through markdown-it with raw HTML escaped, .html/.htm pass through as authored, everything else is served raw with a detected MIME; /raw always downloads, and markdown over maxRenderBytes (1 MB) falls through to raw so a synchronous render cannot stall the webhooks event loop
  • Sandboxed pages — every response carries default-src 'none', sandbox without allow-same-origin (opaque origin, no cookies/storage/network), nosniff, no-referrer and a noindex, nofollow header, so a published page can render but cannot exfiltrate; img-src names the artifacts origin literally (never 'self', which matches nothing inside an opaque origin) plus data:, so a page loads the tab mark and images published beside it and nothing else
  • Exact caching — a strong ETag of (id, updatedAt) with Cache-Control: private, no-cache, so a revoke lands on the next request while a widely-shared link is answered by revalidation before the blob is ever read
  • Source-path containment — path must resolve (via realpathWithin, not lexical containment) inside the caller’s own artifact roots — agents/<agentId>/, plus runs/<slug>/ for a workflow task — never the whole $ARTIFACTS_ROOT; file_send draws the identical boundary
  • Size cap — files over config.artifacts.maxPublishBytes (25 MB) are refused during blob staging, so nothing is stored
  • Conditional registration — artifact_publish registers only when ARTIFACTS_PUBLIC_URL resolves (explicit → https://artifacts.<PUBLIC_DOMAIN> → the webhooks public URL), so a brain with no public origin never sees a tool promising a URL nobody can open
  • Dedicated origin — in domain mode the artifacts.<PUBLIC_DOMAIN> vhost proxies only /p/*, /a/* and /favicon.ico (the tab mark the browser probes at whatever origin it opened — your assets/favicon.*, engine placeholder second) and 404s everything else, while the webhooks vhost symmetrically 404s the publication paths — one canonical origin per resource; requests are rate-limited per handle with separate id and alias buckets
  • Capability — artifact:publish at risk: 'moderate', hitl: false (there is no destination argument; the origin is engine-owned config and the act is revocable), overridable to hitl: true in constitution/engine-capabilities.json; artifact:widen at risk: 'restricted', hitl: true, granted to no role by default
  • Serve observability — every request to /p/* and /a/*, including refused ones, is counted once as published_artifact_requests_total{handle, variant, outcome} and logged once with the ref the reader used (per-link attribution deliberately in logs, not in an unbounded metric label)
  • Data model — omnislash.published_artifacts with blob_ref, filename, content_type, size_bytes, title, unique alias, expires_at, visibility, and the published_by / replaced_at / replaced_by / revoked_at / revoked_by audit columns

Evaluation & Self-Evolving

• Run evaluation — a completed execution is graded by an LLM evaluator against the plan’s own criteria, producing a score, a per-criterion verdict and a pass/fail
  • Two levels for workflows — per-task Definition-of-Done scoring (only for completed tasks with a non-empty DoD) plus a run-level check of successCriteria, custom requirements and the deliverable; the overall score is 0.6 × task average + 0.4 × run score and overall pass requires all tasks, the run and every custom requirement to pass
  • Deliverable verification — file existence, format correctness and schema conformance, read directly from disk in the worker rather than from the DB copy
  • Grounding & tool evidence — the evaluator prompt is fed the run’s tool artifacts and per-task tool report, so the verdict is checked against what actually happened rather than the agent’s narration
  • Structured output, fail-closed — Zod-derived run/task output schemas and a per-call agent timeout well inside the eval lease. A judge that answers with nothing FAILS the evaluation (judge: no structured output) — there is no rescue model, because a grade produced by a judge nobody declared cannot be compared against a baseline the declared one produced — and output that arrived but does not match the schema fails it too (judge: unparseable output, announced first as eval.parse_failed) rather than being recorded as a completed grade of zero, which would make a malfunctioning judge look like a run that lost
  • Three execution kinds — workflow runs, pipeline invocations and heartbeat ticks each have their own queue and prompt builder; a runKind discriminator plus a CHECK constraint keeps pipeline evals free of per-task results
• Grading without a judge — evaluation.method: none — for an entity whose “good” is entirely a number its code already has: no model is called, the grade is the computed catalog plus measure() / window(), passed is read off the declared floors, quality is only reported and no quality guard is added, and no sample.maxPerDay ceiling is owed (nothing is spent). A judged metric, quality as objective/guard, or requirements fail the load. The cycle pins a judge of none plus the loop module’s digest, so editing measure() mid-cycle is a judge change
• Eval methods are brain files — constitution/Evaluation/Methods/<method>.md selected by evaluation.method, requiring a # Run Evaluation section with an optional # Task Evaluation one; add a method with eval_write_method (dry run first — a file without # Run Evaluation is refused)
  • eval_write_method (config:write) — writes one method file, validated as the loader parses it (a # Run Evaluation section), D30-shaped (dry run → expectedSha → compare-and-swap); none is reserved. The dashboard’s Eval Methods page calls the same op
• Per-entity evaluation config — an evaluation: frontmatter block with enabled, method, modelRef, run-level requirements and sample, resolved across three tiers (engine default → constitution/MANIFEST.yaml → the entity’s own block) merged one level deep with sample merged field-by-field
  • Manifest kill switch — evaluation.enabled: false in the manifest ANDs with each entity’s flag, stopping all grading at once without touching entity files; the manifest never opts an entity in
  • Hot-synced — the manifest is editable from the dashboard and takes effect without a redeploy
• Declared metrics — the brain says what “better” means — every graded execution produces a VECTOR of named numbers (evaluations.metrics), and every cycle verdict is a comparator over vectors. The engine fixes that shape and nothing else: which metrics exist, how they are measured and which one is the objective belong to the brain author
  • Three tiers, like every other loop value — evaluation.metrics is a map of metric id → declaration, merged engine catalog → constitution/MANIFEST.yaml → entity frontmatter, per id. Identity fields (kind, direction, scope, unit, criterion, human, scale) belong to the tier that INTRODUCES a metric and cannot be redefined lower down; usage fields (role, target, tolerance, tolerancePct, floor, mustImprove, critical, aggregate, optional) belong to the entity and every tier may override them
  • A metric outside the catalog must declare role as well as kind and direction — MetricSpecError naming the missing key otherwise, surfaced per entity by omnislash doctor → Loop modules. Defaulting it to observe was the quiet failure: an author who declares a metric has by definition decided it matters, and reading their silence as “measure it and ignore it” ships an entity whose verdict never mentions the number it was written for
  • A metric can belong to a PERIOD instead of a run — scope: run (the default, every catalog metric, every metric before windows existed) means the number is a property of ONE execution: measure() produces it at grading and the pre-merge check compares it pair by pair. scope: period means it belongs to the entity over a window — followers, a week’s revenue, the share of drafts a human approved — so no execution can produce it and window() measures it once per window onto the window record. Identity, not usage: one id cannot be a single run’s property here and the account’s total there. period implies computed and rules out critical (both load errors: a judge has no execution to score, and a per-input veto never reaches an input). The consequence worth knowing before you declare one — the pre-merge check cannot read it, so an entity whose ONLY objective is period-scoped merges on a guards-only check, which omnislash doctor → Loop check names
  • Engine catalog — quality (today’s overallScore), passed (today’s overallPassed), cost_usd, duration_ms, tool_failures. Measured for every graded execution whether or not anyone declared them, so a metric promoted from observe to guard already has history to compare against. Their ids are reserved
  • Three producers, one contract — the evaluation outcome fills quality/passed, engine telemetry fills the computed catalog from data it already holds, and the eval agent scores whatever judged metrics the brain declared. Judged ids reach the agent as a runtime enum in a per-entity output schema, so it can neither invent a metric nor misspell one — and a declared metric it fails to answer fails the evaluation loudly rather than defaulting to zero
  • overallScore / overallPassed are the projection — kept as indexed columns for dashboards, trends and the trigger’s shortcut, written from the vector in one place so the two cannot drift
  • Anti-Goodhart floor — the moment an entity declares any objective other than quality, quality becomes a guard automatically. Opting out is possible but must be written down (quality: { role: observe }), which puts it in a diff and under the loop’s protection rules
  • Zero-declaration default is today’s behaviour exactly — quality objective, passed guard, the rest observed
  • quality’s own recipe is brain-tunable — evaluation.scoreWeights (engine 60/40 tasks-vs-run → manifest → entity) decides how a workflow scenario’s per-task grades weigh against its run grade. Relative weights normalized by their total, so quality cannot leave its 0..1 scale whatever pair is chosen; declared as a pair, since half a split silently re-weighs the other side
  • aggregate: median | mean — how a metric’s per-run values become one number in the window’s level, the evolve watch’s bootstrap and the pre-merge check’s movement over its inputs; engine tier median. mean is what a 0/1 share (👍, replied, escalated) needs — its median sits at 0 or 1 while the rate moves
  • Ratings from people — kind: reported, human: true, scale — a metric a PERSON rates: reported (people only — your 👍 on a dialog, your own 1–5; no judge asked, no code owes it, an unrated run has no value) or judged with human: true (the judge scores every run, a person’s rating stands over it). scale: { min, max, step?, labels? } is the scale and rubric both the judge and people answer on — engine default 1–5 with a rubric for a human-rated metric, the judge’s native 0..1 otherwise — normalized to 0..1 on the vector, so target / floor / tolerance are written on 0..1. Ratings live in run_signals (one per person per metric per run, latest wins, median across people) and come through ONE write point that refuses a non-person, a loop replay, a run that is gone or has not ended, an entity whose grading is off, an undeclared metric and an off-scale answer — the whole gesture is checked before a run the sampler passed by is graded on it. Writers: the rating card, the dashboard’s Rate runs (the entity’s newest runs, graded or not, judge and people side by side; on a chat role’s page, Rate on each ended episode), and eval_rate — an agent relaying the person its turn serves (eval:rate, approval by default, so that person confirms it); no agent rates on its own account. The loop reads ratings only in observed windows — trigger, watch, proposer brief, dashboard traces — never in the pre-merge check’s frozen incumbents; the watch reads each human-rated judged metric from ONE source for both windows (people when each holds evaluation.human.agreement.minPairs rated runs, engine 5; the judge in both otherwise); a run awaiting a person’s rating is not a window member until rated or its wait ends. omnislash doctor → Loop check warns when a reported metric is the objective of an entity whose check replays
  • Rating cards, calibration, earned autonomy — evaluation.human — ask: never | always | until-calibrated (engine never): a run’s terminal posts ONE rating card (buttons for one metric on ≤ 8 steps, a number per metric otherwise; the run’s summary, what it published, each metric’s rubric) to the HITL chat and the dashboard, through a keyed job; only a person answers it, and the answer lands in run_signals keyed by the card. The carded run waits expiresHours (48) before its judge’s number counts alone. until-calibrated stops carding once the judge agrees with people — per judged human: true metric, over the newest agreement.maxPairs judge/person pairs under the current judge (model, method, role — a .loop.ts edit keeps it), unknown below minPairs, ok at threshold agreement within tolerance — keeping spotCheck (0.1) of runs, and starts again when one falls to low. loop.autonomy.requireCalibration holds both auto gates for a person until every such metric is ok. The status is visible to your window() hook (ctx.calibration()), on each round’s record, on the dashboard’s Policy view and in omnislash doctor → Human calibration
  • optional: true — a computed metric its code may not always be able to measure: a live measure() or a ready window() that leaves it out records no observation instead of failing the grade. Refused on a judged metric
  • Tolerance axes move together — naming either tolerance or tolerancePct on a metric takes the whole band off the engine tier. The two combine as the more forgiving of the pair, so filling the unnamed axis from the default would let the engine outvote the author and let declarations only ever widen a band
  • Code tier — <entityId>.loop.ts — a module beside the entity file, discovered by the same sibling convention as *.pipeline.ts and hot-synced through the G-set. defineLoop({ cases, measure, window, shouldOpen, verdict, compare }) — ONE module per entity, carrying every brain FUNCTION of the loop and never a VALUE, which is what keeps the dashboard whole: every number stays in frontmatter where the UI edits it, so a custom function costs the surface one row’s provenance and never a hidden knob. measure produces numbers the engine cannot derive (a delivery rate out of the brain’s own tables, a business KPI), verdict replaces the pre-merge check’s candidate/incumbent comparator outright, shouldOpen replaces the trigger’s k-of-n count and answers { open, reason }, cases (workflow scenarios only) are golden inputs every candidate is measured on, window chooses what a cycle is evidence of (asked on every landing grade and on every scheduled look, before shouldOpen; the repair preset samples the entity’s last trigger.windowRuns graded runs through the grade in hand, and a module composes it with ctx.preset.window(ctx)), and compare is declared for the post-merge comparison. A RUN-scoped computed metric declared outside the engine catalog REQUIRES measure — the evaluation fails naming the ids rather than scoring against a metric nobody measured — and a PERIOD-scoped one requires window, whose absence is quieter (the id is simply never in a window, a brief or a verdict). omnislash doctor → Loop modules says so either way, before it costs a run
  • Brain-wide loop functions — defineProject({ loop: { window, shouldOpen, verdict, compare } }), function-carried like tools/ingest/engagement. They live in the config file rather than the manifest for the one reason the loop’s other knobs do not: a function has no YAML form. measure is deliberately not among them — it reads ONE entity’s own tables, so there is no brain-wide form of it. Precedence is the engine preset ← project ← entity module, for each independently
  • Declarations for the common case, code for the rest — code is deliberately not the only form: requiring a TS module to enter the loop would leave most entities outside it, put tolerances and targets out of the dashboard’s reach, and add a file per entity to protect and review
• Eval sampling policy — evaluation.sample decides how much of an entity’s execution stream is graded
  • rate (0..1) — hashed off the execution id so the sample is spread evenly and the same execution always gets the same verdict no matter how many retries or replays ask
  • maxPerDay — a per-entity cap over a rolling 24h, so a chatty scenario cannot starve the rest of the brain; rate alone bounds the fraction but never the count
  • One shared decision — decideEvaluation sits at every producer, so nothing is enqueued that the policy would discard
  • Engine-needed verdicts bypass both — the pre-merge check’s replays and the executions observed while the watch counts a shipped change are always graded, bounded by the loop rather than by the schedule
• Mandatory ceiling for unattended entities — sample.maxPerDay is optional for human-launched scenarios and required once the engine produces the executions (a scenario with schedule:, and every heartbeat)
  • Enforced where the money is spent — decideEvaluation returns no_ceiling and grades nothing, so no write path (dashboard config editor, scenario_update tool) can route around it; deliberately not enforced at frontmatter parse, since a parse rejection would delete the whole scenario over a grading knob
  • Visible — the entity keeps running and simply is not graded, and omnislash doctor names every unattended entity in that state under Eval ceilings
• Booked before queued — a producer that decides to grade inserts the pending evaluation row before enqueueing the job, so the row is the reservation maxPerDay counts; writing it at worker pickup instead let every execution terminating inside the queue window read the same pre-insert count and pass
• Delayed grading — evaluation.gradeAfterHours — when an entity’s outcome only exists hours after its run (a short’s views at 72h, a delivery rate that settles overnight), the judge waits that long instead of scoring an empty result at the terminal. Three tiers like every other loop value (engine .default(0) → constitution/MANIFEST.yaml → the entity’s own block), read once at eval enqueue
  • Only the judge waits — the execution is still sampled and BOOKED at the terminal, so the reservation is still what sample.maxPerDay counts and the queue carries the lag as a BullMQ delay; a lag of 0 passes no delay at all and is byte-for-byte today’s behaviour
  • A lost delayed job is detectable — the booking records evaluations.due_at (the instant the grade is owed), and a scheduler sweep fails rows still pending past due_at plus the queue’s own retry span whose job it has confirmed is gone from the queue, with error: 'grading job lost'. Elapsed time only narrows the candidates: a worker fleet that is hours behind looks exactly like a lost job from the database, and the incident that drops jobs is usually the one that stops workers, so the queue itself casts the deciding vote. Without it an evicted Redis job would hold the challenger slot the post-merge watch is waiting on forever, and that wait has no clock of its own. (It does not free a sample.maxPerDay slot: that count is status-blind and expires with its own rolling 24h window either way.) Rows with no due_at are never candidates — no lag was in force when they were booked
  • Two gradings are never delayed — the loop’s own pre-merge replays (they compare a candidate against an incumbent now; nothing waits on a live outcome) and the manual eval_start tool, which PROMOTES a grading already waiting out its lag rather than silently deduplicating against it
  • omnislash doctor bounds the lag against what the brain keeps — Eval ceilings fails a heartbeat whose lag outlives agentRetention.ttlHours (the tick is an agent row; once swept, every grade of that entity fails) and warns any entity graded past the 7-day tool-artifact horizon (the judge still grades, it just sees a run with no tool calls); Loop watch warns when watch.deadlineHours cannot span the entity’s cadence plus the lag. The engine pins nothing extra for a delayed grade — the remedy is the brain’s own retention number
  • A replay measures fewer numbers, and only a replay — EvalRunContext.replay is true when the loop re-ran a frozen input inside its check; a brain’s measure() may return fewer ids than the entity declared there (the replay posted nothing, so a metric from the world has no source), while a live grading still fails by id on the same omission
• Run identity for lineage — ctx.runRef / context.auth.runRef — every graded execution hands brain code the { runKind, runId } its measure(run) will later receive, so a late metric can join on rows the run wrote: a pipeline reads ctx.runRef (its own invocation, plus definitionHash — sha256 of its scenario file and primary *.pipeline.ts as it started, replay-stable), a brain tool reads context.auth.runRef (the workflow run for a task’s agent, the invocation for callTool / runAgent, the tick for a heartbeat, the chat episode for a turn of a role’s direct chat)
  • Inherited by sub-agents and CLI sessions, never by child pipelines — a sub-agent does its spawner’s run’s work; a child pipeline is its own run. Counting toward a run owns nothing: no checkout, no liveness guard
• Chat episodes — the chat kind’s run — a person’s direct chat with a role is cut into episodes (consecutive turns with one counterpart, first message to end of dialog), each its own run id: every turn joins its chat’s episode at dispatch, whichever surface sent it (telegram, Secretary Mode, dashboard), and its tools see the episode as context.auth.runRef; group chats and system roles have none
  • Idle close — chat.episode.idleHours (engine 24, MANIFEST § chat → role chat:) — a durable per-turn timer counted from the role’s reply, never firing while the role’s agent is busy (a long turn, a turn waiting on the owner); the next turn supersedes the last one’s, so a dialog closes only after that much silence, and a turn after the close opens a new episode. A timer Redis could not take at the dispatch is armed again at the turn’s end and by the previous turn’s timer
  • Explicit close — agent_close_episode (the agent.close_episode op, capability episode:write, hitl: false; {} closes the turn’s own episode, { id } an agent’s open one — an agent names only itself, a person any) for the role’s agent and the dashboard, and closeChatEpisode(runId) from @omnislash-ai/infra/chat-episodes for brain code — one call; an escalation tool records its signal on the episode by run id and ends it
  • Role version per turn — each turn records the hash of what the role does (its body, its frontmatter without the evaluation: / loop: / chat: / budget: blocks, its named skills’ SKILL.md); a rubric, knob or ceiling edit is not a new version. An episode under two versions counts in neither window of a change. chat.onRoleChange: reset (engine keep) instead ends the open episode role-change and starts the session over on the first message after the change
  • Graded when it ends — the episode’s grading is booked at its close, gradeAfterHours counted from there; an idle close racing an explicit one still books once. Unattended like a schedule: a chat role owes sample.maxPerDay (doctor Eval ceilings)
  • The transcript outlives compaction — folding a long chat’s history into a summary moves its episodes’ turns out of the live history instead of deleting them, so the judge, a later episode’s judge and the dashboard still read them
• Chat roles in the loop — a role whose *.agent.md declares evaluation: / loop: is a chat loop entity (roster, <role>.loop.ts, its role file walled off from other entities’ changes — its skills stay shared, as a scenario’s do; its chat: block protected like the loop blocks); every per-entity doctor check reads chat roles beside scenarios and heartbeats; system roles are not entities, and omnislash doctor (Loop kind support) says how to move one into a feature
  • The judge reads the whole dialog — every inbound message, reply and tool call of the episode’s turns; evaluation.context.priorEpisodes (engine 0) earlier episodes with the same person as labelled context; evaluation.context.maxTokens (engine 40_000) cuts earlier episodes first, then the episode from its middle with an explicit marker
  • Privacy by one rule — constitution/Loop/chat-privacy.md (brain-overridable) says how the people in the dialogs are written about: the judge grades under it, and the engine appends it to every chat proposer brief under ## Privacy (a proposer pipeline: ProposerBrief.privacy). It binds what they write, not what they read: the proposer’s runs carry each episode’s runId, shape and verdict, and it reads the dialog itself with db_query (proposer/chat.md § Reading the dialogs) — a role copy without db:read keeps dialogs from it
  • Observed, never replayed — a change is judged on the role’s next episodes begun after it went live under one role version; no standing grant is scoped to a role, autonomy decides its gates
  • The owner’s rating — evaluation.human.ask (engine never); a chat card shows the episode’s shape and links its dashboard transcript
  • Episodes on the dashboard — a chat role’s Self-Evolving page lists its episodes (newest first, paged): start → close and why, turns, a span across role versions, the judge’s grade and numbers (its metrics and measure()’s, e.g. escalated), people’s ratings; Rate on each ended one (rating an ungraded one grades it) and Read the dialog — the role’s agent timeline cut to the episode’s turns, at ?episode=<runId> — the rating card links it as /go/role:<role>?episode=<runId>
• Grading on request (every kind) — a person’s rating of a run the sampler passed by books the judge on that run (the producers’ booking, gradeAfterHours from the run’s end) and lands on it, once the whole rating is validated; refused for a run that no longer exists or has not ended, and for an entity whose grading is off. The dashboard’s Rate runs lists the entity’s newest runs graded or not, so any kind’s unsampled run can be rated there
• Evaluation data model — one unified evaluations table keyed (runKind, runId) with a denormalized targetId (the recurrent entity) indexed for the rolling-window count, storing the metrics vector, its overallScore / overallPassed projection, per-task results, the run result, a summary and the createdBy actor
• Every grade records WHO produced it — each evaluations row carries a judge snapshot: the model ref it dispatched under, the eval method with a sha256 of the method file’s bytes, a sha256 of <entityId>.loop.ts (null when the entity has none), and a sha256 of the evaluator role — its file’s bytes with the capabilities it resolves to. The same shape the cycle pins on loop_cycles.judge, so the two sides compare like for like. Two grades are comparable only when those match: the difference between numbers produced by different judges is a difference between graders, not between versions of the entity. A row with no snapshot reads as not comparable rather than the same as yours
  • The recorded ref is the models, not a name — the snapshot’s modelRef is the entity’s evaluation.modelRef or, when it declared none, the evaluator role’s own inherited ref, with every role step expanded to the concrete chain models.json resolved it to at the pin. A fallover chain is kept whole (it is what the brain declared its judge to be); a role’s name is not, because re-aiming it in models.json mid-cycle would change who grades without changing the string. Dispatching the pinned ref reproduces dispatching the role at the moment it was pinned
• The judge is frozen onto the cycle — a cycle resolves its judge ONCE at the start (loop_cycles.judge jsonb), and every evaluation it asks for rides that snapshot: the challengers it launches, and the ticks or invocations it observes. A change to the method file or the loop module reaches the NEXT cycle, never the one in flight. The snapshot is read once the first analysis has created the row and never re-read; a judge that cannot be resolved at all settles the proposal skipped with an owner notice naming the file — nothing ships that the loop could not measure
  • Three baskets, not two — graded (status='completed'), ungraded (status='failed' — the grading itself failed, or some other judge produced it) and not-run (no row at all). Folding ungraded into “the change lost” is how a broken judge reverts healthy work, so the loop counts them apart; the ceiling below is measured over graded + ungraded only, since a challenger that never ran was never put to the judge
  • evaluation.judge.maxUngradedShare — two tiers only (engine .default(0.34) → MANIFEST.yaml § evaluation.judge), no per-entity override: an entity that could raise its own tolerance for a failing judge is the one that most needs the ceiling. Above it the cycle settles unvalidated with reason judge unhealthy plus a notice, and nothing is reverted — the batch measured the instrument
  • A different judge is incomparability, never a re-judge — a grade is comparable only when its snapshot matches the cycle’s on every fact (judgeMatches, all-or-nothing), and an incomparable grade is set aside whole: a frozen incumbent grade is not used and the check re-runs the incumbent on that input; an observed run after the merge is ungraded for the watch (no slot, counts toward judge health). Nothing is re-scored — the artifacts a re-grade needs do not outlive the run, and a grade re-scored to match the cycle is a bar the loop moved
• A cycle freezes WHAT it grades beside WHO grades it — loop_cycles.frozen (jsonb FrozenSet) is written once, right after the judge: the entity’s last loop.check.inputs graded runs through the window’s anchor — the evaluation of the window’s newest run, scanned HISTORY_SCAN_LIMIT deep so a narrow window cannot starve the set; a window naming no runs freezes golden cases only — distinct by input (the engine’s own replays and launched challengers never count as history), plus the brain’s golden cases from defineLoop({ cases }), plus baseSha — origin/<default> as the remote holds it at the freeze. Each history entry carries its own graded run as the incumbent’s score only when that grade was made under the cycle’s judge (judgeMatches); otherwise, and for every golden case, the check re-runs the incumbent on the input pinned to baseSha — one rule, no knob. Never recomputed: a refinement round reuses it. A set the brain’s files will not yield settles the proposal skipped with a notice, like an unresolvable judge
  • The freeze owns the evidence/held-out split — the same scan’s head, evidence.runs deep, is recorded as FrozenSet.evidenceRunIds (the runs the proposer was briefed on; the brief selects them the same way through the same anchor, since round 1 is staged before the freeze runs), and the check.inputs history slots fill anchor’s input first (a repair fix is checked on the failure it saw — a regression target, not a holdout), then inputs NO evidence run ran on (FrozenInput.heldOut: true), then shown inputs only when nothing else is left; golden cases are never held out. The check’s verdict reason names held-out k of n, and k = 0 is a doctor hint under Loop check (check.inputs < 2, or distinct graded inputs ≤ evidence.runs). No new key: the seam is the existing pair evidence.runs / check.inputs
  • loop.check seam — { mode: replay | none, inputs (1..20, default 5), trials (1..3, default 1), deadlineHours (default 24) }, merged wholesale per tier like autonomy. mode carries NO engine literal: it is derived per cycle from the plan by resolveCheckMode — replay for a workflow scenario whose .blueprint.yml needs no capability a human has to grant (a replay asks nobody and fails on one), reaches no capability above moderate (REPLAY_RISK_CEILING), opens no PR and runs in the brain repo (agent.repo absent or the brain itself); the facts are read off the plan once, in @omnislash-ai/capabilities (readCheckSubject), for the doctor and the freeze alike; none otherwise and always for a heartbeat or a pipeline, whatever a tier declares. A declared replay on an unreplayable workflow is honoured; under none the cycle freezes nothing and frozen stays NULL — the record that this cycle has no pre-merge check
  • Golden cases — LoopModule.cases: Array<{ id, input }> on the entity’s <id>.loop.ts, validated at load (unique non-empty ids, object inputs); workflow scenarios only, the one kind whose execution takes an input
  • omnislash doctor → Loop check — fail on replay declared in an entity’s own frontmatter for a heartbeat or a pipeline, and on replay declared for a workflow with no readable plan (the freeze would skip every cycle); warn on replay declared against a plan the engine would not replay (naming why), on a plan on disk the engine cannot assess (a file that will not parse, an unknown capability — it derives none and checks nothing), and on a replayed entity with fewer inputs to freeze (distinct graded inputs + golden cases) than check.inputs; pass with a hint naming replayable workflows that declared none. Runtime presets and the CLI inject the distinct-input count (countGradedWorkflowInputs), so the doctor package opens no DB connection of its own — and a count that cannot be read from here (no route to postgres) is a warn, never a fail
  • .blueprint.yml is read from config — the read side of the planner’s YAML module (readBlueprintFile, resolveBlueprintYamlPath, @omnislash-ai/config/blueprint-file) moved below the workflow engine so the doctor and the loop’s freeze can assess a plan; the write side stays with the planner, which re-exports the readers
• The pre-merge check measures the candidate BEFORE it ships — for a workflow scenario the cycle froze inputs for, check.ts (S7) runs once the apply PR is open: it pins the PR head (loop_proposals.checked_sha), replays the scenario pinned to that head on every frozen input × check.trials (the candidates, check_run_ids) and, for every input whose frozen entry carries no comparable grade, pinned to frozen.baseSha (the fresh incumbents, baseline_run_ids), waits for their grades up to check.deadlineHours, checks the judge (maxUngradedShare, candidate side) and that the incumbent was measured at all, then hands the comparator the inputs × trials pairs — each frozen input’s incumbent grade (frozen, or the fresh replay) beside the candidate’s replay of it. Every replay is one journaled step keyed by an id minted outside it; the wait is a backoff poll over the rows the replays leave
  • The verdict is a commit status on the PR head — omnislash/validation (packages/git-ops/src/commit-status.ts, gh api … /statuses/<sha>, statuses: write in ENGINE_GIT_APP_PERMISSIONS): pending when the check opens, success on validated, failure on regressed, error with the reason on unvalidated. A repository that requires it cannot merge an unchecked candidate, nor a commit pushed after the check (the status is on checked_sha alone); under merge: auto the engine additionally arms auto-merge only after the check answered (armAutoMerge, S8), never at the apply, and bound to the checked commit (gh pr merge --match-head-commit, GitHub’s expectedHeadOid — a moved head refuses the arm); the merge wait (awaitMerge) then holds the PR to that head on every poll, and a head that moved has its arm taken out (disarmAutoMerge) and the round demoted to the human gate with a head-moved notice
  • The comparator reads PAIRS — VerdictInput.pairs, one per frozen input per check.trials, each carrying the incumbent’s side (its frozen grade, or the fresh replay at baseSha) and the candidate’s (PairSide: viable with its vector, failed, ungraded, notRun, unfinished), built by the check from the launch slots it keeps in memory. Two batches on different inputs measure the inputs as readily as the change (proposal a02); a pair measures the change alone
  • regressed closes the PR — gh pr close with the per-metric and per-input story in a comment, the row settled from applied through the same CAS the watch uses (settleCycleValidation(…, 'applied')), a lesson written, no revert: the change never shipped. unvalidated leaves the PR open for a person, with the round demoted to the human merge gate under merge: auto; the error status blocks a merge wherever the status is required, so there the person’s decision is an administrator’s bypass or a close, and the notice says so
  • A broken candidate is named on the first tick — a pinned create that fails before create-run (its plan will not load at the PR head, the commit will not fetch) leaves no row; the check asks the attempt itself (workflowRunClient.attemptOutcome: live invocation → still driven, else the retained terminal result) and books it as a run the change failed, with the error in the reason, instead of waiting out check.deadlineHours to settle unvalidated
  • A replay’s grade never opens a proposal — the eval worker looks a graded run up in check_run_ids / baseline_run_ids (findCycleByCheckRunId), and the trigger window and the baseline both exclude grades booked under the loop’s own actor (evaluations.created_by.kind = loop) rather than by id lists, so a previous cycle’s candidate is never the entity’s history
  • Stuck detection knows the check’s budget — an applied row whose check has opened (checked_sha set) is bounded by watch.deadlineHours + check.deadlineHours, since the merge wait starts only once the check answered
• Failure taxonomy — a failed run eval carries a small engine-defined failureCategory (unclear_instructions / missing_capability / wrong_plan / tool_failure / quality_below_bar / other) plus free-text failureDetail; the proposer’s input and the suggestion card surface other entities recently failing the same way, steering one root-cause fix instead of N point fixes (surfacing only, no auto-suppression)
• Live eval progress — EvalChannel reduces workflow:eval.* / pipeline:eval.* events into a Redis evaluation:session.snapshot (schema-validated on read, heal-on-acquire reconciliation from the durable rows, active vs terminal TTLs) that chat and the run-detail view render live
• Eval events — eval.started / .completed / .failed / .skipped / .parse_failed on both the workflow and pipeline buses, plus per-task workflow:eval.task.completed / .failed
• Eval tools (MCP) — eval_start (grade a finished run now — a workflow or pipeline run, a heartbeat tick, a chat episode; answers the evaluation’s id, refuses a live run, a run that belongs to no entity and one already graded), eval_get (one evaluation in full, by evaluation id or by the runId it grades, with its live per-task progress while it grades) and eval_list (evaluations newest first with scores and verdicts — by status, the run graded, one entity or a feature, over a window defaulting to 30 days, paged on a cursor); since 1.24.0 eval_list_methods / eval_get_method (every evaluation method — engine, customised, the brain’s own — with the entities that grade with it, and one method’s text with the sha eval_write_method swaps against), eval_list_episodes / eval_get_episode (a chat role’s episodes with the judge’s grade and people’s ratings) and eval_rate (eval:rate, approval by default: a person’s ratings of one run, relayed by an agent for the person its turn serves — through the one door every rating takes); loop_get_cycle (loop:read) tells one improvement cycle whole — its phases, rounds and decisions, PR and revert, verdict and its strength, lesson, agents and spend, its grade and each round’s baseline / candidate pairs — as the dashboard’s Self-evolving page and a run’s Evaluation tab read it
• Idea tools — loop_create_idea ({ targetKind, targetId, text } → { ideaId, opened, reason }) and loop_cancel_idea ({ ideaId } → { withdrawn, reason } — the idea’s state after the call, so a repeated withdraw answers true again), in the same Evaluation category and registration as the eval tools, so worker, pipeline, chat and MCP agents all carry them; both provide loop:analyze (moderate, hitl: true — an idea spends a proposer and outranks the entity’s own rule; relaxed per automation with a grants: block or brain-wide in constitution/engine-capabilities.json). A refused post wrote nothing and is a tool failure with the reason; a posted idea whose cycle did not open yet is a success with opened: false, so the agent does not post a duplicate
• Loop — a graded execution that meets its trigger spawns a proposer agent that reads one kind-agnostic brief about the entity — its definition, the window the cycle opened on (window.json: the stored window, its vector, its runs ranked bad-first), the grade that opened it where one did (grade.json), its recent graded runs through the window’s newest run, its own proposal line, the lessons its settled rounds left behind, its metric declaration and other entities failing the same way — and proposes concrete file changes
  • The cycle’s anchor is a window, not a grade — loop_cycles.window (WindowSchema: from, to, runIds distinct and oldest first, period metrics, reason) is sampled by the loop’s window function through ONE producer (openCycleWindow, @omnislash-ai/loop: enabled first, then window → engine re-filter → shouldOpen, the live-target guard, the keyed submit, never throwing on brain code; its decision half is evaluateTriggerWindow → {kind, window, open, reason, ruleSource}, which a reader outside a grade — the dashboard’s entity detail — asks with anchor: null for the tick/owner answer, brain-replaced window/shouldOpen included) and read by everything after: the brief, the baseline (windowVector — each metric aggregated over the window’s runs, the median unless it is declared aggregate: mean, with its period metrics laid over), the freeze (scanned through the newest run’s evaluation) and the dashboard’s cycle list. Whatever runs a window names are re-filtered by the engine (windowOutcomes: the entity’s own completed grades, never the loop’s replays; the pinned judge and the watermark where a phase passes them) the drops are counted as rejected, and the row stores the survivors — the anchor a stored window is read through is always a run the loop counted. evaluation_id is the grade that produced the window, nullable; a window with none is analysed on its runs alone, carries no grade.json, and freezes through its own newest run
  • One bundle, assembled once for every kind (buildEvidenceBundle) — a target adapter hands over raw material and nothing else; which runs are shown, in what order, with how much of each, and what goes when the whole thing does not fit are decided in one place. While each kind rendered its own runs.json, loop.evidence could not mean one thing: a brain raising runs on a heartbeat and on a scenario was tuning two unrelated documents, and only one of them carried a trace
  • Bad runs first, and the cut comes off the end — runs.json is the entity’s last evidence.runs GRADED executions ordered bad-first by the loop’s single definition (isBadRun, under the trigger’s LIVE terms) and then newest-first, each with the judge’s per-criterion reasoning and cited evidence, its metric vector, the execution’s own resultSummary, the failure taxonomy and — under evidence.includeTrace — its tool calls, read best-effort from the Redis stream so an aged-out trace is honestly [] rather than a failed analysis
  • The ceiling has a fixed order — estimateTokens over every file, and over evidence.maxTokens the traces go first (largest by an order of magnitude, most redundant: the criteria already say WHAT went wrong) and then the oldest runs one at a time down to one; the definition, window.json, grade.json and metrics.json are never cut, because a bundle that fits by dropping those has been emptied rather than trimmed
  • Who analyses and what it is told are seams too — the loop.proposer block — { pipeline, modelRef, instructions }, the one block inside loop: folded PER FIELD (every other block belongs whole to the nearest tier that writes it). modelRef (absent → the proposer role’s own ref, the file that re-aims every analysis at once; nearest tier wins; no effect under a pipeline); instructions — lines ADDED to the brief, never a replacement: the brain’s (MANIFEST.yaml) and the entity’s are both kept, the brain’s first, and the engine appends them after whichever brief the cycle reads (the kind’s, the preset’s, an idea’s; the engine template or a brain copy) as ## Instructions for every entity of this brain / ## Instructions for this entity, and hands them to a proposer pipeline as ProposerBrief.instructions: { brain, entity }. The retired flat keys loop.modelRef, loop.prompt and a scalar loop.proposer are refused at load with the new path in the message. omnislash doctor (Loop proposer models) fails a modelRef models.json does not resolve and warns on one beside a pipeline
  • Two human gates, each declaratively staffed — the Accept card (decide) and the PR merge. By default an owner gets an Accept / Skip card (a reply to it refines) and a human merges the PR the engine opens from the implementer’s gated changes; loop.autonomy (below) declares auto per gate. The change only ever ships through a PR — direct-push to main does not exist at any autonomy level
  • A cycle is its row, so deploys never strand one — each cycle runs as short steps over its loop_cycles row: a step reads the row, does the next thing on the code deployed NOW, writes the row and stops; a wait is a phase on the row (analyze → propose → decide → gate → apply → implement → ship → check → merge → sync → watch → settle → revert → done) plus the instant the cycle must look again. What it waits on rings it when it happens — a card answered or expired, an agent turn ended, the proposer pipeline’s run ended, a PR event, a graded replay, a knob write — and every wait also looks on its own ladder (2 min doubling to 2 h or 6 h), capped at its deadline. Every effect is recorded before it runs and found again on a re-run (the agent dispatched, the card opened, the replays launched, the PR by its branch), so a step a deploy cuts short just runs again. A cycle that keeps failing in one phase shows as stuck after ~45 min and is ended by the engine after a day (unjudged, nothing taught). Read through loop_status (each entity’s live cycle: phase, since when, next look) and the cycle’s story. Brain-side: self-evolving.md § A cycle, phase by phase
  • Statuses — completed (suggestions waiting) → accepted (being applied) → applied (PR open; the pre-merge check runs here) → validating → validated / regressed / unvalidated, plus skipped and failed. A regressed reached by the pre-merge check settles the row from applied: the PR is closed, nothing shipped, nothing to revert
  • Prompt overrides — role = folder, file = what it briefs: constitution/Loop/proposer/{workflow,pipeline,heartbeat,chat,evolve,idea}.md (one rule picks the brief: idea for an idea cycle, else the preset’s, else the entity kind’s — proposerBriefPath), constitution/Loop/implementer.md, and constitution/Loop/chat-privacy.md (shared by the chat judge and the chat proposer) are brain files a project can replace whole; engine templates are read as the fallback, never copied into the brain. A brief’s placeholders are {{definition}}, {{runs}}, {{window}}, {{grade}}, {{metrics}}, {{proposals}}, {{lessons}}, {{failures}}, {{refinement}} (+ {{idea}}); omnislash doctor fails a brain copy at a retired path (Loop/{default,apply}.md, a flat Loop/<brief>.md, constitution/Improvement/** — Loop prompt paths) or carrying a placeholder the engine does not fill / an implementer.md without {{editablePaths}} (Loop prompt placeholders)
• Two presets — the loop is a skeleton plus a bundle of functions — loop.preset names the engine tier of window, shouldOpen, verdict and compare (plus which runs the proposer is shown and which prompt briefs it); a preset carries functions, never values, so switching one changes which rules run and nothing they are tuned to
  • repair (the default) fixes what broke: a bad graded run opens an analysis over the entity’s last trigger.windowRuns grades, the proposer is shown the newest runs bad-first, and the post-merge watch counts bad runs by the trigger’s rule
  • evolve improves what works: every trigger.windowRuns grades (or every trigger.every hours) an analysis opens over the grades landed since the previous cycle looked, nothing being wrong; the proposer is shown the window’s best and worst runs by the objective under constitution/Loop/proposer/evolve.md; a threshold or trigger.minFailures written on the entity (or beside a brain-wide preset: evolve) is refused at load, while a brain-wide one tuned for repair entities is simply not read
  • The evolve watch compares windows — the window the cycle opened on against the first watch.windowRuns runs graded since the merge: floors and guards as point rules on the median, the objective through a bootstrap interval at watch.confidence (engine 0.9) — regressed only when the whole interval is past the tolerance, validated only when it clears the bar, unvalidated (“inconclusive”) between; a period-scoped metric keeps the point rule, a run metric on fewer than three observations a side is inconclusive rather than guessed, and a metric unmeasured on either side settles the change unvalidated naming it — never regressed, never validated. MetricDelta.spread carries the interval beside the gain wherever perMetric is shown; the watch stamps no validation_terms under evolve
  • An unproven change — watch.onInconclusive: keep | revert — what a shipped change the watch settled unvalidated becomes (a gain inside the noise, a window that never filled, an unhealthy judge): keep (engine tier) leaves it shipped as unproven; revert undoes it through the same revert PR a regression gets, so an autonomous brain keeps only what was shown to work. The row still settles unvalidated; the dashboard’s cycle view says “reverted by policy”. Not read under watch.mode: none
  • Period metrics are owed by window() — every window that is ready (at the trigger the one an analysis may open on, at the watch the full one the comparator settles on) must carry each scope: period id the entity declared, and may carry no other; a missing or stray id is a load error naming it, for the preset’s own sampler too. A window that is not ready may leave them out, so a brain that composes the preset pays for the period read once per cycle and once per watch, never per grade or per poll
  • A window that waits says on whom — or that it stopped — a window() that is not ready may name the person’s move it waits on (awaitingPerson: { what, url? } — “score PR #16”): the entity is listed under needs you (loop_status needsYou, gate window, with the link; next.waits.awaitingPerson; the dashboard’s “Next cycle” line and N need you list), and that is the engine’s only decision on it — no fake evidence, no timeout, under any autonomy. A not-ready window whose stated count (progress.have) has not moved for loop.windowStalledAfterHours (engine 336 h, MANIFEST → entity, 0 never) is listed as a stall with no brain cooperation; one that names a person is listed only for that. The producer records each not-ready sample (omnislash.loop_waiting_windows), so the fleet reads both without running brain code. Brain-side: self-evolving.md § A window that waits
  • omnislash doctor → Loop evolve — warns an evolve entity whose only comparable metric is the judge’s quality (optimised against its own grader), and hints the quality: { role: observe } opt-out where the judge’s score is still a guard beside a declared objective
• Loop targets are brain entities — the loop’s subject is (targetKind, targetId) with targetKind the ENTITY (scenario, heartbeat, role — LoopTargetKind, @omnislash-ai/types/entity), never the engine that runs it, so a scenario that gains a .pipeline.ts keeps its cycles, lessons, ideas, holds and eval window (evaluations.target_kind is generated from run_kind). One LoopTarget adapter per kind supplies the kind its executions run as now (runKind — a scenario’s engine, read at call time; what picks the proposer brief and whether the check can replay), the entity definition, its resolved loop terms (the loop: block plus the metric declaration the check and the watch read), its graded runs as raw pairs (listGradedRuns → execution + grade + the agents that carried it, for the grades the preset’s evidence policy chose, never a rendered document) and the auto-accept grant scope
• A cycle is a line of rounds — omnislash.loop_proposals, one row per round keyed (cycle_id, round), under one rule: a round owns its PR and everything that PR carries. The suggestions, their summary, the refinement that asked for them, the decision and who made it, pr_url / revert_pr_url, checked_sha, the candidate and incumbent replay ids and the check’s check_verdict all sit on the round; the cycle keeps only what it fixes or measures ONCE across all of them — the frozen judge and input set, the watch’s record, the effective merge_gate and when the merge wait started, the acks, the agent ids and the stage clock — because at most one round ever merges. A refinement is a CHILD round (parent_id), never an overwrite, so what the previous round proposed is still readable; the parent takes the status refined, and a failed round retried goes back to accepted on the same row
  • Lookups reach the cycle through the round — the eval worker resolves a graded replay by run id (GIN-indexed), answering { cycle, proposal } (a PR’s events reach the loop’s merge wait by the PR’s resource key, not through a lookup); the health predicate for “a promised revert was never opened” reads revert_pr_url through the same join, and every lifecycle event frame carries proposalId beside prUrl so a reader never has to guess which round a PR belonged to
  • Live changes announce themselves, not only transitions — beside the lifecycle frames the loop emits loop:checked (the round’s pre-merge check verdict recorded: outcome, reason, perMetric), loop:watched (each post-merge watch tick: observed runs through to), loop:revert.settled (how the wait on a regressed round’s revert PR ended: merged at GitHub’s mergedAt, closed or unmerged), loop:merge.gated (the merge gate the apply PR really stands under was recorded — gate: human | auto and waitStartedAt, the instant a person’s merge wait is counted from) and loop:merge.demoted (an armed auto-merge lost mid-wait — cause: head-moved | disarmed, armStands when the arm may still land the PR); the dashboard invalidates on them instead of polling. Observational like every frame — the row is the record
• One live cycle per entity — a partial unique index (loop_cycles_live_entity_key) over the live statuses plus a pre-check in the trigger and the analysis, so two failing runs of one scenario can never open two PRs against the same files
  • The claim always releases — every entry into a live status goes through claimCycleTarget, which returns null instead of raising when the target is taken; a PR left unmerged past the deadline settles unvalidated rather than freezing the entity forever; and a cycle the engine cannot advance — every step in one phase failing for a day (CYCLE_GIVE_UP_MS) — is ended by the engine itself (giveUp: unjudged, nothing taught), so a poisoned cycle never holds its entity forever
• Recurrence bounds — what the loop may spend on one entity — two loop: knobs on the same three-tier seam, gated in CycleService.startAnalysis beside the claim; a refinement round is exempt and an unloadable config fails open
  • cooldownHours — rest after a SETTLED cycle, engine tier conditional on the outcome (DEFAULT_ANALYSIS_COOLDOWN_HOURS: 6h ordinarily, 24h after regressed) and so carrying no Zod .default(); 0 disables the rest
  • maxAnalysesPerDay — rolling-24h ceiling on proposer agents for one entity, engine default 3, null opts out; omnislash doctor → Loop ceilings names every unattended entity that took the opt-out
  • Only an analysis that RAN counts — both bounds filter on startedAt IS NOT NULL, so a refusal neither fills the budget that refused it nor extends the cooldown that produced it
  • Refusing is loud — a refusal settles the cycle’s already-born row skipped with the reason (CycleService.startAnalysis), so the entity’s cycles on /evolution show the refusal and its reason instead of the loop going quietly silent
• Per-run spend ceiling — loop.budget — { maxUsdPerRun } on the same three-tier seam as every other loop block, merged wholesale per tier like autonomy, engine default null (unpriced, so an existing brain changes behavior by zero). The recurrence bounds above price how OFTEN a run may open and say nothing about what one costs; the ceiling covers the whole run — every agent it opens across every round — and is enforced by SUBTRACTION: readBudgetAllowance prices the run’s own agents (loop_cycles.agent_ids, off the spend ledger usage_records) before each dispatch and hands that agent the remainder as AgentCliOptions.maxBudgetUsd
  • A run with nothing left opens nobody — the analysis and the apply both refuse before creating an agent, and the stage’s failure names what was spent of what. Enforcing per agent instead would multiply the declared number by however many turns the run happened to take (two per round, six for a run refined twice and retried once), which is not a ceiling. A retired agent still counts — deleteAgent is a soft delete and the ledger is keyed on the agent id — and the cost of the turn just finished is already committed, because the VO settles the loop’s callback downstream of the finalize stage that drains that insert. A turn that never reached a terminal is the honest blind spot: that spend happened and no row records it
  • Two enforcements, one outcome — a harness with a native budget option (the Claude SDK’s maxBudgetUsd) stops the turn the moment it crosses and its error_max_budget_usd terminal is named over budget; Codex and OpenCode, which accept no such option, are compared against sumAgentCostUsd([agentId]) once the turn’s terminal passes and the terminal is rewritten into the identical failed over budget one. A caller reads one outcome instead of branching on which harness it dispatched to
  • The second lane is a verdict, not a brake — the spend has already happened when it fires, and the ledger it reads excludes the turn that just ended (the finalize stage writes that row downstream of the comparison), so it bites on the turn AFTER the one that crossed. The native lane is the one that can actually stop a crossing turn; the doc says so rather than promising a cap the harness cannot keep
• k-of-n trigger, never one run — an analysis opens when the graded run that just landed went badly AND loop.trigger.minFailures of the entity’s last trigger.windowRuns GRADED evaluations did (engine default 2 of 5, the block merged wholesale per tier like autonomy). One execution is a sample of the entity’s noise, not a measurement of it: a proposer opened on a single off run spends a model, a human answer and a PR chasing variance, then ships a fix whose validation compares the entity against that noise again. minFailures: 1 restores “analyse the first failure”, minFailures == windowRuns is the “N in a row” rule, and minFailures > windowRuns is a schema error rather than a loop that silently never fires
  • Ungraded runs are not in the window — the window is filled from status='completed' rows only. A run the judge failed on was never scored, so it is neither good nor bad; counting it as bad opens analyses on a sick judge, and merely letting it occupy a slot is worse, because the window is a FIXED size and an ungraded row would push a real graded run out and quietly demand more failures than the author asked for
  • What makes a run BAD is unchanged — loop.threshold limits analysis to failed or below-threshold executions (omitted → every graded execution is bad, so k-of-n then only withholds the entity’s very first analysis); a run with no score counts as failing, since no evidence of health is not evidence of health
  • shouldOpen replaces the rule, not the numbers — LoopModule.shouldOpen({ window, trigger }) on the entity’s <id>.loop.ts, or defineProject({ loop: { shouldOpen } }) brain-wide, answers in place of the engine’s count and receives both the window and the terms the count would have used. loop.enabled is settled before it runs: a kill switch a rule can switch back on is not a switch. The post-merge watch settles by the same rule (triggeredWithin, @omnislash-ai/loop): asked once per landed grade of the observed window, over the runs since the merge newest first, the way the trigger asks it — a yes at any grade regresses the change, a full window without one validates it, and a rule that throws settles unvalidated naming it. LoopTerms.functions carries all five resolved functions with the tier behind each (loopFunctionsFor, @omnislash-ai/config/loop-config); source: 'engine-preset' is the preset’s own count. A rule answers { open, reason }, never a bare boolean — the reason is what the owner is shown for the analysis that did not open
  • Metric targets count too — a declared target a run did not reach makes that run BAD in the window, even a run that passed. “Quality is fine but cost is still double what I asked for” is exactly the case a pass/fail gate cannot see
  • The newest run must be bad, not just the count — the count alone can fire on a HEALTHY run (two old failures still in the window), and the window’s newest run is the anchor the proposer’s evidence and the frozen history are read through (findGradedWorkflowInputs reads through: its evaluation, bounded on (createdAt, id) so a sibling booked in the same millisecond cannot stand in for it). Opening on a good run asks the proposer to fix a success, so the window is only ever a brake: it withholds analyses one-bad-run would have opened and opens none it would not
  • Brain code cannot fail the grade — resolving shouldOpen imports the entity’s <id>.loop.ts on the success path of every graded run, so an unreadable module withholds THIS run’s analysis (logged) instead of throwing after the evaluation was written and announced, which would bury the job and re-send its report on every retry
  • A cadence is the SECOND producer — loop.trigger.every — hours between scheduled looks at an entity, with no engine default because the key’s ABSENCE is the meaning (only a landing grade opens a window, which is the usual answer). No rule over graded runs can express “every Monday” or say anything about a week in which the entity did not run — the producer is the grade, so that is a producer problem and not a seam. An hourly scheduler sweep (LOOP_TICK_SWEEP_INTERVAL_MS, apps/scheduler/src/loop-tick.ts) walks every entity whose resolved every has come round since its own KV mark (loop-tick:<kind>:<id>; read, stamped and projected by @omnislash-ai/loop’s cadence module — readTickMark, nextAskAt = mark + every rounded up to the sweep, and restingUntil = last settle + the cooldown — so the dashboard answers “next look” off the same clock) and calls the ONE producer with anchor: null, producer: 'tick' and the entity’s LIVE trigger terms; everything else — enabled, the window, shouldOpen, the live-target guard, the keyed submit — is the producer’s, exactly as for a landing grade. The mark is stamped when the producer ANSWERS, opened or declined (a decline has answered the cadence’s question for this period; re-asking it an hour later would collapse every into the sweep’s own cadence), and NOT when the engine’s own read threw, which makes the next hour the retry. It is the cadence clock alone and never the loop’s mark: a tick that opens nothing writes no row, so max(window.to, watch_window.to) does not move and the next window is sampled as if the look had not happened. The sweep’s hour is the floor on how fine a cadence the engine can honour — a smaller number is not refused, it gets the sweep’s own cadence, and omnislash doctor names that rather than letting an author find out from a number that quietly rounded up. Two scheduler replicas reading the same stale mark both ask, and the loser is settled by the live-target guard plus loop_cycles_live_entity_key rather than by a redis lock — one live cycle per entity is an invariant the row already holds. Under repair a scheduled look still needs the entity’s newest graded run to be bad: the preset is a rule about failures, so a clock changes only WHEN one is noticed
  • Frozen for workflow scenarios — the trigger (enabled + threshold) is baked into the plan when the plan is built, so editing it affects runs planned afterwards, not runs in flight; pipelines and heartbeats read it live. trigger: itself is NOT frozen for any kind: it is a measurement over the ENTITY whose count spans runs from many plans, so freezing it would tie the window to whichever plan produced the newest run. The measurement knobs are never frozen — though each deadline is read once per PHASE rather than once per wait: reviewDeadlineHours is read at each analysis round and arms every one of that round’s human waits at once (and a brain proposer’s run), watch.deadlineHours once the change has shipped, arming the merge wait and the challenger window together. So an edit reaches the next round or the next proposal, never a wait already counting down — a proposal already past its analysis runs to a verdict on the terms it started with, never half on the old number and half on the new
• The ideas bucket — a human’s hypothesis, next in line — loop_ideas holds ideas posted for ONE entity; the entity’s next cycle is opened on the oldest queued one (FIFO, one idea per cycle, no priority, no config key) and works it before anything the loop would propose, and every stage after the analysis is unchanged, so an idea comes back as a measured experiment with a verdict. Engine entry points postLoopIdea / withdrawLoopIdea (@omnislash-ai/loop) are the only way in or out, so every surface refuses the same things in the same words — the /idea chat command, the loop_create_idea / loop_cancel_idea tools and the dashboard’s Ideas panel on /evolution (the bucket with each idea’s derived status and queue position, what the head of the queue waits on — the producer’s own dry run, the same sentence the entity’s timeline ends in — withdraw, and on a cycle the idea it was opened on)
  • Two surfaces — /idea <entity> <text> in chat (<kind>:<id> or a bare id resolved against the loop’s roster, asking for the prefix when it names two kinds; the reply renders the outcome in one sentence and carries a Withdraw button while the idea is queued), and the loop_create_idea / loop_cancel_idea tools (see Idea tools above) — which is how an agent routes a brain-wide idea to the entities it concerns
  • The author hears back — when the cycle that took an idea settles, its author gets the outcome, the idea quoted, and the measured deltas (the lesson’s own numbers, watch before check) or, for skipped / failed, the proposal’s summary (where a declining proposer says why) or the error. A chat post is answered in its chat; an agent or MCP post in the chat the loop’s cards arrive in. Sent at exactly the terminals a lesson is written for, best-effort in one journaled step
  • Outranks the rule, never the gates — a queued idea steps past the window’s ready, shouldOpen (which is simply not asked, so a brain rule written before ideas cannot starve them), cooldownHours and maxAnalysesPerDay; loop.enabled (the post refuses a switched-off entity), one cycle at a time (an idea waits until the entity’s previous cycle has SETTLED — an unanswered proposal holds no claim but still holds the line, so ideas run strictly one after another, each proposer seeing the previous outcome), the breaker, the pinned judge, the frozen set, the protected surface, the edit-size bound, the check, the watch and the decide gate all hold. The exemption keys on the input’s ideaId, never on which producer asked
  • No fourth producer — the ONE producer reads the entity’s queued head itself, whoever called it: a post pokes it as request, the scheduler’s hourly sweep asks as tick for every enabled entity with a queued idea (one query per sweep, no trigger.every needed, no cadence mark stamped), and a grade that lands while an idea is queued opens the idea’s cycle with its grade.json riding along. The cycle is keyed <kind>:<id>:idea:<ideaId>:<instant>: producers racing one idea can only open one cycle (one holds the entity, the rest step aside spending nothing, and only one can take the idea), and an ask that stepped aside does not use the idea up
  • The binding lives on the idea — loop_ideas.cycle_id (UNIQUE, ON DELETE RESTRICT); taking the idea (after the cycle claims the entity) and withdrawing it are two compare-and-sets on the same row, so exactly one wins, and a cycle that lost the race settles skipped (“the idea was withdrawn before its cycle started”) without spending a proposer, a slot of the day’s ceiling or a cooldown. Status is derived, never stored: withdrawn / queued / the bound cycle’s status
  • Its own prompt, never trimmed — an idea cycle is briefed with constitution/Loop/proposer/idea.md (engine default, brain-overridable) whatever the entity’s kind or preset — the entity’s loop.proposer.instructions still appended — plus idea.md in the brief: the text, who posted it and when, never cut by the evidence budget and bounded at the post by IDEA_MAX_CHARS (4000) for that reason. Declining — protected surface, missing capability, a validated lesson against it — is empty promptChanges with the reason in summary; the output schema is unchanged
• Two deadlines, not one — loop.reviewDeadlineHours (168h) bounds HUMAN latency at each wait of an analysis round (none of which exists under autonomy.decide: auto, where a grant request fails the turn and a broken analysis or apply closes the cycle failed with no card), all armed from one read per round: a grant request the proposer parks on abandons the turn and records the analysis failed; an Accept / Skip card nobody answers inside it expires (the card’s expiresAt IS the deadline — one clock) and the cycle settles skipped unanswered, with a review-abandoned notice, rather than holding the proposal forever; a grant request the implementer’s turn parks on expires the same way, but abandons the turn and records the apply failed, with the error on a Retry / Skip card that the same number bounds in turn. loop.watch.deadlineHours (168h) bounds EVIDENCE latency. One number for both would mean a brain tightening its verdicts to four hours had also, without saying so, given its owner four hours — discarding every proposal sent on a Friday evening
• Closed-loop validation — before the merge a workflow candidate is COMPARED by the pre-merge check; after it every kind is WATCHED by the loop.watch block (mode: observe | none, windowRuns / minFailures defaulting to the trigger’s pair, deadlineHours 168), merged wholesale per tier like autonomy — no per-kind strategy type, the seam is the whole answer
  • The verdict is an ORDERED list of rules over the PAIRS (metricVerdict, the pre-merge check’s comparator) — (a) fewer than ceil(inputs × trials / 2) pairs judged — the incumbent graded and the candidate answering: graded, or launched and dead before a grade — → unvalidated insufficient evidence; (b) the judge-health ceiling, settled by the loop upstream; (c) viability per input — the candidate must have passed something, and among the inputs the incumbent passed it must keep a strict majority (an input the incumbent failed too is not a loss; passing it is the fix), ties conservative; (d) a critical metric past tolerance on ANY input → regressed, naming the input — the per-input veto the median cannot forgive; (e) a guard past tolerance on the median of its per-input movements → regressed, a MECHANICAL VETO checked before the objective precisely so it outranks any score the judge produced; (f) any metric below its declared floor → regressed; (g) the objective past tolerance → regressed, and under mustImprove a gain inside the noise across inputs (half the spread of the per-input movements, never tighter than the tolerance) → unvalidated; (h) otherwise validated. Each rule answers a question the next one is not equipped to ask, and every rule below the one that fires would have answered the same batch differently. VerdictResult.perInput records every pair — what each side produced, whether the candidate lost the input, which critical metrics it failed there — beside perMetric
  • The four buckets travel whole to the comparator — failed / ungraded / notRun / unfinished plus expected (how much evidence was PROMISED), instead of one summed inviable. Summing them was the loop deciding on the comparator’s behalf that a dead run, an errored grade and a run still going are the same evidence — which is how a batch nobody could measure reached regressed and opened a revert PR. unfinished and notRun are never counted against a change; they only make the graded count smaller, which is exactly what rule (a) measures
  • Every metric is the MEDIAN of its per-input movements — the candidate’s value on an input against the incumbent’s on the SAME input, in the metric’s direction, over the pairs where both sides measured it (MetricDelta.compared); the two side medians ride along for reading. Tolerance is taken at the incumbent’s median (and, for a critical metric, at each input’s own incumbent value). The comparator receives the pairs RAW, not pre-aggregated, so a brain replacing it (defineLoop({ verdict })) can apply its own statistic — a worst case, a p95 — to the same pairs
  • Judged metrics get a tolerance band — default 0.05 absolute on a 0..1 judged metric, 10% relative on a computed one, both brain-tunable and per-entity overridable. An LLM judge’s own noise is larger than a strict >= could tell from a real regression
  • The watch’s window defaults to the trigger’s — the loop has no rolling baseline. The evidence a COMPARISON needs is sized where the comparison happens, before the merge (check.inputs × check.trials); after the merge the watch counts over loop.watch — windowRuns runs, minFailures bad ones — whose pair is folded from loop.trigger unless the brain declares it, so an entity that would trigger again inside its window is one whose change did not hold, and a brain that wants a longer watch than trigger writes the block. omnislash doctor warns under Loop watch when an OBSERVED entity (a heartbeat, a scheduled pipeline) has a cadence that cannot deliver watch.windowRuns executions inside watch.deadlineHours; watch.mode: none is exempt
  • mustImprove on the metric, not a knob on the loop — off by default, because holding an inert change to a higher bar than “it broke nothing” would fight the human who chose to merge it. Declared on an objective, it settles a change that moved nothing unvalidated rather than validated, and the noise band it compares against is half the spread of the per-input movements over the compared pairs (never tighter than the metric’s tolerance, and falling back to the tolerance below three pairs, where a spread is not yet a distribution). A bare gain > 0 test adopts noise as progress on its first flaky day. Read only on the objective, and deliberately INERT elsewhere rather than a load error — the engine itself demotes quality to a guard when another metric becomes the objective, so a sibling’s role change would otherwise start failing a declaration that was legal when written
  • floor is the absolute bar a tolerance cannot state — per metric, optional: with direction: max the challenger median may not fall below it, with min it may not rise above it. A tolerance says how far a metric may move from where it was; only a floor says where it may not stand at all, which is the only way to hold a promise made outside the loop (an SLO, a pass rate a customer was told about) — ten changes each 4% worse are ten validated changes and a metric a third below where it started. Reported separately from regressed on the delta, because a metric can sit below its floor without having moved at all. Read on objective and guard and inert on observe, which is defined as “never part of a verdict”
  • observe (every kind) asks ONE function per tick and stores its record — after the merge the engine starts nothing: it stamps a watermark when the change goes live and, on every tick, asks the loop’s window (phase: 'watch', since the watermark — under repair the first watch.windowRuns runs graded under the cycle’s pinned judge; a tick the judge failed on fills no slot and counts toward judge health, the loop’s own replays never count), re-applies the engine’s filters to whatever it named, writes that window on the cycle (watch_window — the eval-forcing producer and the dashboard read the window’s progress off it), and asks the loop’s compare over the cycle’s window against it. null is “not yet” and the watch keeps observing; a VerdictResult settles the row on the spot and is stored verbatim as watch_verdict beside validation_run_ids (the settled window’s runs) and, under repair, validation_terms. repair’s compare is the trigger’s question (triggeredWithin): by the engine’s count of bad runs — the trigger’s own definition (isBadRun: failed, below threshold, or a missed metric target) — or by the brain’s shouldOpen where the entity declares one (the resolved function’s source is what tells the two apart), asked at every grade. minFailures bad runs settle regressed the moment they are counted, whatever the rest of the window brings (withheld only while the judge looks broken — the engine’s own read, which settles unvalidated at the deadline instead); a full window with fewer settles validated; a window the deadline closes short of both settles unvalidated — with an empty perMetric, which is how the autonomy breaker reads a repair unvalidated as blind (a comparator that DID measure and found no gain is not blind). Brain code runs inside the journaled tick step (60 s inactivity timeout) and a throw from window or compare settles the row unvalidated naming the function — never a killed invocation. The check’s record stays on the round (check_verdict); the lesson reads the watch’s perMetric first, then the check’s. Post-merge runs are on the entity’s own inputs, nobody’s pair, and comparing them against its history would measure the inputs (proposal a02) — which is why repair counts. Re-running a heartbeat would send real messages, re-running a pipeline is arbitrary brain code whose side effects the engine cannot reason about, and a workflow’s like-for-like measurement already happened before the merge (the pre-merge check, above). While the window is open the target’s executions bypass sampling, since an ungraded execution leaves the window short. launch is gone from ValidationStrategy: nothing is re-executed after a merge
  • watch.mode: none is declarable — the honest answer for an entity the brain would rather not watch. A change it ships settles unvalidated by design, with an unvalidated-by-design notice — explicitly “not checked”, never mistaken for “checked and fine”
  • unvalidated is a real terminal, and the comparator may now reach it — a watched window the deadline closed short with fewer than minFailures bad runs, an unmergeable PR past the deadline, a non-re-runnable entity, an unhealthy judge, or a comparator that read the evidence that DID arrive and found it too thin to tell a real move from noise. Partial evidence is not upgraded to a verdict in either direction, and no outcome but regressed opens a revert. MetricVerdictFn returns a discriminated union — validated carries reason: null, the two negative outcomes owe a string — so a brain comparator cannot ship a revert order with nothing after the colon
  • Deadline — loop.watch.deadlineHours (default 168h) bounds this wait — the evidence one, not the wait for a human answer — with the clock starting when the change went live rather than when the PR was opened; the merge wait it also bounds starts once the pre-merge check has answered, so the check’s own deadlineHours is never charged against it
  • Automatic revert — regressed opens a mechanical revert PR (merged through the same gate the change shipped under — autonomy.merge: auto arms auto-merge on it too, else a human merges), whose URL lands on the round’s revert_pr_url — a field of its own, because pr_url is the change that shipped and both the revert and its credential mint read it as such. The run workflow then follows the revert PR on its own wait (its own subscription to the revert PR’s events + poll, bounded by watch.deadlineHours from the revert’s opening) and records revert_outcome (merged / closed / unmerged) and GitHub’s revert_merged_at; while it waits, the producer opens no new cycle for the entity (grade, tick and owner alike — waiting on the revert of …), so the next analysis never reads a brain that still carries the regressed change. Under merge: auto the revert auto-merges and the hold ends on its own; a closed or overdue revert lifts it with the change still live
  • The verdict is persisted, not recomputed — the check’s settle writes the comparator’s own record (loop_proposals.check_verdict, on the ROUND whose PR it measured: per-metric incumbent median → candidate median, the median per-input movement, tolerance allowance, pairs compared, which metric tripped; per-input sides, losses and critical vetoes; and the reason) plus the tally (challengers_viable / challengers_total — viable candidate replays of the pairs promised for the check, good runs of the window for the watch) in the SAME statement as the status, so a CAS loser can never overwrite the winner’s evidence. Tolerances, metric roles and even the comparator are brain files that move — re-deriving a past decision from today’s declarations would explain it in terms nobody used to make it. The tally is recorded even where no comparator ran: “1 of 5 ticks observed” is the whole explanation of an unvalidated, and an execution that never happened leaves no run id to count. The dashboard renders a row’s LATEST stage as its verdict: once the watch has opened (the watermark is stamped), loop.list / getById / loop.get’s cycles attach watch — each observed run as good / bad / ungraded under the cycle’s pinned judge and the trigger’s terms (isBadRun, the watch’s own rule, not the pass column) with the window and the count that regresses — and that counted window headlines the card, chip and panel, with the check’s stored record shown beneath it as the pre-merge stage. A window still counting is read under the entity’s live terms, as the watch reads them on every tick; a settled row is read under the terms its settle was made under (loop_cycles.validation_terms, written by the watch in the same statement as the tally), so a windowRuns or threshold moved afterwards never relabels the evidence that closed it. A row the watch never reached shows the check’s record alone
  • Stage clock — proposed_at / applied_at beside started_at / completed_at, each named for the stage it closes, so time-to-propose, time-to-apply and time-to-verdict are subtractions in SQL. completed_at alone could not carry them: it means “this row is done” and is rewritten by whichever transition finished it last, erasing every earlier boundary
• Protected surface, applied before the write — one resolved ProtectedSurface — the turn’s PathConfinement { editable, denied, unreadable } plus maxChangedLines — per implementer turn, rendered in three places: the CLI harness’s native permissions (compiled from the implementer role’s file:read + file:write grant plus the surface — an edit outside editable is refused before it happens; Claude natively per path, Codex only as a writable root — its paths and read wall hold through the sandbox and the gate — and OpenCode not at all, so omnislash doctor fails an implementer role on it), the bwrap jail’s deny / mask mounts plus the hiding of every other copy of the brain on the host under isolation.enabled, and the diff gate before the commit. The proposer is told to say so in its summary if a criterion is genuinely wrong
  • Allow-list by default — editable is the accepted proposal’s own target files plus skills/<newSkill>/**; new files are allowed only under it. loop.editablePaths (entity frontmatter, globs) widens it for one entity — never brain-wide
  • The engine floor, add-only — denied is constitution/Evaluation/**, constitution/Loop/**, constitution/Agents/system/**, any *.loop.ts, constitution/models.json, omnislash.config.ts, memory/ and every declared memory.sources entry (memory has one writer, the memory tools — the loop never writes it), the deploy perimeter (db/, .github/, docker/, Dockerfile, Dockerfile.override, .dockerignore), the CLI agents’ config at any depth (.claude/, .codex/, .mcp.json, opencode.json), .git/, plus loop.protectedPaths from MANIFEST.yaml, which ADDS and never removes; denied beats editable
  • The judge is closed to reading too — constitution/Evaluation/** and *.loop.ts are unreadable: the proposer is not handed the rubric it is optimized against, and works from the per-criterion feedback on the evaluation instead. A wall on files: the proposer’s db:read reaches the judge’s recorded turns
  • The proposer reads the runs itself — loop/role-proposer.md grants file:read, db:read (db_query, db_schema) and loop:read (loop_history): the evidence files start a round, and the proposer reads whatever run, conversation, tool call, step or brain table explains a verdict; on a chat role it reads each episode’s whole dialog by its runId. A brain copy without db:read confines it to the evidence files. Widening is the brain’s call: the proposer’s cwd is the LIVE brain, so a resolved grant (role-general.md included) carrying '*' or engineering:execute hands it a shell that reads the judge’s files and writes outside any diff — omnislash doctor (Loop confinement) warns, as it does for a resolved '*' or shell on the implementer role
  • A bound on how much, not only where — loop.maxChangedLines (engine 600, three tiers: engine, MANIFEST.yaml, entity frontmatter) is counted at the diff gate over what the engine would commit: added plus removed lines across every gated file, a created or deleted file counting its whole length. A binary file is refused outright rather than counted — the implementer writes the bytes the gate reads, so any “content shaped like X counts zero” rule is a switch the implementer holds. Past it the apply is failed naming the count, the bound and the three largest files — never a truncated PR and never a partial landing; there is no per-file bound and no warn-only mode. It is the bound an optimizer rewriting the same artifact every cycle needs: GEPA’s prompts grew 75% and got worse without one, and the end state has a name, “context collapse”. The apply prompt states the number so the agent plans inside it; omnislash doctor (Loop confinement) warns when the bound sits below a file the loop actually edits; and since the key lives in the loop: block the gate compares before and after, the implementer cannot raise its own bound
  • By block — the evaluation: / loop: / chat: / budget: / gate: frontmatter of an entity file and the matching sections of constitution/MANIFEST.yaml, compared before and after at the gate (budget: is the money ceiling the entity’s own agents run under — budgets.md; gate: a heartbeat gate’s timeout, which could fail every tick before it is graded). This is the one that matters once metrics exist: the objective, its target and its tolerances live inside the very file the implementer is supposed to rewrite, so it edits the body and the rest of the frontmatter freely and those blocks not at all
  • Git belongs to the engine — the implementer only edits files and reports { summary, files }; it holds no git credential, no gh token and no shell (nothing is minted for a confined turn and the harness strips the engine’s own from the child env). The engine snapshots the tree before the turn — every dirty path with a content digest, plus the checkout’s .git/config and HEAD (pre-existing dirt in a live checkout is never the agent’s; a rewrite of an already-dirty file still is), gates what changed (surface, regular files only — a symlink never lands — measurement blocks, git metadata unmoved), copies exactly those files into a throwaway clone of its OWN repository (the brain baseline; in dev the live checkout, once its metadata is known intact) — each copy held to the digest the gate read the file under, so a file that moved between the gate step and the landing step fails the apply rather than landing uninspected — commits them on loop/<entity>-<hex> cut from the exact base commit the gate read (not a tip that moved after it; a path under a directory symlink the base tracks is refused, never written through), force-pushes under the deploy’s credential (one step) and opens the PR (the next). The one git command that runs in the agent’s tree is git status, with hooks off. omnislash doctor fails an implementer role whose resolved grant carries '*' or a shell. A violation fails the apply with the paths on the Retry card — nothing committed, no PR to close
• Lessons are rows, not prose (compounding) — every terminal round that had a proposal behind it writes one omnislash.loop_lessons row: the hypothesis it ran on (the round’s summary, or a proposer pipeline’s own hypothesis), the files it proposed to touch, the failure taxonomy of the evaluation the cycle answered, how it ended and — from the round’s check_verdict — how the metrics actually moved. Mechanical, no LLM call: every part was already distilled by the proposer or by the judge. The lessons used to be markdown written into agent memory and recalled by vector search, which made the plainest question a proposer can ask (“what was tried here before, and how did it end?”) answerable only if an embedding agreed, and left the dashboard parsing a heading back out of a memory line
  • All five terminals teach — validated, regressed, unvalidated, skipped and failed; the three the markdown lesson never wrote are exactly the ones a reader asks about. A terminal with NO round behind it (an analysis that produced nothing, an unresolvable judge, a cooldown refusal) writes none — there is no hypothesis to record. Ordered by the ENTRY handler at every terminal it reaches, not by the stages, and idempotent on (proposal_id, outcome) so an at-least-once step replay cannot double the archive while still letting a retried failed round settle a second, different way
  • Citations make a lesson measurable — the proposer answers with citedLessons, ids out of the lessons.json it was handed (required in the structured-output schema; the empty array is the honest “stood on none”), and the same step that writes the settle credits each cited lesson helpful on a validated round whose verdict something measured (strength paired or measured — a blind win credits nothing) or charges it harmful on a regressed one, in SQL so two rounds citing one lesson at once both land. An id naming no row moves nothing — a hallucinated citation must not fail the settle carrying it
  • A person’s “no” is not flattened into skipped — each recalled lesson carries its rejection, derived from the round and cycle rows (rejectionOf): human (the round skipped and decided by a person, with the note the dashboard’s Skip asks for — loop_proposals.decision_note, riding the approval tap as note) or timeout (the round still proposed in a cycle settled skipped: nobody answered the card); the loop’s own set-asides (a lost claim, an unpinnable judge or input set) record the round decided by the loop and are neither. And its verdict strength
  • Recall and retention are one seam — loop.lessons (maxRecalled 10, retentionDays 180), replaced wholesale per tier like autonomy, read live at the moment each applies. maxRecalled: 0 recalls nothing, so there is no parallel on/off key; recall puts what a person turned down first, then newest first, bounded after that ranking (recallLessons), and never ranks by relevance, because which of an entity’s past failures still matter is the brain author’s judgement. Expiry is one dated DELETE at the BRAIN tier on the scheduler’s loop sweep (every 5 minutes) rather than a sweeper entity of its own
• Verdict strength — paired / measured / blind — one derivation (verdictStrength in @omnislash-ai/loop) of how strongly a shipped change’s verdict was measured, off the cycle’s watch record and its merged round’s check: paired = the pre-merge check passed and the watch measured; measured = the watch alone measured (a per-metric reading, or repair’s k-of-n count with its stamped validation_terms); blind = nothing did (no record, a count that closed short, a watch a sibling’s change or a foreign edit confounded) — exactly the breaker’s “unmeasured”. Read by the breaker, the lesson’s helpful credit, loop_history and the dashboard (each settled outcome shows it)
• Cycle grades — Improvement / Tradeoff / Tie / Inconclusive / Regression — one derivation (cycleGradeOf in @omnislash-ai/loop, words CYCLE_GRADES in @omnislash-ai/types/cycle-grade) of how a settled cycle’s experiment came out, off the watch’s verdict record and its strength in the loop’s own terms (each metric’s tolerance and interval — no new number) — or, for a candidate the pre-merge check regressed, off the check’s record; blind reads Inconclusive, a cycle with no verdict reads no grade. Qualifies the status (a Reverted cycle may be a Regression or a Tradeoff), never stored, always shown with its n. Decision 0090.
• Your own proposer — loop.proposer.pipeline — one of the brain’s pipelines writes an entity’s changes instead of the proposer agent (engine default null = the proposer agent; brain-wide in MANIFEST.yaml; per entity in frontmatter, where null takes the proposer agent back). The loop SENDS its run handler a typed ProposerBrief (keyed once per round; the pipeline’s run row is the answer, read when the engine rings the cycle at the run’s end or at the cycle’s next look) — the proposer agent’s own evidence as JSON (the entity’s definition, window, opening grade, runs, metrics, lessons, proposal line, related failures — every document the proposer agent reads — and the loop.proposer.instructions of both tiers), cut by the same loop.evidence / lessons.maxRecalled bounds, plus the rails its files will meet — as a loop-launched run of its own, and it answers { summary, hypothesis, files: [{ path, content | null }] } or null / nothing (“nothing to propose” → the cycle skipped, no round). The answer is parsed where it lands: a shape the engine refuses, a reply that is not JSON, or a TerminalError, is a failed analysis with a Retry card; a refinement round is handed the round it refines (refining). The engine writes the files itself — no implementer — behind the same protected surface and diff gate (which also walls off every proposer pipeline’s own *.pipeline.ts, for the proposer agent too), then the same card, PR, check, watch, revert and lesson; every reader names the pipeline as the author. The proposer agent’s read-ban on the judge’s files does not bind a proposer pipeline (it is the brain’s own code); the write-ban does. omnislash doctor (Loop proposers) fails an id the brain does not serve. ProposerBrief / ProposerAnswer come from @omnislash-ai/pipeline-sdk
• loop_history — the loop’s ledger for brain code — the op loop.history, a read-only, safe Evaluation tool under capability loop:read (hitl: false), callable from a pipeline through callTool and live under loopLaunched: one row per cycle, newest first, filtered by targetKind / targetId / feature / since, bounded by limit and paged by cursor — the change (round, who wrote it — proposer, null for the proposer agent — hypothesis, files, PR), its merge (instant and gate) and revert, the check and watch verdict records, the verdict strength and the grade read off them, a person’s rejection with their note, the lesson. The columns are a documented contract (plain JSON; the table in self-evolving.md § Reading the history is the schema); instants are ISO strings
• loop_get_proposal — one round’s whole proposal — loop.get_proposal (loop:read) returns every change a round proposes (proposer-agent text changes, a per-file diff for a proposer pipeline), its decision, PR and the apply’s report; the dashboard opens it as the proposal sheet at ?proposal=<round>
• Merge detection is event-first, poll-fallback — the merge phase parks on a backoff ladder of the PR rung early by the PR’s own events: after its first read it opens a cycle resource watch on the PR’s key (github:pr:<repo>#<n>, whose delivery rings the cycle with no payload), and each segment reads the PR when the next event or the ladder’s rung arrives, whichever comes first. Where the deploy has a GitHub App, a pull_request closed delivery wakes the wait within seconds of the merge (after the watch’s short debounce), so the loop’s longest phase stops being a days-long poll. The gh pr view poll (2 min → 6 h) stays unchanged and unrelaxed: it is the PAT lane’s ONLY mechanism, it covers a delivery GitHub never made (at most once) and an App whose owner has not subscribed to pull_request, and its tick is also what re-checks the validation deadline. An event is a cue, never the verdict: it prompts an immediate gh pr view, and only GitHub reading MERGED (or CLOSED) ends the wait — anyone who reaches the inbound sink can record an event about the PR; the merge instant is GitHub’s mergedAt, never the moment the loop heard
• Declarative per-gate autonomy — loop.autonomy declares who answers at each of the loop’s two human gates (plus the two “we don’t know” policies below): decide: human | auto (the Accept card), merge: human | auto (the PR; auto arms GitHub-native auto-merge once the pre-merge check has answered, so required checks stay a gate) plus mergeMethod: squash | rebase | merge. No direct merge exists: mergePrAuto answers armed or unavailable with GitHub’s reason (the arm regex, or an HTTP 422 — the repo’s auto-merge setting off, a base branch that requires no status check so GitHub will not hold an arm, a forbidden method) and never falls back to gh pr merge itself; unavailable demotes that round to the human merge gate with an auto-merge unavailable: <reason> notice, never a silent downgrade, never a failed apply over an open PR. The engine publishes omnislash/diff-gate: success on the pushed head before it opens the PR (a status GitHub refuses for permission fails the apply round at once, and the apply asks GitHub the same before the implementer’s turn — a rate-limit 403 is not a refusal) and omnislash/validation from the check, so a base-branch rule can require both; omnislash doctor (GitHub merge gate, Infrastructure) — asked only while some entity is in the loop, since the loop is the gate’s only client — reads the base branch’s rulesets + classic protection and warns when omnislash/validation is not required, or when the repository has “Allow auto-merge” off (allow_auto_merge) while an entity declares merge: auto. Before those it asks GitHub whether the loop’s own credential may post a commit status at all — on every lane, by posting one on a commit that cannot exist (422 = granted, a 403 that is no rate limit = missing; nothing is written) — and a refused or undecided answer is reported ahead of the plan and required-context findings, naming the permission row (Commit statuses: Read and write) and the agent’s fix. Inside the deployment it judges the credential the loop actually posts under — an installation token where the App mints one for an https remote, otherwise the GH_TOKEN/GITHUB_TOKEN gh reads, so an ssh brain remote (an ~/.ssh/config alias included) is judged under that token; from a laptop it reads the rules with any token in the brain’s .env and leaves the deployment’s credential to the doctor inside it. A private repository on GitHub Free, which can carry no branch rule at all, is named as such; a configuration that leaves nothing to read (no remote, no credential, a token GitHub rejects or that cannot see the repository) is a warn naming its own remedy. Engine default is human/human — existing brains change behavior by zero; the block merges WHOLESALE per tier (engine → manifest → frontmatter), so the tier that writes it owns every key. An apply PR abandoned at the validation deadline has its auto-merge disarmed before the unvalidated settle, so an unmeasured change can never land later off a stuck check going green
  • A disarm is heard, not assumed — a person disabling auto-merge on the PR reaches the loop as a pull_request.auto_merge_disabled event on the PR’s watch, and every read takes autoMergeRequest on every tick (null while armed = disarmed). The event is a cue too: it prompts an immediate read, and the arm is given up only when that read finds it gone — a forged disarm cannot switch off the head check while GitHub still holds the arm. Either way the wait continues under the human gate with an auto-merge-disarmed notice. A head that moved past the vouched commit — the checked one, or the one the apply opened the PR on where the cycle has no check; the arm is bound to it (--match-head-commit) either way — disarms the same way (its synchronize event prompts that read at once).
  • Revert inherits merge — no separate knob: merge: auto auto-merges revert PRs too, because autonomy without self-repair rots silently. The revert runs step by step (revert-create-branch / revert-push / revert-status-diff-gate + revert-status-validation / revert-create-pr, the PR looked up by head before it is created) with the sandbox removed in finally, so a re-run never double-opens; the two statuses are success on the revert head, so a base branch that requires them takes the undo instead of holding it forever
  • Circuit breaker — maxConsecutiveRegressions (default 2) consecutive regressed verdicts demote both gates to human and notify, until someone re-arms (the entity’s dashboard page or loop_rearm); derived from the entity’s own verdict history (readBreaker → { streak, blind }: validated resets the streak, an unvalidated neither counts nor resets it — EXCEPT one that shipped through an autonomous gate and could not be measured (merge_gate = 'auto' on a row with merged_at — the effective gate, which nothing writes after the merge — so a watch.mode: none change that shipped on its own counts too), which is blind and trips the breaker on its own whatever the ceiling (unless the brain declared autonomy.onUnmeasured: continue): a loop that would ship the next one the same way is the failure the breaker exists for; the durable re-arm is loop_cycles.regression_acked_at on the reviewed row, acked from the entity page), never a stored autonomy state; the breaker never blocks a revert. null disables the STREAK ceiling only — blind trips under any ceiling. omnislash doctor names an unattended entity that took the opt-out under Loop autonomy, along with any auto/auto entity judged by quality alone
  • What a person owes the loop — listCyclesAwaitingPerson(rearm) (@omnislash-ai/infra): ONE statement, every gate kind — decide / retry (a pending HITL card of producer loop, data = loop.gate.v1: CycleGateDataSchema in @omnislash-ai/types/loop), grant (a pending grant_request from a live cycle’s own agent, coalesced subscribers included), merge (applied + merge_gate = 'human', due merge_wait_started_at + watch_deadline_hours), revert (a regressed change whose revert PR is human-gated — revert_merge_gate — and still awaited), rearm (the entities the caller found tripped under a declared auto gate, each resolved to the settle a re-arm acks) → { cycleId, gate, round, since, deadlineAt, hitlId, prUrl }, oldest first. The rearm input is the seam: tripped-under-an-auto-gate needs the resolved autonomy block, which is brain config
  • The demotion announces itself once, at the settle that crosses — loop:paused ({ …lifecycle, streak, blind }) plus a paused notice fire at the settle where the streak reaches the ceiling or a blind change lands, and at no later regressed settle: the entity is already paused there, and an alarm repeated on every subsequent failure is one its reader learns to ignore. The breaker-tripped-r<round> line on the NEXT proposal’s card stays as the standing reminder that this round is human-answered. The pause lifts only on the owner’s ack — there is no half-open probe and no timer, deliberately
  • The implementer can never grant itself autonomy — autonomy lives inside loop:, which is already part of the protected measurement surface gated before every apply commit
  • No fixed human step under decide: auto — the proposer and implementer of an autonomous round run with AuthContext.unattended: HitlGateway.request refuses their HITL requests before any row exists, so a grant request fails fast and a missing_grant stays a failure (carried to CLI harnesses over the MCP URL, inherited by spawned sub-agents). A broken analysis or apply settles failed at once — no Retry / Skip card, no lesson; the breaker does not count it, maxAnalysesPerDay bounds it. omnislash doctor (Loop autonomy) names each hitl: true capability the two loop roles reach once any entity declares decide: auto
  • Policies for “we don’t know” — autonomy.onInconclusive: human | ship | close (default human) answers a pre-merge check that could not judge: a person merges, the declared gate stands (the loop posts omnislash/validation: success by policy; the cycle history shows “merged without proof by policy”), or the PR is closed and the cycle settles unvalidated. autonomy.onUnmeasured: pause | continue (default pause) decides whether a blind auto-merge trips the breaker. Doctor names merge: auto + ship + continue together. Both keys are editable in the dashboard’s Policy view
• Kill switch — enabled: false — loop.enabled / evaluation.enabled AND across the tiers, so false in constitution/MANIFEST.yaml switches the whole brain off and no entity can override it (no brain function either: enabled is settled before window / shouldOpen). It stops NEW cycles (a grade, the trigger.every clock, Analyze now, an idea) and closes every cycle in flight that has not merged. The cycle reads the resolved switch before every step it takes until the merge, and a switch written through loop_set / the dashboard rings every live cycle it reaches. When it reads false, the loop cancels the card, disarms auto-merge, closes the PR, and settles the cycle skipped with one notice. The idea goes back to the queue and no lesson is written. /evolution reads such a cycle as closed · loop off (closedBySwitch, @omnislash-ai/loop), its Change chapter saying the PR was closed by the switch and nothing shipped. A switch edited another way (a pushed MANIFEST) reaches a wait at its next look (at most 6h). A merged change finishes its watch and revert. evaluation.enabled: false also stops the grading an in-flight check or watch waits on. Documented with the in-flight moves in self-evolving.md § Kill switch
• Supervising the loop — re-arm, hold, release, dismiss — four Evaluation-category tools that are the entity page’s buttons as code, each through one engine entry point (rearmBreaker / holdLoop / releaseCycle in @omnislash-ai/loop, ackLoopFailure in its control core), behind two capabilities: the hold is loop:hold (moderate, hitl: false — it only takes autonomy away, so an agent that sees trouble stops the loop without waiting), while re-arm, release and dismissal hand oversight back and stay loop:supervise (moderate, hitl: true by default)
  • loop_rearm — the same tripped-breaker guard as the dashboard’s Re-arm; the ack records its Actor in loop_cycles.regression_acked_by, shown in the cycle history and the Supervision list
  • loop_hold / loop_release — omnislash.loop_holds rows (target: an entity, or a lock group declared under loop.groups; who, why, when; released holds kept as history). A standing hold refuses every producer — tick, grade, “Analyze now”, a queued idea — and nothing else: gates unchanged, no card, a cycle in flight finishes. A group hold stands on every member. Hold / Release buttons sit next to Re-arm on the entity page, with the hold banner naming who held it and why
  • loop_ack_failure — dismisses one terminal failure from Loop failures and records who in loop_cycles.failure_acked_by; attention bookkeeping, not a re-arm
• The loop’s reads are ops — every read the Self-evolving page makes is one loop:read op an agent calls as a tool: loop_status (the fleet with each entity’s feature, preset, cadence, lock groups, own record, grading facts, the window its next analysis reads and the join plan; with joinOrder its place in the join order — graded first, then the most hand-tuned, joinRank — and people’s recent edits to its files, handEdits, from the brain’s git history; the features the fleet groups by), loop_get (one entity whole: status, supervision record, lock groups, live cycle and its agents, the way to a first cycle, ratings, ideas, lessons, and its newest cycles told whole with their grade), loop_trace (entities’ metrics over their graded runs — the loop’s recent window, or one entity’s whole history: values with the scale a person answers on, bad runs, brain versions, the level line cut at every shipped change, a marker per cycle with its grade; several entities answer their objective each), loop_summary (the window’s settled cycles, win rate, cycles per week by grade, the kept cycles’ uplift, gates owed — on the stats contract) and loop_list_agents (the judge, proposer and implementer as the brain configures them, with model ladder, grant and what it compiles to, where each runs, doctor verdicts and consequences; the proposer pipelines). The dashboard composes its pages from them and holds no loop composition of its own
• Agents run the loop through validated tools — loop_status / loop_policy (loop:read), loop_join / loop_set (loop:configure, hitl: false), loop_widen (loop:autonomy, dangerous, hitl: true) and loop_analyze (loop:analyze) are the loop.* ops the dashboard’s loop pages run too, so an agent’s click is the dashboard’s click — one definition, one action-log row per write against the entity it steers. loop_join / loop_set / loop_widen take dryRun and answer each file’s diff (files); loop_policy also answers the editors’ views (sections), the lock groups in scope with holders and members, the proposer’s added lines, one entity’s judge calibration and the loop’s code
  • Configure and autonomy are split — loop_set refuses a write that widens oversight (widens-oversight): autonomy, the change perimeter (editablePaths, protectedPaths, maxChangedLines) or the brain-wide loop switch, judged on resolved values for every entity the write reaches, before and after — and one that takes an entity out of a lock group a person holds (lifts-hold). Narrowing goes through. loop_widen makes the widening write once a person approves its grant, and answers each widened[] subject
  • One writer at a time, from any process — every loop-settings write (dashboard editors and tools alike) takes one cross-process lock and commits by content compare-and-swap; a file that kept changing or a lock held too long answers contended — “try again”, nothing written
  • Status names the next step — loop_status lists what each entity waits on (needsYou[]) with next: who acts, and through which card, PR or tool; the loop’s cards take no agent answer or cancel, and its PRs are a person’s to merge (a rule in the self-evolving skill — the engine cannot tell an agent’s merge apart)
• Lock groups — one variable at a time across entities — loop.groups (MANIFEST only: <id>: { lock: true, repair: bypass | wait }, engine {}) declares entities that share an outcome; loop.group joins them at any tier (nearest wins the list, [] leaves; doctor Loop groups fails an undeclared name). While a member has a change past its Accept and unsettled, or a regressed one whose revert is awaited, no other member opens a cycle (the producer refuses early, naming the holding change) or is accepted (the claim takes pg_advisory_xact_lock per sorted group, checks for a holder and takes the entity in one transaction; the membership is stamped on the row as loop_cycles.lock_groups). A repair member passes a repair: bypass group. A member’s watch that saw another member ship or revert after its baseline closes confounded (unvalidated, loop_cycles.confounded_by names the change): the comparator’s record is kept but never acted on — no credit, no revert (watch.onInconclusive included) — and the breaker counts it blind. Every watch, grouped or not, also closes confounded on an edit of the entity’s files (its defining files and the files its change landed) that landed on the brain’s branch after the baseline (git reachability, not dates) and is neither part of the cycle’s own merge nor a pure edit of the entity’s loop: settings — a person’s PR, an agent’s commit, another entity’s change to a shared file — stored as loop_cycles.confounded_by_edit. A member’s next window starts after the group’s last merge or revert (since, and ctx.groupChangedAt for repair’s last-n count). An Accept that loses the group race settles skipped naming the holder (under decide: auto at once, no card) and hands its idea back to the queue. Edit boundary: no change writes another loop entity’s definition files; what a member lists in its editablePaths is denied to every other entity’s change, unless that entity shares a group with it (an entity the lock does not hold would otherwise move a member’s numbers under a watch that settles clean; a fellow member is kept apart by the lock itself); and a member’s existing shared files (*.agent.md, skills/, constitution/Planner/) open only through its editablePaths. The entity page shows each group’s holder, members and waiting ideas; the fleet read carries the lock status
• Grant-gated auto-accept — a standing loop:auto_accept grant on a scenario (admin-issued, scenario-scoped, maxCalls-bounded, TTL’d, revocable) lets the analyze step apply its own suggestions instead of opening the card, burning one grant use and posting an informational notice — the temporary, scoped delegation layered over a human config, where autonomy.decide: auto is standing policy
  • Delegation, not risk scoring — “low-risk” is never computed by the engine; the capability sits in ADMIN_ONLY_CAPABILITIES, so no approval card can mint it and the planner’s vocabulary excludes it
  • Remaining gates stay — the apply PR is still merged through its own merge gate and the pre-merge check, the watch and auto-revert still settle the verdict; no grant (or any lookup failure) falls back to the card, a refined round or an empty suggestion set is never auto-accepted, and a tripped circuit breaker vetoes the grant path exactly as it vetoes the config path
• Loop events — the whole lifecycle, not just the analysis — loop:analysis.started / .suggested / .failed / .skipped from the analysis service, then loop:accepted / skipped / failed / applied / validating / validated / regressed / unvalidated / reverted / paused from the loop’s own transitions, each carrying the same envelope plus what its transition genuinely knows (the PR url, the challenger tally, the comparator’s reason, the revert url, the breaker’s streak / blind) — accepted, validating and reverted carry an auto flag telling the autonomous gate (config or grant, armed auto-merge) apart from a human, so a surface can tell human-gated from autonomous flow. accepted and skipped carry an actor BESIDE that flag, because the two answer different questions: auto says whether a person was asked, actor says who answered — the tapping speaker on the human path, and the cycle itself for every answer nobody was asked for (an admin-only grant carries no issuer to name, so the two autonomous branches are not separated here). Pure pub/sub — the row is the system of record and nothing work-triggering may hang off them — so they drive cards, the activity feed and dashboard invalidation, and never a side effect
  • The half that used to be silent is what makes the loop watchable — before them the loop’s page (then /self-evolving) was the one page in the dashboard that polled, because nothing past analysis announced itself; every Self-Evolving surface now invalidates off these and off *:eval.completed, with no bespoke clock
• Runtime health of the loop itself — the dashboard’s /evolution loop checks carry two that read the database rather than the brain’s files, because the surfaces above answer what the loop decided and none of them answers is the loop alive. Two checks, not one: a stuck cycle and an unread failure are independent facts, and a single check can only report the first that matches — folded together, one stuck row would silently delete the whole failure surface
  • Agents read both through loop_status: the fleet’s lifecycle (live and stuck cycles) and an entity’s failureRows
  • Loop lifecycle — stuck cycles, read-only — a pure classifier (findStuckCycles) over the machine-live rows (listMachineCycles) reports two shapes, read off the row alone — no Restate question, nothing that degrades when its admin is out of reach: failing (a segment leased the row and never parked or moved it: leased_at older than one segment’s lease plus a 30-minute slack — the phase keeps throwing on every retry) and unrung (no lease, and wake_at passed more than 30 minutes ago — nothing is ringing cycles: the scheduler’s wake reconciler or pipelines is down). warn, not fail: neither is lost — a failing cycle is ended by the engine at leased_at + 24 h (the hint names the instant), an unrung one moves the moment rings arrive — but each holds its entity’s claim until then. It never writes: the cycle machine is the sole writer of its row, and the wake reconciler (rings, never writes) is the only thing that acts on an overdue one. loop_status, the brief and the cycle’s story show the same row as In <phase> since … · next look in …
  • Loop failures — terminal failures, acknowledgeable — a failed settle, or a regressed one that shipped (merged_at IS NOT NULL — GitHub’s merge instant, recorded under every watch mode) and was never undone (no revert PR, or one closed / unmerged / past its deadline with no outcome — a revert still inside its wait is not listed), becomes a health row; a regressed the pre-merge check settled never shipped and owed no revert, so it is not one that persists until a human dismisses it from the page’s “need you” list, or an agent does with loop_ack_failure (loop:supervise) (loop_cycles.failure_acked_at, mirroring regression_acked_at, with who in failure_acked_by; the ack is guarded by the same predicate the list selects on, so a live row can never be pre-emptively acked into silence). The discriminator is the revert’s own record (revert_pr_url + revert_outcome), not a non-null error — a message survives a retried round, and it is absent entirely when the invocation dies between the settle and the revert. The revert failure is now RECORDED on the row rather than existing only as a chat notice that scrolls away, and both error and the ack are reset wherever a proposal re-enters the lifecycle, so an ack is per attempt rather than per row. The ack is not the autonomy re-arm: it changes nothing the loop reads, and the two write different columns so neither implies the other
• Per-cycle spend — loop_cycles.agent_ids links every proposer and implementer back to the cycle that dispatched it, across every one of its rounds, appended inside the SAME journaled step that creates the agent (idempotent in SQL, since a ctx.run is at-least-once), and the retention reaper exempts source = 'loop' so the rows it names — and the turn.completed events that cascade off them — outlive a validation window that is 168h by default (the spend ledger, usage_records, outlives them regardless). That is what turns “the loop cost $12 this month” into “this cycle cost $0.40, across two refines and a retry”, rendered in the cycle’s facts on /evolution and priced from the spend ledger (usage_records) by those agent ids. Challenger executions are deliberately excluded and the returned shape says so: their run ids reach agents through a different table per entity kind, and for an OBSERVED entity they are the entity’s own traffic, which would have cost the same with no cycle in flight
• Eval trend on the card — the suggestion card shows the target’s recent eval trend (pass rate + average score) for context, and — when the entity declares metrics — what the change is being optimized toward and what is guarding it, so a reviewer sees the terms before merging
• The proposer is given a goal, not an adjective — a metric-driven analysis is handed metrics.json (objective with its baseline and target, guards with their tolerances, the entity’s recent trend) plus an ## Optimization Target prompt section that names the mechanism out loud: guards are measured on the same challengers, so a change that buys its objective by doing less of the work will be reverted automatically