Runtime configuration: scope is invisible, prelude config is undeclared, and some values are unreachable

[andreasronge]

Problem

Runtime configuration is spread across three mechanisms with different rules, and
which one applies to a given value is not visible from any file a user edits.

1. limits is flat, so scope is invisible. All 24 manifest-narrowable names
sit at one level. workflow_heap_words is adjacent to evaluation_heap_words
and to run_duration_ms with nothing indicating that the first bounds the
orchestrator, the second bounds one mission evaluation, and the third bounds the
whole run. The scope is encoded only in a name prefix the reader has to know.

To be clear about what already works, because it is easy to assume otherwise:
heap sizes and timeouts are not hardcoded. They are :manifest_narrowable
rows in LimitCatalog, settable in a manifest and ceilinged in a host document.
The problem is legibility, not absence.

2. Prelude configuration has no declared contract. max_turns exists
nowhere in lib/ — three occurrences, all in .clj:

agent.core.clj:75   (positive-int-or (get cfg "max_turns") 4 128)
agent.core.clj:80   "max_turns" max-turns
agent.prompt.clj:9  :turns-remaining (get cfg "max_turns")

So it binds only because agent.core chooses to respect it, and a wrong value
is silently swallowed:

(agent.core/run-value task {"max_turns" "three"})   ; runs with 4 turns, no signal

There is no way to discover the accepted keys except reading the prelude source,
and no way to learn that your own key was ignored because you typo'd it.

3. Some values are unreachable from any file.

Value	Where it lives	Reachable?
pmap_timeout	Context.@default_pmap_timeout (5_000)	no — absent from LimitCatalog, and Runner.execute_workflow/5 never passes it
value-history depth (*1 *2 *3)	RunState.@history_depth (3)	no — a constant, not a limit

The pmap_timeout gap has teeth. Two concurrent agents under pcalls measured
4.1s against a hard 5s ceiling nothing can raise.

4. There is no per-agent budget. subordinate_evaluations is run-wide, so
two agents share one pot. If the first burns 15 of 16, the second gets 1, and no
file can prevent that. max_turns looks like a per-agent budget but is a
suggestion; the thing that actually enforces is shared.

Proposed shape

Group limits by scope, and let the grouping carry the meaning the prefixes
currently imply.

"limits": {
  "run": {
    "duration_ms":     120000,
    "provider_tasks":       8
  },

  "workflow": {
    "timeout_ms":       90000,
    "heap_words":     8000000,
    "pmap_timeout_ms":  30000,
    "capability_calls":    64
  },

  "mission": {
    "timeout_ms":       10000,
    "heap_words":     1250000,
    "evaluations":         24,
    "capability_calls":   200,
    "memory_bytes":   2000000,
    "history_depth":        3
  },

  "missions": {
    "research": {"evaluations": 20, "capability_calls": 180, "timeout_ms": 15000},
    "review":   {"evaluations":  4, "capability_calls":  10}
  }
}

Read top to bottom, that states the whole budget without knowing any prefixes:

• run — the shared pot: one deadline, one provider-slot budget.
• workflow — the orchestrator. pmap_timeout_ms belongs here because that
  is where parallel agents actually run, not inside a mission.
• mission — the default for every space.
• missions — per-space overrides.

Three narrowing levels, one rule at each: you may only ask for less.

host ceiling  ≥  limits.mission  ≥  limits.missions.research

So declaring a space can never buy budget the run did not already have. This is
the same rule per-space provider grants already follow on
spike/mission-spaces, where a space may only name providers that
providers.mission already selected.

history_depth becomes an ordinary mission limit rather than a constant, which
is what makes *1 *2 *3 configurable.

Declare the prelude config contract

Separately and independently: give the shipped agent entries a signature, using
the contract mechanism the runtime already has.

(defn run-value
  "..."
  {:signature "(task :string, cfg {max_turns :int?, mission :string?,
                max_program_chars :int?, max_observation_chars :int?,
                max_transcript_chars :int?, result_envelope :bool?}) -> :any"}
  [task cfg]
  ...)

Shaped maps are open — verified empirically, an undeclared key passes
through — so a user's own configuration keys keep working while the known ones
become validated and discoverable via (doc "agent.core/run-value") and the
rendered prompt inventory.

A contract violation performs no capability call, so it is retryable and
agent.core already converts it into model correction feedback. Measured:

declared ok      -> "t/3"
user's own key   -> "t/3"
wrong type       -> :prelude_contract_error
                    "cfgdemo/run-agent input cfg.max_turns: expected int, got string"

Known tradeoff: because the map is open, a typo in a declared key still passes
silently. Extensibility and typo-catching cannot both come from one map. If
typo-catching is wanted, the escape hatch is declared keys at the top level plus
a nested open sub-map for user keys.

Suggested split

These are independent and can land separately:

1. Signature on agent.core entries — metadata on three functions, no Kernel
   change. Smallest, and useful on its own.
2. pmap_timeout as a real limit — one LimitCatalog row plus two call
   sites. Should follow the parallel-agent hang investigation, since raising a
   deadline on a hang only lengthens it.
3. Grouped limits shape — a catalog presentation and manifest-parser
   change; enforcement points do not move.
4. Per-space limits — the actual work. RunState.reserve_evaluation/2
   already receives the space, so it is mostly making run-wide counters
   per-space.

Context

Measurements and the per-space groundwork are on spike/mission-spaces, written
up in docs/plans/mission-spaces-spike.md. That branch is spike code, not a
merge candidate.

[andreasronge]

Related: #1237 (named mission spaces). The per-space budget gap listed here as problem 4 is the piece that issue defers to this one — subordinate_evaluations stays run-wide on spike/mission-spaces, so per-space grants bound authority but not spend.

[andreasronge]

Superseded detail: this issue does not sketch multi-model selection, but the as-per-alias approach discussed alongside it is superseded by #1240, which adds a provider argument to llm-request instead. Reason: tool/... is a static form, so distinct capability names cannot be chosen at runtime without a closure or a hardcoded dispatch table in a shipped prelude. The trace objection to a parameter turned out to be wrong — llm_snapshot/3 already publishes the alias into run-started.

[andreasronge]

PR #1278 (merged) closes this issue's sharpest item — the unreachable pmap_timeout:

• parallel_timeout_ms is now a manifest-narrowable LimitCatalog row (compiled default 30,000 ms, installed ceiling 300,000 ms), threaded into workflow, subordinate-mission, and REPL evaluations and clamped by the run deadline, so a late-started parallel operation cannot outlive its run. The "two live agents measured 4.1 s against a hard 5 s ceiling nothing can raise" problem is gone.
• A second new row landed with it: evaluation_admission_timeout_ms, bounding how long a concurrent kernel-eval waits for the evaluation lease (Concurrent agent loops: 4+ pcalls workers fail, and live runs can hang to run_duration_ms #1241).
• Parallel timeouts are now attributed to the limit that actually fired (parallel_timeout_ms, workflow_timeout_ms, or run_duration_ms) in workflow error details.

Still open from this issue: the flat-limits legibility problem (scope invisible from names), the undeclared prelude configuration contract (max_turns silently swallowing bad values), the unreachable value-history depth (RunState.@history_depth), and the absence of per-agent budgets (subordinate_evaluations remains one run-wide pot — now shared more gracefully via queueing, but still shared).

[andreasronge]

Re-scope: item 3 is closed by PR #1278; items 1 and 2 stand unchanged.

3. Unreachable values — fixed for pmap_timeout. It is now a first-class
manifest-narrowable limit, parallel_timeout_ms, with a default/ceiling row in
LimitCatalog (limit_catalog.ex:23 — {:parallel_timeout_ms, 30_000, 300_000}),
threaded to the evaluator at evaluation.ex:341, runner.ex:206 and
repl_session.ex:592, published in mission_inventory.ex:314, and given a
distinct exhaustion message (runner.ex:668-670) so it is distinguishable from
the run deadline. The Context.@default_pmap_timeout constant survives only as
the library-level default.

The rest of item 3's table (value-history depth for *1 *2 *3, and anything else
listed there) has not been re-checked — worth re-verifying row by row before this
issue is closed.

1. Flat limits, invisible scope — unchanged. LimitCatalog still exposes
one flat namespace where workflow_heap_words, evaluation_heap_words and
run_duration_ms sit side by side with scope encoded only in a name prefix.

2. Prelude configuration has no declared contract — unchanged. max_turns
still exists nowhere in lib/; agent.core.clj:75 clamps it with
positive-int-or and a typo'd key is still silently ignored with no signal.

Item 2 is the one that keeps costing runs (see #1226, where the same config value
is computed every turn but rendered only on the last). Suggest keeping this issue
for 1 + 2 and dropping item 3 from the title.

[andreasronge]

Hit item 1 (limit legibility) from the outside during the 2026-08-13b new-developer smoke pass,
walking multi-agent fan-out for the first time. Adding the newcomer-path detail, since this issue
is the right home for it.

docs/guides/manifests-and-capabilities.md#narrow-installed-limits ends with:

Consult PtcRunner.Kernel.LimitCatalog for the complete names, defaults, ranges, and scopes, and
PtcRunner.Kernel.Limits for what each one bounds.

That is a user-facing guide pointing a user at library source for the values. The two questions I
actually had while writing a fan-out workflow — "how many agents can run concurrently before I hit
a ceiling" and "how much headroom does parallel_timeout_ms have" — are answerable only by reading
@manifest_defaults in lib/ptc_runner/kernel/limit_catalog.ex:

{:evaluation_admission_timeout_ms, 10_000, 120_000},
{:parallel_timeout_ms, 30_000, 300_000},
{:subordinate_evaluations, 16, 16},

The module's @moduledoc explains the concept (manifest_narrowable vs installed_only) but
carries none of the numbers, so even reading the docs for that module is not enough — you have to
read the data literal.

The guide's own example uses "subordinate_evaluations": 8, which a reader will reasonably take
for the default. It is half the default (16).

Adjacent, and the reason this cost me time rather than a lookup: exceeding
subordinate_evaluations reports only execution/workflow_failed: the workflow failed, so you
cannot learn the limit exists by hitting it either. Filed separately.