[vinniefalco]

This started as one commit, the model_only_call flag. It now holds 29, in seven groups and one housekeeping commit, in branch order:

• The model_only_call flag (1 commit): a Pack can keep a tool in the catalog while a script's tools.call refuses it.
• Built-in model roles and a model that belongs to the chain (8 commits): every prompt gets five fixed roles, the Host maps roles to models, and models.use now lasts for the rest of the chain.
• Plain model handles (1 commit): a handle holds fields only, and the models functions are the one way to run a model.
• A smaller run API (11 commits): the Engine checks a run's start conditions in its first step, the Engine and the Harness share one outcome type, and the facade drops what no production code uses.
• Housekeeping (1 commit): cf572c063 moves the October plan files under vibe/2026-10/, adds a line to crates/plugin-std/AGENTS.md that each tool's source goes in its own directory named after the tool's Lua name, and shortens the doc link in crates/runvil-internal/engine/src/execute/error.rs that failed the docs job.
• A looser source layout rule (1 commit): 4cec10f24 replaces the three-file minimum for source subdirectories in AGENTS.md.
• Real file tools in the std Pack (5 commits): Access::read_range, then the shared code with a real Read, the glob matcher with a real ListDir, and a real Grep, and then the commit that closes the plan.
• Mount parents and a demo mount (1 commit): 331a2933b makes the parents of a mount show up as directories, adds a demo that maps a local directory into each run behind a switch that is off, and changes the built-in chat agent to declare the std tools.

The diff is 415 files, +19,228 and -7,445. Of those files, 222 are tests, fixtures, benches, and examples, and 22 are in vibe/ (19 renames into vibe/2026-10/ and 3 new plans). Source and docs outside tests, plans, and the API listing change by +6,432 and -3,828 lines, so the branch adds about 2,600 lines of non-test code, most of it the file tools. Before the file tools it removed about 780. crates/runvil/public-api.txt loses 327 lines and gains 73.

Each commit message gives its own account, and the commits build on each other in order, so reading them in order is the easiest way through.

Add the model_only_call flag to ToolInfo

A Pack may render a tool differently for each model: other parameter names, another schema, another description. Lua cannot read a schema, so a script that calls such a tool writes JSON from a guess. The tool still has to stay in the catalog, because tools.offer("std/replace") has to name it. So the flag keeps the catalog entry and refuses the script's call. The model still calls it, because the arguments a render shaped belong to the model that receives them.

Three facts stay independent:

• In the catalog: Lua can name it, and tools.get returns a tool object.
• Offerable: tools.offer accepts it, alone or with its Pack.
• Script-callable: the new flag. false means tools.call refuses it and the model may still call it.

How it works:

• ToolInfo::model_only_call and its builder sit beside structured_output, survives_stop, and describes_tools in crates/runvil-internal/types/src/tools/info.rs. It has #[serde(default)], so a run log written before this change still loads. ToolInfo::new leaves it false, so every existing tool behaves as before. The key is always serialized, so a recorded run shows the flag.
• tool_route in crates/runvil-internal/engine/src/execute/scheduler/tool_call.rs refuses in its script branch, after the one catalog lookup that a bare id and a tool object share. The model branch resolves against the section's frozen sets and is untouched.
• The refusal is Error::ModelOnlyToolCall { name, id }, kind RunErrorKind::Tool. It reaches Lua as an error table tagged model_only_tool, so a prompt can pcall it and tell "model-only" apart from "no such tool".
• bind in crates/runvil-internal/engine/src/execute/scope.rs copies the catalog's value onto every rendered tool with a catalog id, so a render cannot clear a declaration its own Pack made.
• The Lua tool object gains model_only_call as a fifth read-only field.

No tool sets the flag yet. This is the mechanism only. The plan is vibe/2026-10-31-1-model-only-call-flag.md.

Give every prompt five model roles

Before this change a prompt wrote a models: block naming its own role labels, then called models.default(label) before its first model call. The Host then bound every declared role to its one current model. Now every prompt has the same five roles, and the caller decides which model fills each.

• ModelRole is a closed type with Default, Strong, Small, Fast, and Creative, in the fixed order of ModelRole::ALL. It is #[non_exhaustive], reads only its lowercase names, and the error for any other name lists all five.
• The caller gives RunConfig::with_models one map from role to model. A role with no entry uses the default entry. An empty map means the caller has no model, so a model call raises ModelRequired and a prompt that never calls a model still runs. A map with entries but no default entry is refused before the run starts, with a notice that the caller's role map has no default (RequirementCheck::Unbound).
• fill_model_set builds one binding per role for every prompt, whether or not the prompt names the role.
• models: front matter now only attaches requirements to those five roles. Each may state min_context and thinking. A role outside the five, a field outside those two, a repeated role, and a zero minimum are parse errors. description: and the keyword lists are gone, along with ModelKeyword, ModelRoles, and ModelRolesIter. Frontmatter::role_requirements is the one accessor.
• Requirements are checked against the model that fills each role. thinking: true fails against a model that never thinks, thinking: false against one that always does, and a declared value sets the thinking switch on that role's requests only.
• The run's model set is built once and shared as an Arc<ModelSet>. The mutex, ModelView, ModelSetError, and the default alias with its writer are deleted, so nothing writes to the set during a run.
• models.default is deleted. Every section starts on the default role's model, or on no model when the caller gave none.
• models.use takes a role name or a handle and applies its options on top of the handle's own settings. models.get returns a role's handle without selecting it. The new models.current returns the handle for the section's model.
• ModelBinding drops its keyword list, so a handle shows its label, name, model id, description, context, thinking switch, and provider. A role's description is the description of the model that fills it.
• Workshop's ModelDto reports each declared role as its name, minimum context, and thinking requirement, and the run panel shows them as text. parseModel rejects a thinking value that is neither a boolean nor null.

Make the current model belong to the chain

A switch of model used to end with the section that made it. Now it lasts across the sections of a chain.

• A chain starts on the default role's model. The root walk that follows the opening pass starts on the model that pass ended on, including when a jump leaves the pass.
• A call child and a spawned task, which includes every fanout arm, start on a copy of the parent's model taken when the call or spawn is dispatched. A task waiting in the queue is not changed by a later switch in its parent, and a child's switch never reaches its parent or its siblings.
• Chain owns the selection its section VMs share, and ChainStart holds the model it starts on.
• tasks.fanout has a model-first form, tasks.fanout(model, worker, collection). The parent switches to the given model only while the arms are spawned, and is put back before the first wait and also when a spawn fails part-way. It lives in __impl_fanout.lua, so the scheduler and the spawn request do not change. A first argument that is not a handle, or any other argument count, fails with an error that says what was expected.

Make model handles plain values

A handle holds its fields and has no methods. models.infer and models.loop take an optional leading handle, and the compactor of models.loop stays optional. handle_method, HANDLE_METHODS_REGISTRY, and the handle_methods table are deleted, and LOOP_ARITY now reads models.loop takes (compactor?) or (model, compactor?).

Check a run's start conditions in its first step

A Run always holds a boxed Scheduler, so a run that cannot start needs no state of its own. On the first step, check_start checks the runvil: version, then probes the declared store, then checks the prompt's requirements. A failed check ends the run and reports no run events. This replaces Start, Stillborn, Spent, prepare_state, and the refusal step the caller used to run before it built the run.

• RunConfig::with_models replaces prepare. with_packs takes one map of RosterEntry values, and the Harness reports each Pack's status through the roster.
• Requirements, UnmetRequirement, RequirementCheck, MissingService, UsablePack, and UnavailablePack leave the facade. The facade exports runvil::packs::RosterEntry.
• A run with no with_packs call checks no declared Pack. A run with an empty roster finds each declared Pack missing.
• When a start check fails and the cancel flag is set, the first step ends the run Cancelled. An unsupported version and an unmet requirement together report the version failure first.
• A refused run is now prepared and driven like any other, so its record holds the parse events and then the end.

Use one outcome for the Engine and the Harness

Step::Done holds a closed RunOutcome: Completed, Failed with a RunErrorKind and a message, or Cancelled. The Harness records the outcome the Engine returns and no longer converts it, so effect_loop-outcome.rs is deleted. RunResult, RunError, and SourceLocation leave the facade.

• The failure message holds the error's text and its source() chain. A parse failure adds (prompt {name}, line {line}, column {column}) with the parts it knows, and an internal failure adds (at {file}:{line}).
• Harness::run begins the record before it resolves the model, so every run has a record and one outcome. A cancel before or during the model lookup ends as Cancelled, and a failed lookup or a stall ends as Failed. HarnessError keeps only Recorder, DriveError is gone, and RunReport::run_id is a RunId, no longer an Option.
• The step that decides a run lists every outstanding effect in withdrawn. The effect loop answers Dropped for each one without performing it. Run::decided, Run::cancel, and Run::cancel_handle leave the facade, and the caller cancels through the flag it gives RunConfig::with_cancel.
• Preparation failures use Engine kinds: Parse for a parse failure, RequirementsUnmet for an undeclared or missing input file, and Vfs for a store failure on an input. The Harness wrote Input for all three.

Delete facade surface that nothing uses

• The record types EffectRecord, AnswerRecord, ChatAnswerRecord, ToolAnswerRecord, and FailureRecord are pub(crate). Effect::record and EffectAnswer::record return the record as a JSON Value, which is the value the Harness stored before.
• Removed: Flags, ReplayError, the replay module, RunUid, with_flags, the RunConfig getters vfs, tools, seed, started_at, and flags, the events TaskResumed and TaskNote, ToolErrorKind::Cancelled, and the is_retryable methods.
• IdError is the one error for every id parser and both catalogs. It replaces seven error types and their kind enums, and each message text stays the same.
• RunErrorKind goes from 12 kinds to 10. UnsupportedVersion maps to Parse, Determinism to Vfs, and ModelRequired to RequirementsUnmet. from_tag still reads the retired Version and Determinism tags, so a stored run keeps its meaning, and as_str never writes them.

Split the run state and rename RunContext

RunState becomes SharedState, which holds the run-wide fields behind one Arc, and ChainState, which holds that Arc plus the fields a chain fork replaces (reporting, args, and argv). Every fork shares one SharedState. RunContext is renamed RunConfig in the Engine, the facade, the Harness runner, harness-gateway-client, and their tests, because the type holds the caller's inputs for one run and its module is config. HostRunContext in the Harness runner is a different type and keeps its name. The last commit fixes the execute module doc, which listed cancel as a method of Run.

Loosen the source layout rule

AGENTS.md said a source subdirectory must hold at least three files, and that a smaller group sits beside its parent as foo-bar.rs files wired with #[path = "foo-bar.rs"] mod bar;. The repository had about 250 of those attributes in src/ trees, and 185 of them only put a test file beside its module. The rule now says a module with more than one file keeps them in a directory named after it (foo.rs beside foo/bar.rs), a directory may hold any number of files, a module's unit tests go in foo/tests.rs, and new code adds no #[path] for layout. The existing attributes stay, because removing them would touch about 200 files and change no behavior.

Make the std file tools real

The std Pack shipped as six stubs that all answered one fixed text. This branch makes Read and Grep real and adds a seventh tool, ListDir (Lua id std/dir). Write, StrReplace, Delete, and Glob are still stubs. Every tool reads through the run's virtual filesystem, so the run's mode and policy apply to each access, and the Pack never touches the disk itself.

• Access::read_range(path, offset, len) (07c1cbe7a) takes the same four steps as read (gate, read claim, event, backend) and passes the range to the backend's own read_range. It is the one new facade method, so public-api.txt gains one line. RealBackend reads only the bytes asked for, and a backend that does not override it reads the whole file and slices it.
• Read (bea66707c) numbers each line as 1|text, caps its output at 100,000 bytes on a line boundary, and ends a cut read with a trailer that names the next offset. It stats the file first, reads at most 16 MiB through read_range, refuses binary content by sniffing the first 8,192 bytes, decodes UTF-8 lossily and UTF-16 by its mark, and names the path in every failure.
• ListDir (316a76f0b) prints a bullet tree, breadth first, under a 15,000-byte cap with a note when it stops. It skips entries named .git, lists every other dotfile, and never enters a link. Its wire name is ListDir, not Cursor's deprecated LS.
• Grep (f7472905c) uses the Rust regex crate and a literal flag, walks in path order, and pages with head_limit and offset. It counts what it skips by reason instead of failing on one entry, and it yields every 32 files or 2 MiB so a cancel can reach it.
• Shared code in crates/plugin-std/src/: refusal.rs words every VfsError the same way for all tools, text.rs holds decode, binary sniff, line split, and clip_to_boundary, and matcher.rs is a glob matcher where only * and ** are special and a relative pattern matches at any depth. clip_to_boundary is the only function that shortens text inside a line, so no cut splits a UTF-8 code point.
• Tests: plugin-std runs 386 tests, and its yield test counts Pending polls over 1,000 seeded files. A real-directory test in crates/workshop/server/tests/it/std_real_directory.rs mounts a directory with RealBackend::rooted and runs the list, find, read, and read-the-next-window flow through the Pack. It lives in workshop-server because a Plugin crate may not depend on the vfs crate.

94e6a172b closes the plan that drove these four commits.

Show mount parents and add a demo mount

The VFS router served each path from its longest-prefix mount and nothing else, so a directory that existed only because a mount sat under it did not exist. A model that listed / found nothing, and one that tried /_runvil got "Path does not exist", though /_runvil/language-guide worked. The router now reports such a directory: it exists, stats as a directory, and lists the mount's next path segment beside whatever its serving backend holds. The code is mount_children in router-access.rs, with three tests in router-tests.rs. This changes behavior for every VFS with nested mounts and changes no signature.

The same commit adds a demo in crates/workshop/server/src/agents/language_guide.rs. It maps one local directory read-only under /_runvil in each run, so a prompt can read the language guide with the file tools. The directory is a path on one machine, so ENABLED is false, and that constant is the one switch. Its tests map a temporary directory and run a prompt over it, so nothing in the suite needs that path.

chat.md declares std, offers user-input and std, and holds a commented-out messages:system line that names /_runvil/language-guide. The chat gate tests skip a leading system message, and the compaction mock does not count one, so they pass with that line on or off.

Breaking changes

For prompt authors:

• models: may name only default, strong, small, fast, and creative, each with min_context, thinking, or both. Any other role, any other field, and a zero minimum fail to parse. There is no migration message.
• models.default(...) is gone. A section that never calls models.use runs on the default role.
• A handle has no methods. Pass it to models.infer or models.loop as the first argument.
• The sample prompts and the built-in chat agent moved to the new keys, and greet.md and hello.md lost their models: block.

For code that embeds the Engine or the Harness:

• RunContext is RunConfig, prepare is with_models, and Step::Done holds a RunOutcome.
• The facade drops the types listed above and gains Access::read_range. crates/runvil/public-api.txt loses 327 lines and gains 73.

For recorded runs and Workshop:

• A ToolInfo now always serializes model_only_call, so a render answer record shows "model_only_call":false. A line without the key still reads as false.
• The run log reads the retired Version and Determinism tags as Parse and Vfs. It reads a stored tag it does not know, such as Input, as Internal with the stored message.
• Workshop no longer prefixes a failed model lookup with "the run's model could not be resolved". A run cancelled before it starts now has a record with nothing between begin_run and end_run.
• Workshop's built-in chat agent now declares std and offers user-input, std, and web, so its model can call Read, ListDir, and Grep, and can ask the operator a question.
• A VFS with nested mounts now lists the parents of each mount as directories.

What this does not do

• No production Host picks a model for each role. The Harness turns its one model into a map that holds only default (crates/harness-internal/runner/src/prepare.rs), so strong, small, fast, and creative all resolve to that model. Only an embedder that builds its own map can fill them differently.
• The language guide lives in cppalliance/runvil-docs, not in this PR. Its model chapters match this branch in runvil-docs commit 1b99039: chapter 10 is rewritten, and the examples, errors, and links in the other chapters follow it. That commit is not pushed yet, so it needs pushing alongside this PR.
• No compatibility path, alias, or migration error exists for the removed prompt forms.
• No tool in crates/plugin-std sets model_only_call.
• ModelRole has no FromStr or Display, because the serde error already names the five roles.
• Write, StrReplace, Delete, and Glob in std are still stubs, and the read record that Write will need is not built.
• ListDir and Grep skip entries named .git and apply no .gitignore, so a real repository's target/ and node_modules/ are searched. A shared ignore module comes later.
• Workshop mounts nothing real by default. The demo mount is off, and the directory it names is a path on one machine. No test covers the demo mount with ENABLED set to true.

How this was verified

CI at 331a2933b, the head of this branch: every job passes. They are api-surface, check-workshop, check-workshop-linux, ci-green, clippy, docs, fmt, msrv, supply-chain, test, and ui.

CI at cf572c063, before the file tools: every job passed too. They are api-surface, check-workshop, check-workshop-linux, ci-green, clippy, docs, fmt, msrv, supply-chain, test, and ui. The docs job had failed at 3527ad195 on rustdoc::redundant_explicit_links in the doc of RunErrorKind, where [`RunOutcome::Failed`](super::RunOutcome::Failed) repeated its own target, and cf572c063 fixes it.

Each file-tool commit ran its focused tests, and the Grep commit ran the full gate set: workspace and Workshop nextest, both clippy runs with warnings denied, fmt, rustdoc, cargo test -p build-xtask, the wording scan, and cargo xtask api --check. For the mount commit, the Workshop suite passes (320 tests) and the rest of the workspace passes (4,065 tests).

The guide in runvil-docs builds with cargo xtask site in its books-only mode, with RUNVIL_DOCS pointing at the clone (mdBook 0.4.44). A link check over the guide finds only the two index.md files that the site assembler writes, and the rendered chapter 10 has every anchor the other chapters link to.

The commit messages name the tests that pin each change. A few to know:

• ModelRole: the order of ModelRole::ALL, the round trip through as_str, and a reviewer role that the error rejects with all five names.
• The start gate: a_run_that_cannot_start_reports_its_failure_on_the_first_step.
• Retired tags: a_retired_tag_parses_to_the_kind_that_absorbed_it_and_no_kind_writes_it.
• Public records: every_kinds_public_record_is_json_that_round_trips_exactly.
• The flag: a script's tools.call by id and by tool object both fail with ModelOnlyToolCall, pcall catches it, tools.offer still accepts the tool, and a model's call of it reaches a ToolCall effect.

Reviewer notes

• Most of the diff is mechanical. 222 of the 415 files are tests, fixtures, benches, and examples, and the RunContext to RunConfig rename touches many of them.
• The model commits depend on each other, from 4f547a6b9 (the five roles) to 7075dfc4c (the model-first fanout), so review them in order. vibe/2026-10-31-2-built-in-model-roles.md holds that plan, and d4a6e3f3c closes it.
• The file-tool commits build on each other too: 07c1cbe7a, bea66707c, 316a76f0b, then f7472905c. vibe/2026-11-01-1-std-read-listdir-grep.md holds that plan, and 94e6a172b closes it.
• The start-check and outcome commits change what the facade exports and what the Harness records. The public-api.txt diff in each commit shows the exact surface.