M3.5: multi-model (maker/checker) loops — roles, agent compiler, inter-stage/intra-run orchestration

[dpickem]

Summary

M3.5 makes a loop able to decompose into per-role agents on different
providers — e.g. a gpt-5.5 implementer and an opus reviewer — and adds the
runtime plumbing to make that portable and safe. A role binds a vendor-neutral
agent definition (behavior) to an execution binding (vendor + model); the
agent definition is the single source of truth for behavior and the engine is a
swappable binding on top of it.

Two execution modes:

• inter-stage (portable default): each role runs as its own ordered adapter
  invocation and hands a structured artifact (status, promoted ledger output
  paths + sha256 digests, stdout) to the next stage through the memory ledger.
• intra-run: role agent definitions are compiled into the harness runtime's
  native sub-agent format and one invocation spawns them as sub-agents.
  Cross-provider intra-run is native only on Cursor.

A single normalized ExecutionPlan (resolving the --vendor override, per-role
vendor/model, read-only policy, and output ownership) drives dry-run, preflight,
and execution so the paths cannot drift.

Cross-provider Cursor spawn — verified live

The exit criterion "a Cursor loop spawns a cross-provider sub-agent" is
demonstrated against a real cursor-agent: a gpt-5.5-high main agent spawned
the compiler-emitted reviewer sub-agent running on claude-opus-4-8-high
(confirmed via the run's structured taskToolCall, which carries
subagentType.custom.name = reviewer and model = claude-opus-4-8-high). The
opt-in smoke test reproduces it and is skipped offline per CONTRIBUTING.md:

LOOPCRAFT_LIVE_CURSOR=1 uv run pytest tests/test_cursor_live.py -q

Caveat: per-sub-agent model selection is plan-dependent (Max Mode / usage-based);
legacy request-based plans without Max Mode may fall back to the parent model.

What's included

• Manifest: roles block (Role = agent + vendor/model + own outputs),
  execution mode, role-name vocabulary, role-output validation, and role
  outputs in fleet producer-collision/DAG analysis.
• Agent definitions (agents.py) and compiler (agent_compiler.py):
  compiles a role def + model into the runtimes' current native schemas —
  .cursor/agents/*.md and .claude/agents/*.md (Markdown + YAML frontmatter),
  .codex/agents/*.toml (developer_instructions + sandbox_mode); compiled
  name = role key (unique destinations); verify compiles into the instructions.
• Orchestrator (orchestrator.py): normalized plan; inter-stage + intra-run;
  mode-correct preflight; reviewer verdict gating; read-only enforcement;
  aggregate runtime budget; structured handoff persisted to the ledger.
• Worktree-local outputs + safe promotion (outputs.py): outputs staged in
  the worktree and promoted by the control plane (no out-of-worktree writes);
  TOCTOU-safe (O_NOFOLLOW + fstat, unique mkstemp + atomic replace,
  validate-all-before-replace).
• Shared run/apply/deps check preflight; --vendor override propagation;
  durable per-stage StageRunResult records; corrected Cursor docstring.

Enforced vs deferred (M3.5 scope)

Enforced: per-role vendor/model; output ownership consistent across
modes/dry-run/fleet; read-only reviewer (control-plane hash check inter-stage;
native readonly/sandbox_mode intra-run; read-only role rejected under a
Claude harness); a single explicit reviewer Verdict: PASS/FAIL
(missing/conflicting/FAIL fails and stops the pipeline); safe, success-gated
promotion; aggregate runtime budget from pipeline start; live Cursor
cross-provider sub-agent spawn (above). Role tools are policy-validated
(READ/EXECUTE/WRITE), not yet mapped to runtime-native allowlists.

Deferred (documented, not dropped): a code maker/checker against a real Git
worktree/diff (with L4); max_turns/max_tokens enforcement (needs adapter
usage telemetry) and max_consecutive_failures (scheduler/store boundary).

Review history

Two review rounds are addressed in-branch, each with a report + response under
docs/review_notes/:

• Review 01 (0a75645): shared preflight; mode-correct preflight; read-only
  enforcement; verify/tools; success-gated + symlink-safe promotion; structured
  handoff; normalized ownership plan; --vendor propagation; current runtime
  schemas; role-name/stage-log containment; aggregate runtime budget; unique
  compiled destinations; CLI-level tests; typed signatures.
• Review 02 (c00ef10): verdict gating + pipeline stop; intra-run verdict +
  harness read-only/model-compat gating; promotion TOCTOU hardening;
  plan-consistent effective_outputs; ledger-persisted handoff + untrusted-stdout
  fencing; durable typed stage records; dry-run uses the plan; Pydantic models;
  role-tool policy validation; fail-closed direct execution.
• Live Cursor verification (92005e9): the cross-provider spawn demonstrated
  end-to-end + opt-in smoke test.

Test plan

• make test — 410 passing, 1 skipped (the opt-in live test), fully offline
• make compile / make validate / make check
• Live (optional, paid): LOOPCRAFT_LIVE_CURSOR=1 uv run pytest tests/test_cursor_live.py -q

Note: two offline tests write .cursor/agents/...; they pass in CI and with
the sandbox disabled, but fail under a local Cursor sandbox that protects
.cursor paths.