## Summary A sub-agent DAG node can now decide which of its downstream branches run. Before this, a background run could not turn on a result: every node ran, and choosing a path meant the host winding the run down and starting another. How it works: - A node that declares `routes` (route name to condition) is a decision node; `select` is `"one"` (the default) or `"many"`. Raven's per-node judge, the existing verdict call, picks the route or routes the node's answer satisfies. The node's own text never selects a route. A route that cannot be determined fails the node, with no fallback route. - A downstream node carries `when`, a guard over `<node>.<route>` and `<node>.done` atoms joined with `not`, `and`, `or` and parentheses, evaluated with three-valued logic: a route of a decision node that was never executed is unknown. Every decision node in a node's `depends_on` must appear in its `when`; such graphs are refused at submission otherwise, along with guards that can never hold and a route named `done` in any letter case. Validation keeps negation parity and the surrounding boolean expression: a double-negated `done` and a disjunction with a satisfiable arm are accepted, without expanding disjunctions into combinations. - A node that does not run is `not_executed`, with a reason: `when_false`, `when_unknown` or `upstream_not_executed`. A node whose dependencies all went unexecuted is not executed either; a failed or skipped dependency still skips its dependents first. - A merge node reads a missing upstream as a fixed sentence, `<This task is not executed and the output is missing, please go on without this output.>`, written outside every untrusted-content fence, plus a note listing the inputs that may be missing. A file reference to the files of a node that may not execute is refused at submission however its path is spelled: `@nodes/`, an absolute path into the node root, or a workdir path that lands there, symlinks followed. Windows case, separator and drive-relative aliases are recognized, and the advice keeps the declared node ID. - Node judgement is always on: the `subagentDag.verdictEnabled` switch is retired. Config migration 14 removes it with a notice, and drops it again on every later load should an older build sharing the config write it back. `raven playbook run` now judges its nodes too, on the same `subagentDag` settings and a pinned `verdictModel`'s own provider; with nobody there to answer, a node judged not to have accomplished its task fails on the judge's reason. A host with no judge at all refuses graphs that declare routes. Where it shows: - Run events, the manifest, `dag.get`, `tasks.list` and `dag.run_completed` carry `reason`, `selected_routes` and `route_evidence` per node, and `routes`, `select` and `when` from the graph. The instance registry's DAG-node rows (and `InstanceRow`) carry the outcome too, so a client that reloads before the run finalizes shows what a branch decided. `TaskCounts.not_executed` is a new counter. - TUI: a not-executed node shows a hollow marker and its reason in words; a decision node shows its selection on the node's second line, and the guard and route evidence in the detail and in `/dag <node>`. The Agents Overlay and the live agents strip leave not-executed nodes out, as the backend's agent lists do. - Web: the desk's tasks tab names not-executed steps and shows the same fields. - Playbooks pass the three fields through, namespace guard atoms with the run prefix, and keep them through compilation. - The `run_subagent_dag` schema, the DAG orchestration skill and the docs site (English and Chinese) describe routes, guards and the merge rule; CHANGELOG has the entries. A graph with no `routes` and no `when` behaves exactly as before: the same judge requests, events, records, summary and finish text. `route_evidence` is a quote the judge picks from the sub-agent's output; it is cut at 500 characters, keeps a lone surrogate from a malformed escape as the escape's own text, and never enters model-facing text (finish text, `dag_status`, exception reports). When a judge answer does not report a usable route, the judge is asked again at most twice, each time with one correction. The shared instance registry drops its cache when a write fails on the data rather than the disk, so a row the file cannot hold fails its own write and no other. Two Windows CI steps run the alias and finish-text regressions; the latter exposes the installed Git `cat` executable required by the existing fixture. ## Type - [ ] Fix - [x] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification Linux, Python 3.12.13, on this revision rebased onto the current main (`$CHECKS` is a temporary evidence directory): ```sh uv run --frozen --no-sync pytest -q -n 4 # 23 failed, 33229 passed, 162 skipped, 1 xfailed, 3 errors uv run --frozen --no-sync pytest $(git diff --name-only origin/main...HEAD -- tests/) -q -n 4 --idle-ceiling-strict --cov=raven --cov-branch --cov-report=json:$CHECKS/coverage.json # the 20 test files this branch changes: 2622 passed, 1 skipped (a POSIX permission case that does not apply to root) uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json "$CHECKS/coverage.json" diff --base-ref origin/main --head HEAD --threshold 90 # Diff coverage: 99.48% (764/768 executable changed lines), passed the 90.00% threshold ``` The full run's 23 failures and 3 errors are 25 tests. 24 of them fail the same way on the current main in this environment: the venv lacks `nltk` and `datrie` (16), a proxy is set in the environment (5), this box has its own `npm` in `/usr/bin` (1 install-script case), LibreOffice writes no `.xls` here (1), and the run is root (1). The 25th, `test_a_cli_run_left_on_the_machine_when_this_computer_stops_is_picked_up_by_the_next_start`, failed with its teardown in the full run and in one of two runs of its file, and passed in five runs on its own: it reads the remote-run record the moment its pid file appears, a race in code this branch does not change (#840 makes that test wait for both). The four uncovered changed lines are the gateway's `_verdict_provider` body, whose helper is tested on its own; a guard atom over a node that did not complete, which the runner never evaluates because it reads a guard only once every dependency completed or was not executed; and the cut of an over-long terminal output. Ruff check and format, `ty check` over the changed modules, the import contracts, `deptry raven`, commitlint, and `scripts/check_commit_messages.py`, `check_large_files.py` and `check_source_language.py` over this branch's commits pass. ui-web: `vitest run src/features/tasks/BoardCard.test.tsx scripts/gates` passes 50 files and 244 tests, and `tsc --noEmit` is clean. In Chromium a not-executed title whose first word is wider than the room beside its status now breaks that word instead of starting under a blank line, and every other tasks-board card renders pixel-identical, English and Chinese, light and dark. Firefox still starts such a title under a blank line and cuts it without an ellipsis. CI's `TUI checks` covers ui-tui. Mutation checks: removing any one of these makes its own test fail: the every-load strip of the retired switch, the quote's escape before the cut, the registry's cache drop, the node-root check in the tool, the runner and the replan path, the physical path through a symlink, the CLI's judge, its settings and its no-answer failure, and the pinned judge provider. A model reading only the DAG skill's catch-all paragraph answers that without a catch-all route the judge may pick the nearest route or fail the node; an earlier wording led it to answer that the graph always stops. A live run on `openrouter/z-ai/glm-5.3-flash`, two graphs with synthetic messages, selected the expected route at each decision node, left the unselected branch `not_executed` with `when_false`, and put the fixed sentence outside the fences. Earlier revisions of this change passed the native Windows selections (aliases, finish text, guards; Windows build 26300, Python 3.13.12). The final revision has not been rerun on native Windows or macOS. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes Security: sub-agent text stays fenced or out of model-facing text on every new path. The routes block in the judge request sits after the last untrusted fence and is labelled as the graph author's; the missing-output sentence is written outside every fence; `route_evidence` is bounded and reaches records, events, the registry and the UIs only. In the TUI, route evidence is drawn through the same path as a node's error text; neither strips terminal control sequences, which this PR leaves as it is. Behaviour changes: a config that set `subagentDag.verdictEnabled: false` now gets judged nodes; migration 14 removes the key and says so once. `raven playbook run` judges every node, one more model call per node, and a node judged not to have accomplished its task fails there instead of completing. New wire fields are optional except `TaskCounts.not_executed`, which is always present (0 when nothing branched). `InstanceRow` gains three optional fields, and a decision node's registry row now also stores its selection and up to 500 characters of route evidence. Conditional-artifact validation matches node IDs using the session namespace's case-insensitive identity on every host, including macOS. This conservatively rejects case-only spellings even on case-sensitive filesystems. Separator and drive normalization remain native, and unconditional file resolution keeps its existing behaviour. Rollback: revert the squash commit. A config already stamped 14 loads unchanged on the previous build, since the stamp only gates migrations; a user who had set `verdictEnabled: false` can set it again there, and a later build drops it again on load. ## Related Issues Related, found while building this and not changed here: #998, #999, #1000. Follow-ups from its review, not changed here: #1008.
Raven Documentation
This directory holds design notes, dated records, and developer references that are too detailed for the main README.
For first-time users, start at the root README.md. Domain terms live in
CONTEXT.md, routed from CONTEXT-MAP.md. Several files below are dated
records kept for their history rather than descriptions of the current tree;
each such file carries a banner saying so.
Index
showcase.md/showcase.zh-CN.md- more showcases, linked from each root README: real runs, each shown as its task graph and what the run produced.technical-report/- the Raven technical report: abstract, citation, and a link to the PDF, which lives on a GitHub Release rather than in git.documentation-references.md- public reference sources and implementation evidence behind the protocol, orchestration, permissions, and extension guides.dev.md- local development notes.browser-and-desktop.md- the model'sbrowser_*tools over the shared Chromium, and desktop control through a desktop MCP server; enabling, permissions, what was verified.TRACING_STANDARD_API.md- the tracing span contract between raven and raven-tracing.research-report-quality.md- how a deep-research report is graded against a competitor's, and whatscripts/research_report_audit.pysettles mechanically.sandbox/- BoxLite sandbox usage and debugging notes.specs/- dated design records (YYYY-MM-DD-*.md) plus the self-evolution SOP and playbook specs; each describes the tree as of its date.plans/- historical implementation plans; an archive, deliberately not held to today's layout.examples/- benchmark and runtime configuration examples.Proactivity-Plan.md/Proactivity-Implementation.md- proactive-behavior design intent and as-built notes.Proactivity-Cost-Analysis.md- dated cost snapshot (2026-04).memory-plugin-architecture.md- design record for the memory-plugin architecture; the bundled-in-tree layout it proposes was superseded byplugins-dist/.everos-memory-e2e-test-plan.md- dated end-to-end memory validation plan.skill-hub-integration-design.md- design record; shipped asraven/skill_hub/.