agents-relay 2.0.30 → 2.0.32

package/README.md

@@ -121,7 +121,7 @@ Planner-created tasks use stable IDs and the existing parent/subtask tree, so
 retries and daemon restarts do not create duplicate work.
 Task producers must follow `skills/agents-relay/contracts/task-job-contract.md`; that shared skill contract defines story size, lifecycle events, review, and auto-merge semantics.
 
-Execution routing is code-driven: Relay builds complete executable worker+model routes from authoritative runtime/model/resource facts, removes only impossible routes, then calls the generic typed `decide(request, contract)` boundary once. Free-text routing guidance and task/resource/capability signals are soft decision facts; decision failure falls back deterministically to a usable Codex default route. See [Execution Router and typed decisions](docs/worker-model-routers.md).
+Execution routing is code-driven: Relay builds complete executable worker+model routes from authoritative runtime/model/resource facts, merges profile defaults with the user's explicit `[choices]`, deduplicates them, removes only impossible routes via hard gates, then calls the generic typed `decide(request, contract)` boundary exactly once with one merged choice list and the `[routing-instruction]` text forwarded verbatim. Task/resource/capability signals and the routing instruction are soft decision facts; decision failure falls back deterministically to a usable Codex default route. See [Execution Router and typed decisions](docs/worker-model-routers.md).
 All task producers use the same story-size contract: `S`≈5 minutes, `M`≈15 minutes, and `L`≈45 minutes of normal-reasoning execution, with `M` as the default. `high` reasoning doubles that overall window. ChatGPT Browser Worker start-ack timeout is derived as one third of the effective overall timeout, clamped between 1 and 5 minutes. Orchestrators and planners should choose `storySize`, not raw timeout milliseconds; `--timeout` remains only as an explicit compatibility/debug override.
 
 Autonomous jobs can also be scheduled. The Job marker stores a five-field cron expression, IANA timezone, next run, and missed-run/concurrency policy. The daemon evaluates the SQLite-backed managed Job view and validates durable schedule facts before claiming a due slot. A repository heartbeat invokes `tick` at 10-minute resolution. See
@@ -193,7 +193,7 @@ External product feedback uses the reusable `src/feedback.ts` contract. See [doc
 
 reconcile leases and launches ready tasks without waiting inside the runtime scheduler; the CLI waits only long enough for its launched workers to persist results. agents-relayd (or the equivalent npx agents-relay serve) is the watchdog/dashboard mode. Model-backed workers require --events nats; the event transport carries authoritative terminal worker events as well as wake/progress traffic. See [docs/service.md](docs/service.md). --file PATH is explicit local demo/test mode only.
 
-Router Rules are stored at `~/.agents-relay/execution-router-rules.md` by default. `agents-relayd --execution-router-rules PATH` selects a different file for that daemon process; the explicit CLI path takes precedence over `AGENTS_RELAY_EXECUTION_ROUTER_RULES`, which remains supported for compatibility.
+Router Rules are stored at `~/.agents-relay/execution-router-rules.md` by default and use `[choices]` plus `[routing-instruction]` sections (see the Execution Router doc). `agents-relayd --execution-router-rules PATH` selects a different file for that daemon process; the explicit CLI path takes precedence over `AGENTS_RELAY_EXECUTION_ROUTER_RULES`, which remains supported for compatibility.
 
 `agents-relayd` without `--pr`/`--id` runs in workspace mode by default: it discovers nested Git repositories under `~/Workspace`, keeps only GitHub `origin` remotes, and aggregates their managed PR jobs into one dashboard and worker pool. Pass `--workspace PATH` to use another root. `--repo OWNER/REPO` remains the single-repository pool mode.
 

package/dist/dashboard-html.js

@@ -235,7 +235,7 @@ export const dashboardHtml = `<!doctype html>
       </div>
     </div>
   </section>
-  <section id="rules-view" role="tabpanel" aria-labelledby="rules-tab" hidden><div class="panel"><div class="panel-head"><h2>Router Rules</h2><span id="rules-meta" class="subtle"></span></div><div class="panel-body"><div class="router-rules-workspace"><div class="router-rules-pane rules-editor"><h3>Rules Editor</h3><p class="rules-help">Free-text soft policy loaded by the Execution Router for every worker+model routing decision. Impossible routes remain excluded by code; Codex remains the deterministic fallback if decision fails.</p><textarea id="rules-text" class="rules-textarea" spellcheck="true" aria-label="Execution router rules" placeholder="Example: Prefer ZAI glm-5.3-flash high while quota is available. Use ChatGPT for research when appropriate. Codex is fallback only."></textarea><div class="rules-footer"><span id="rules-status" class="subtle" aria-live="polite"></span><div><button id="rules-test" class="rules-save" type="button">Test Router</button> <button id="rules-save" class="rules-save" type="button">Save rules</button></div></div></div><div class="router-rules-pane"><div class="panel-head"><h3>Audit Log</h3><button id="audit-refresh" type="button">Refresh</button></div><div id="audit-log" class="audit-log" aria-live="polite"><p class="empty">Loading latest routing decisions…</p></div></div></div><div class="router-test-panel"><h3>Test Router Result</h3><div id="router-test-results" class="router-test-results" aria-live="polite"><p class="empty">Select a Job and Task, then run Test Router.</p></div></div></div></div></section>
+  <section id="rules-view" role="tabpanel" aria-labelledby="rules-tab" hidden><div class="panel"><div class="panel-head"><h2>Router Rules</h2><span id="rules-meta" class="subtle"></span></div><div class="panel-body"><div class="router-rules-workspace"><div class="router-rules-pane rules-editor"><h3>Rules Editor</h3><p class="rules-help">Execution Router rules with an explicit <code>[choices]</code> section (provider: model [reasoning] entries, additive to profile defaults) and a <code>[routing-instruction]</code> section forwarded verbatim to Laya. Relay deduplicates, applies hard gates, and sends one merged choice list; impossible routes remain excluded by code and Codex stays the deterministic fallback.</p><textarea id="rules-text" class="rules-textarea" spellcheck="true" aria-label="Execution router rules" placeholder="[choices]\nopenai: sol medium, luna high\nzai: glm-5.3-flash high\n\n[routing-instruction]\nPrefer zai until its quota resets; otherwise use the openai default."></textarea><div class="rules-footer"><span id="rules-status" class="subtle" aria-live="polite"></span><div><button id="rules-test" class="rules-save" type="button">Test Router</button> <button id="rules-save" class="rules-save" type="button">Save rules</button></div></div></div><div class="router-rules-pane"><div class="panel-head"><h3>Audit Log</h3><button id="audit-refresh" type="button">Refresh</button></div><div id="audit-log" class="audit-log" aria-live="polite"><p class="empty">Loading latest routing decisions…</p></div></div></div><div class="router-test-panel"><h3>Test Router Result</h3><div id="router-test-results" class="router-test-results" aria-live="polite"><p class="empty">Select a Job and Task, then run Test Router.</p></div></div></div></div></section>
   <section id="shortcuts-view" role="tabpanel" aria-labelledby="shortcuts-tab" hidden>
     <div class="panel">
       <div class="panel-head"><h2>ChatGPT Shortcuts</h2><span class="subtle">One per line · %1 = current repo/pr</span></div>
@@ -453,7 +453,7 @@ function routeWorker(record){const id=record?.selected?.worker?.id||record?.work
 function renderAudit(records){auditLog.replaceChildren();if(!Array.isArray(records)||!records.length){auditLog.append(element('p','empty',text('No schema v5 routing decisions yet.')));return;}for(const record of records){const card=element('article','audit-entry');const head=element('div','audit-entry-head');head.append(element('strong','',text(routeWorker(record)+' · '+value(record?.selected?.model?.model))),element('span','subtle',text(new Date(record.timestamp).toLocaleString())));card.append(head);const correlation=record.correlation||{};card.append(element('div','subtle',text([correlation.job_id,correlation.task_id].filter(Boolean).join(' / ')||'uncorrelated')));const probabilities=record.decision_evidence?.probabilities||{};const gates=(record.gate_results||[]).filter(item=>!item.eligible).map(item=>item.candidate_id+': '+item.rejection_reasons.join(', '));const nl=String.fromCharCode(10);const details=document.createElement('pre');details.textContent='fallback: '+String(Boolean(record.decision_evidence?.fallback))+(Object.keys(probabilities).length?nl+'probabilities: '+JSON.stringify(probabilities,null,2):'')+(gates.length?nl+'rejected: '+gates.join(nl):'');card.append(details);auditLog.append(card);}}
 async function drawAudit(){auditRefresh.disabled=true;try{renderAudit(await loadJSON('/api/decision-audit'));}catch(error){auditLog.replaceChildren(element('p','error-state',text('Audit unavailable: '+error.message)));}finally{auditRefresh.disabled=false;}}
 async function drawRules(){rulesStatus.textContent='';try{const rules=await loadJSON('/api/execution-router-rules');rulesText.value=typeof rules.text==='string'?rules.text:'';rulesMeta.textContent=rules.hash&&rules.hash!=='none'?'Loaded · '+rules.hash.slice(0,12):'No custom rules saved';}catch(error){rulesMeta.textContent='Unavailable';rulesStatus.textContent='Could not load rules: '+error.message;}void drawAudit();}
-async function testRouter(){rulesTest.disabled=true;routerTestResults.replaceChildren(element('p','subtle',text('Calling router with current status…')));try{if(!selectedJob||!selectedTaskId)throw new Error('Select a Job and Task first');const response=await fetch('/api/router-test',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({jobId:selectedJob,taskId:selectedTaskId})});if(!response.ok)throw new Error(response.status+' '+await response.text());const result=await response.json();const selected=result.selected||{};const payload={selected,proposed_fields:result.proposedFields||{},probabilities:result.probabilities||{},fallback:Boolean(result.fallback),hard_gates:result.gates||[],laya_input:result.decisionInput||null};routerTestResults.replaceChildren(element('strong','',text((selected.worker||'—')+' · '+(selected.model||'—'))));routerTestResults.append(element('div','subtle',text('route: '+(selected.route||'—'))),element('pre','',text(yamlDump(payload))));}catch(error){routerTestResults.replaceChildren(element('p','error-state',text('Router test failed: '+error.message)));}finally{rulesTest.disabled=false;}}
+async function testRouter(){rulesTest.disabled=true;routerTestResults.replaceChildren(element('p','subtle',text('Calling router with current status…')));try{if(!selectedJob||!selectedTaskId)throw new Error('Select a Job and Task first');const response=await fetch('/api/router-test',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({jobId:selectedJob,taskId:selectedTaskId})});if(!response.ok)throw new Error(response.status+' '+await response.text());const result=await response.json();const selected=result.selected||{};const payload={selected,proposed_fields:result.proposedFields||{},probabilities:result.probabilities||{},fallback:Boolean(result.fallback),effective_choices:result.effectiveChoices||[],routing_instruction:result.routingInstruction||'',merged_choices:result.mergedChoices||[],hard_gates:result.gates||[],laya_input:result.decisionInput||null};routerTestResults.replaceChildren(element('strong','',text((selected.worker||'—')+' · '+(selected.model||'—'))));routerTestResults.append(element('div','subtle',text('route: '+(selected.route||'—'))),element('pre','',text(yamlDump(payload))));}catch(error){routerTestResults.replaceChildren(element('p','error-state',text('Router test failed: '+error.message)));}finally{rulesTest.disabled=false;}}
 async function saveRules(){rulesSave.disabled=true;rulesStatus.textContent='Saving…';try{const response=await fetch('/api/execution-router-rules',{method:'PUT',headers:{'content-type':'text/plain; charset=utf-8'},body:rulesText.value});if(!response.ok)throw new Error(response.status+' '+await response.text());const rules=await response.json();rulesMeta.textContent='Saved · '+rules.hash.slice(0,12);rulesStatus.textContent='Saved. New routing decisions will load these rules.';}catch(error){rulesStatus.textContent='Save failed: '+error.message;}finally{rulesSave.disabled=false;}}
 async function drawShortcuts(){shortcutsStatus.textContent='';shortcutsText.value=chatShortcutText();}
 function saveShortcuts(){const value=shortcutsText.value.trim();if(value)localStorage.setItem(CHAT_SHORTCUTS_KEY,value);else localStorage.removeItem(CHAT_SHORTCUTS_KEY);shortcutsText.value=chatShortcutText();shortcutsStatus.textContent='Saved.';}

package/dist/decision-audit.js

@@ -135,7 +135,7 @@ export function makeExecutionDecisionAudit(input) {
         fallback: { used: input.routing.decisionEvidence?.fallback ?? false, reason: input.routing.decisionEvidence?.error },
         decision_evidence: input.routing.decisionEvidence,
         decision_input: {
-            type: 'staged_route_decision',
+            type: 'merged_choice_decision',
             stages: input.decisionStages.map(stage => ({
                 name: stage.name,
                 facts: stage.facts,

package/dist/execution-routing.js

@@ -111,13 +111,6 @@ async function decideStage(engine, name, facts, question, choices) {
         throw new Error('Execution router expected a choice result for ' + name);
     return { name, facts, contract, result: { choice: decision.choice, probabilities: decision.probabilities } };
 }
-function stageFacts(baseFacts, selected, candidates) {
-    return JSON.parse(JSON.stringify({
-        ...baseFacts,
-        selected,
-        ...candidates,
-    }));
-}
 function routeId(worker, model) {
     return worker.workerId + '::' + model.id + (model.reasoning ? '@' + model.reasoning : '');
 }
@@ -143,9 +136,89 @@ function workerSelection(worker, selectedBy, evidence) {
         decisionEvidence: evidence,
     };
 }
+/**
+ * Configured profile defaults for one worker: the explicitly configured
+ * provider/model/reasoning profiles (Codex `config.toml` and `*.config.toml`),
+ * i.e. every discovered route that is not a runtime catalog expansion.
+ */
+function profileDefaults(candidates) {
+    return candidates.filter(candidate => !candidate.id.startsWith('catalog:'));
+}
+/**
+ * Resolve explicit user `[choices]` entries against discovered runtime models.
+ * A choice may reference a runtime catalog model because the user named it
+ * explicitly; Relay never expands the unreferenced catalog into choices.
+ * Unresolvable or reasoning-incompatible entries are dropped rather than
+ * fabricated into an impossible route.
+ */
+function resolveExplicitModel(choice, pool) {
+    const model = choice.model.toLowerCase();
+    const exact = pool.find(candidate => candidate.model.toLowerCase() === model);
+    if (exact)
+        return exact.model;
+    const suffixes = [...new Set(pool.filter(candidate => candidate.model.toLowerCase().endsWith('-' + model)).map(candidate => candidate.model))];
+    if (suffixes.length === 1)
+        return suffixes[0];
+    const hint = choice.model.match(/^(gpt-\d+(?:\.\d+)?)-[a-z0-9.-]+$/i)?.[1];
+    if (hint) {
+        const family = pool.find(candidate => candidate.model.toLowerCase() === (hint + '-' + model).toLowerCase());
+        if (family)
+            return family.model;
+    }
+    return null;
+}
+function resolveExplicitChoices(choices, candidates) {
+    const result = [];
+    const seen = new Set();
+    for (const choice of choices) {
+        const provider = choice.provider.toLowerCase();
+        const providerPool = candidates.filter(candidate => candidate.provider.toLowerCase() === provider);
+        const model = resolveExplicitModel(choice, providerPool);
+        if (!model)
+            continue;
+        const matches = providerPool.filter(candidate => candidate.model === model);
+        const pool = choice.reasoning
+            ? matches.filter(candidate => (candidate.reasoning ?? '').toLowerCase() === choice.reasoning)
+            : matches;
+        const candidate = pool.find(item => !item.id.startsWith('catalog:')) ?? pool[0];
+        if (!candidate)
+            continue;
+        const key = candidate.id + '@' + (candidate.reasoning ?? '');
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(candidate);
+    }
+    return result;
+}
+function mergeCandidates(...lists) {
+    const result = [];
+    const seen = new Set();
+    for (const list of lists) {
+        for (const candidate of list) {
+            const key = candidate.id + '@' + (candidate.reasoning ?? '');
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            result.push(candidate);
+        }
+    }
+    return result;
+}
+export function executionChoiceLabel(route, isDefault) {
+    return 'worker=' + route.worker.workerId
+        + ' provider=' + route.model.provider
+        + ' model=' + route.model.model
+        + ' reasoning=' + (route.model.reasoning ?? 'provider-default')
+        + ' default=' + String(isDefault);
+}
+function isDefaultCandidate(candidate, defaults) {
+    return defaults.some(item => item.id === candidate.id && item.reasoning === candidate.reasoning);
+}
 export async function discoverExecutionRoutes(workers, requirements, options = {}) {
     const registered = options.registered ?? [];
     const policy = await loadRoutingPolicy(options.policyPath, options.rulesPath);
+    const rules = await loadExecutionRouterRules(options.rulesPath);
     const workerGateEvaluations = workers.map(worker => {
         const rejectionReasons = workerGateReasons(worker, requirements);
         return { workerId: worker.workerId, eligible: rejectionReasons.length === 0, rejectionReasons };
@@ -153,28 +226,45 @@ export async function discoverExecutionRoutes(workers, requirements, options = {
     const evaluations = [];
     for (const worker of workers) {
         const workerReasons = workerGateEvaluations.find(item => item.workerId === worker.workerId)?.rejectionReasons ?? [];
-        const models = await discoverModelCandidates(worker, registered, options.usage, undefined, options.rulesPath);
-        for (const model of models) {
+        const discovered = await discoverModelCandidates(worker, registered, options.usage, undefined, options.rulesPath);
+        const defaults = profileDefaults(discovered);
+        const explicit = resolveExplicitChoices(rules.parsed.choices, discovered);
+        const merged = mergeCandidates(defaults, explicit);
+        for (const model of merged) {
             const rejectionReasons = [...workerReasons, ...modelGateReasons(model, options.routingConstraints, options.excludedRoutes, policy)];
             const route = { id: routeId(worker, model), worker, model };
             evaluations.push({ route, eligible: rejectionReasons.length === 0, rejectionReasons });
         }
     }
     const routes = evaluations.filter(item => item.eligible).map(item => item.route);
-    return { routes, evaluations, workerGateEvaluations, policy };
+    return { routes, evaluations, workerGateEvaluations, policy, choices: rules.parsed.choices, routingInstruction: rules.parsed.routingInstruction };
 }
 export async function routeExecution(workers, requirements, options = {}) {
-    const { routes, evaluations, workerGateEvaluations, policy } = await discoverExecutionRoutes(workers, requirements, options);
+    const { routes, evaluations, workerGateEvaluations, policy, routingInstruction } = await discoverExecutionRoutes(workers, requirements, options);
     if (routes.length === 0)
         throw new Error('No executable worker+model route satisfies authoritative constraints');
     const fallback = fallbackRoute(routes);
     const rules = await loadExecutionRouterRules(options.rulesPath);
-    const userInputRules = rules.text;
     const preferredChatgptConcurrency = options.preferredChatgptConcurrency ?? DEFAULT_CHATGPT_PREFERRED_CONCURRENCY;
     const chatgptRunning = options.chatgptRunning ?? 0;
     const taskFacts = options.taskFacts ?? {};
     const taskShape = executionTaskShape(taskFacts);
-    const baseFacts = JSON.parse(JSON.stringify({
+    const discoveredDefaults = new Map();
+    for (const worker of workers) {
+        const discovered = await discoverModelCandidates(worker, options.registered ?? [], options.usage, undefined, options.rulesPath);
+        discoveredDefaults.set(worker.workerId, profileDefaults(discovered));
+    }
+    const effectiveChoices = routes.map(route => ({
+        worker: route.worker.workerId,
+        provider: route.model.provider,
+        model: route.model.model,
+        profile: route.model.profile ?? null,
+        reasoning: route.model.reasoning ?? null,
+        default: isDefaultCandidate(route.model, discoveredDefaults.get(route.worker.workerId) ?? []),
+        source: isDefaultCandidate(route.model, discoveredDefaults.get(route.worker.workerId) ?? []) ? 'profile-default' : 'explicit-choice',
+    }));
+    const choiceLabels = routes.map((route, index) => executionChoiceLabel(route, effectiveChoices[index].default));
+    const facts = JSON.parse(JSON.stringify({
         context: {
             job: taskFacts.job ?? null,
             task: taskFacts.task ?? taskFacts,
@@ -189,95 +279,32 @@ export async function routeExecution(workers, requirements, options = {}) {
                 reviewer_diversity: taskFacts.reviewer_diversity,
             } : null,
         },
-        user_input_rules: userInputRules,
+        user_input_rules: rules.text,
+        routing_instruction: routingInstruction,
         runtime: {
             chatgpt_running: chatgptRunning,
             preferred_chatgpt_concurrency: preferredChatgptConcurrency,
         },
         worker_candidates: workerProviderFacts(routes),
-        routing_instruction: 'Interpret user_input_rules directly. Choose among the runtime-provided legal candidates at each stage. Relay does not parse user_input_rules into model or reasoning choices.',
+        effective_choices: effectiveChoices,
     }));
+    const question = 'Choose one complete route from the merged choice list. Relay has already merged profile defaults with the user\'s explicit [choices] and applied every authoritative hard gate, so only these routes are legal. Follow [routing_instruction] verbatim; do not invent, add, or substitute routes that are not listed.';
     let selected = fallback;
     let evidence = { mode: options.decisionMode ?? 'off', fallback: true };
     const decisionStages = [];
     if ((options.decisionMode ?? 'off') !== 'off' && options.decisionEngine) {
         try {
-            const providerKeys = [...new Set(routes.map(route => route.worker.workerId + '::' + route.model.provider))];
-            const providerOptions = providerKeys.map(key => {
-                const splitAt = key.lastIndexOf('::');
-                const worker = key.slice(0, splitAt);
-                const provider = key.slice(splitAt + 2);
-                const providerRoutes = routes.filter(route => route.worker.workerId === worker && route.model.provider === provider);
-                const configured = providerRoutes.find(route => !route.model.id.startsWith('catalog:')) ?? providerRoutes[0];
-                return {
-                    key,
-                    worker,
-                    provider,
-                    default_model: configured.model.model,
-                    label: 'worker=' + worker + ' provider=' + provider + ' default_model=' + configured.model.model,
-                };
-            });
-            const providerFacts = stageFacts(baseFacts, {}, {
-                provider_candidates: providerOptions.map(({ label: _label, key: _key, ...option }) => option),
-            });
-            const providerStage = await decideStage(options.decisionEngine, 'provider', providerFacts, 'Choose the best worker/provider pair. Interpret user_input_rules directly together with task context, runtime load, provider defaults, and code-plan quota. When user_input_rules explicitly names providers as routing options, prefer those named providers when applicable; treat unmentioned providers as fallbacks unless other facts clearly require them.', providerOptions.map(option => option.label));
-            decisionStages.push(providerStage);
-            const selectedProvider = providerOptions.find(option => option.label === providerStage.result.choice);
-            if (!selectedProvider)
-                throw new Error('Laya selected an unknown worker/provider option');
-            const workerId = selectedProvider.worker;
-            const provider = selectedProvider.provider;
-            const providerRoutes = routes.filter(route => route.worker.workerId === workerId && route.model.provider === provider);
-            if (providerRoutes.length === 0)
-                throw new Error('Laya selected a worker/provider pair with no eligible routes');
-            const modelGroups = new Map();
-            for (const route of providerRoutes) {
-                const group = modelGroups.get(route.model.model) ?? [];
-                group.push(route);
-                modelGroups.set(route.model.model, group);
-            }
-            const modelChoices = [...modelGroups.keys()];
-            const modelOptions = modelChoices.map(model => {
-                const group = modelGroups.get(model) ?? [];
-                const configured = group.some(route => !route.model.id.startsWith('catalog:'));
-                return {
-                    model,
-                    configured_default: configured,
-                    supported_reasoning: [...new Set(group.map(route => route.model.reasoning).filter((value) => Boolean(value)))],
-                    label: 'model=' + model + ' configured_default=' + String(configured),
-                };
-            });
-            const modelFacts = stageFacts(baseFacts, { worker: workerId, provider }, {
-                model_candidates: modelOptions.map(({ label: _label, ...option }) => option),
-            });
-            const modelStage = await decideStage(options.decisionEngine, 'model', modelFacts, 'Choose the best model for the selected worker/provider. Interpret user_input_rules directly. Candidate model names come from current runtime/configuration and are not derived from the free-text rules. If user_input_rules explicitly maps a model to the current task type, size, complexity, or other current condition, follow that mapping instead of the provider default.', modelOptions.map(option => option.label));
-            decisionStages.push(modelStage);
-            const selectedModel = modelOptions.find(option => option.label === modelStage.result.choice);
-            if (!selectedModel)
-                throw new Error('Laya selected an unknown model option');
-            const modelRoutes = modelGroups.get(selectedModel.model) ?? [];
-            const reasoningChoices = [...new Set(modelRoutes.map(route => route.model.reasoning ?? 'provider-default'))];
-            const reasoningOptions = reasoningChoices.map(reasoning => ({
-                reasoning,
-                label: 'reasoning=' + reasoning,
-            }));
-            const reasoningFacts = stageFacts(baseFacts, { worker: workerId, provider, model: selectedModel.model }, {
-                reasoning_candidates: reasoningChoices,
-            });
-            const reasoningStage = await decideStage(options.decisionEngine, 'reasoning', reasoningFacts, 'Choose the reasoning level for the selected model. Interpret user_input_rules directly. If user_input_rules explicitly assigns a reasoning level to the selected model for the current conditions, follow that assignment. Use provider-default only when the model does not expose a specific reasoning level.', reasoningOptions.map(option => option.label));
-            decisionStages.push(reasoningStage);
-            const selectedReasoning = reasoningOptions.find(option => option.label === reasoningStage.result.choice);
-            if (!selectedReasoning)
-                throw new Error('Laya selected an unknown reasoning option');
-            const reasoning = selectedReasoning.reasoning === 'provider-default' ? null : selectedReasoning.reasoning;
-            const proposed = modelRoutes.find(route => (route.model.reasoning ?? null) === reasoning);
-            if (!proposed)
-                throw new Error('Laya selected a model/reasoning combination with no eligible route');
-            selected = proposed;
+            const stage = await decideStage(options.decisionEngine, 'route', facts, question, choiceLabels);
+            decisionStages.push(stage);
+            const index = stage.result.choice ? choiceLabels.indexOf(stage.result.choice) : -1;
+            if (index < 0)
+                throw new Error('Laya selected a route outside the merged choice list');
+            selected = routes[index];
             evidence = {
                 mode: options.decisionMode ?? 'active',
                 engine: options.decisionEngine.name,
-                proposed: providerStage.result.choice + '/' + selectedModel.model + '@' + selectedReasoning.reasoning,
+                proposed: stage.result.choice,
+                probabilities: stage.result.probabilities,
                 proposedFields: {
                     worker: selected.worker.workerId,
                     provider: selected.model.provider,
@@ -320,6 +347,8 @@ export async function routeExecution(workers, requirements, options = {}) {
             constraints: options.routingConstraints ?? {},
             excludedRoutes: options.excludedRoutes ?? [],
             candidateRoutes: routes.map(route => ({ id: route.id, workerId: route.worker.workerId, adapter: route.worker.adapter })),
+            effectiveChoices,
+            routingInstruction,
         },
         policy,
         routing,

package/dist/relayd.js

@@ -63,6 +63,13 @@ Legacy single-job mode also accepts --repo OWNER/REPO --pr NUMBER --id JOB_ID.
 Examples:
   npx agents-relayd --repo OWNER/REPO
   npx agents-relayd --workspace ~/Workspace`;
+function firstStageChoices(decisionInput) {
+    const stages = decisionInput?.stages;
+    if (!Array.isArray(stages) || stages.length === 0)
+        return [];
+    const contract = stages[0].contract;
+    return Array.isArray(contract?.choices) ? contract.choices.filter((item) => typeof item === 'string') : [];
+}
 function value(args, name, fallback = '') { const index = args.indexOf(name); return index >= 0 ? args[index + 1] ?? fallback : fallback; }
 export function normalizeDaemonArguments(argv) {
     const repository = value(argv, '--repo') || null;
@@ -412,6 +419,9 @@ export async function runDaemon(argv) {
                 providers: usage.providers,
                 credits: usage.credits,
             },
+            effectiveChoices: result.audit?.contract?.effectiveChoices ?? [],
+            routingInstruction: result.audit?.contract?.routingInstruction ?? '',
+            mergedChoices: firstStageChoices(result.audit?.decision_input),
             decisionInput: result.audit?.decision_input ?? null,
             gates: result.audit?.gate_results ?? [],
         };

package/dist/router-evals.js

@@ -65,11 +65,11 @@ export async function runRouterEvals(engine, rulesPath) {
             user_input_rules: rules.text,
             runtime: { chatgpt_running: testCase.chatgptRunning ?? 0, preferred_chatgpt_concurrency: 10 },
             worker_candidates: workerCandidates,
-            routing_instruction: 'For each selected provider, use its default model and reasoning unless user_input_rules explicitly provides another model/reasoning option.',
+            routing_instruction: 'Choose one route from the merged choice list. Profile defaults and explicit [choices] have already been merged and hard-gated; do not invent additional routes.',
         }));
         const decision = await engine.decide({ facts }, {
             type: 'choice',
-            question: 'Choose one legal route. Each provider default is available. Additional model/reasoning routes exist only when explicitly provided by user_input_rules. Use context, code-plan quota, runtime load, and user_input_rules.',
+            question: 'Choose one legal route from the merged choice list. Each provider default is available; extra model/reasoning routes appear only when explicitly listed in [choices]. Use context, code-plan quota, runtime load, and routing_instruction.',
             choices,
         });
         if (decision.type !== 'choice')

package/dist/router-rules.js

@@ -0,0 +1,101 @@
+/**
+ * Router Rules free-text parsing.
+ *
+ * The Execution Router rules file carries two explicit, user-authored sections:
+ *
+ * ```text
+ * [choices]
+ * openai: gpt-5.6-luna high, sol medium
+ * zai: glm-5.3-flash high
+ *
+ * [routing-instruction]
+ * Prefer zai until its quota resets; otherwise use the openai default.
+ * ```
+ *
+ * `[choices]` is an explicit, additive list of provider/model/reasoning routes.
+ * `[routing-instruction]` is opaque guidance forwarded to Laya verbatim: the
+ * exact section body is preserved byte-for-byte (leading and trailing
+ * whitespace, blank lines, and line endings included) so Relay never rewrites or
+ * normalizes user intent. Everything outside these sections is ignored so legacy
+ * free-text files remain valid and Relay never has to guess at intent.
+ */
+const SECTION_CHOICES = 'choices';
+const SECTION_INSTRUCTION = 'routing-instruction';
+const SECTION_HEADER = /^[ \t]*\[([a-z][a-z0-9-]*)\][ \t]*\r?$/gim;
+function sectionOf(line) {
+    const match = line.match(/^\s*\[([a-z][a-z0-9-]*)\]\s*$/i);
+    return match ? match[1].toLowerCase() : null;
+}
+function choiceKey(choice) {
+    return [choice.provider, choice.model, choice.reasoning ?? ''].join('\u0000');
+}
+/**
+ * Return the raw body of the first section named `name`, exactly as authored.
+ *
+ * The body begins after the line terminator that ends the section header line
+ * (the terminator belongs to the header) and ends at the start of the next
+ * section header line, or at end of input. Nothing inside the body is trimmed or
+ * normalized: whitespace, blank lines, and line endings are part of the
+ * forwarded instruction.
+ */
+function rawSectionBody(text, name) {
+    const headers = [];
+    for (const match of text.matchAll(SECTION_HEADER)) {
+        const lineStart = match.index ?? 0;
+        headers.push({ name: match[1].toLowerCase(), lineStart, lineEnd: lineStart + match[0].length });
+    }
+    const index = headers.findIndex(header => header.name === name);
+    if (index < 0)
+        return null;
+    let bodyStart = headers[index].lineEnd;
+    if (text[bodyStart] === '\r')
+        bodyStart += 1;
+    if (text[bodyStart] === '\n')
+        bodyStart += 1;
+    const bodyEnd = index + 1 < headers.length ? headers[index + 1].lineStart : text.length;
+    return text.slice(bodyStart, bodyEnd);
+}
+/**
+ * Parse explicit router choices and the routing instruction from Router Rules.
+ *
+ * `[choices]` entries are deduplicated deterministically (first occurrence
+ * wins). The `[routing-instruction]` body is captured verbatim.
+ */
+export function parseRouterRules(text) {
+    const choices = [];
+    const seen = new Set();
+    let section = null;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const header = sectionOf(rawLine);
+        if (header !== null) {
+            section = header;
+            continue;
+        }
+        if (section === SECTION_INSTRUCTION)
+            continue;
+        if (section !== SECTION_CHOICES)
+            continue;
+        if (!rawLine.trim() || rawLine.trim().startsWith('#'))
+            continue;
+        const match = rawLine.match(/^\s*([A-Za-z0-9._-]+)\s*:\s*(.+)$/);
+        if (!match)
+            continue;
+        const provider = match[1].trim();
+        for (const segment of match[2].split(',')) {
+            const tokens = segment.trim().split(/\s+/).filter(Boolean);
+            if (tokens.length === 0)
+                continue;
+            const choice = {
+                provider,
+                model: tokens[0],
+                ...(tokens[1] ? { reasoning: tokens[1].toLowerCase() } : {}),
+            };
+            const key = choiceKey(choice);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            choices.push(choice);
+        }
+    }
+    return { choices, routingInstruction: rawSectionBody(text, SECTION_INSTRUCTION) ?? '' };
+}

package/dist/routing-policy.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { parseRouterRules } from './router-rules.js';
 const EMPTY_POLICY = {};
 function safePolicy(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -34,16 +35,16 @@ export function policyPath(explicit) {
 async function loadRouterRules(path) {
     try {
         const text = await readFile(path, 'utf8');
-        return { path, hash: createHash('sha256').update(text).digest('hex'), text };
+        return { path, hash: createHash('sha256').update(text).digest('hex'), text, parsed: parseRouterRules(text) };
     }
     catch {
-        return { path, hash: 'none', text: '' };
+        return { path, hash: 'none', text: '', parsed: parseRouterRules('') };
     }
 }
 async function saveRouterRules(path, text) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, text, 'utf8');
-    return { path, hash: createHash('sha256').update(text).digest('hex'), text };
+    return { path, hash: createHash('sha256').update(text).digest('hex'), text, parsed: parseRouterRules(text) };
 }
 export function executionRouterRulesPath(explicit) {
     return explicit ?? process.env.AGENTS_RELAY_EXECUTION_ROUTER_RULES ?? join(homedir(), '.agents-relay', 'execution-router-rules.md');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.30",
+  "version": "2.0.32",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/skills/agents-relay/contracts/orchestrator-workflows.md

@@ -6,6 +6,25 @@ Before `job create`, the orchestrator converts the relevant discussion into a st
 
 This contract defines orchestrator-owned exception workflows that sit above normal Agents Relay task/job execution.
 
+## Normal managed Job start workflow
+
+For a normal managed Job, `job create` or `job adopt` establishes durable Job/PR state only. Unless the user explicitly requested **create-only / no execution**, the orchestrator must immediately start the Job by invoking the first-class Planner command for that exact Job:
+
+```text
+job create|adopt
+  -> agents-relay plan --repo <owner/repo> --pr <number> --id <job_id>
+  -> durable plan-N
+  -> Planner next_tasks
+  -> Relay materializes Tasks
+  -> normal routing, execution, and reconciliation
+```
+
+The initial decomposition for a normal managed Job belongs to that durable Planner round. The orchestrator must not hand-author the initial child Task batch as a substitute for `agents-relay plan`, and it must not leave a newly created executable Job with zero Plans and zero Tasks. If the Planner command fails, the Job is blocked at startup and the orchestrator must report the failure rather than silently inventing Tasks.
+
+This rule applies regardless of whether the Job uses `fixed` or `autonomous` execution mode; execution mode does not replace the required initial Planner invocation. Later replanning continues to follow Relay's normal Planner/reconciliation rules.
+
+The explicit exception is the P0/self-job workflow below: a self job is synchronous orchestrator-owned execution, so it creates orchestrator-owned Tasks directly and terminalizes them in the same turn instead of invoking the normal initial Planner round.
+
 ## P0 / self job workflow
 
 A **P0 job** (alias: **self job**) is executed directly by the current active orchestrator thread: