agents-relay 2.0.31 → 2.0.33

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
@@ -189,11 +189,13 @@ events, durable-thread reuse, resume, or retry behavior.
 
 Open the dashboard on localhost port 8787. The marker format is intentionally public and append-friendly. Daemon/workspace operation uses `ProjectedDurableStore` over SQLite RelayStore plus the authenticated GitHub projection adapter; GitHubStore is not the daemon operational state database.
 
+Deterministic projection conflicts are safe and observable. A same-id/different-definition `append_task`/`append_plan` is classified once into a durable `conflict` state, stops consuming retry budget, keeps structured divergence evidence, and is never auto-overwritten. Inspect with `agents-relay projection conflicts --repo OWNER/REPO --pr NUMBER` and repair explicitly with `agents-relay projection resolve --repo OWNER/REPO --pr NUMBER --projection-id ID --action requeue|discard-local`. See [docs/architecture-v2.md](docs/architecture-v2.md).
+
 External product feedback uses the reusable `src/feedback.ts` contract. See [docs/feedback-intake.md](docs/feedback-intake.md) for the schema, attachment limits, privacy rules, materialization path, and provenance envelope for later Jobs/Tasks/PRs.
 
 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/cli-help.js

@@ -1,4 +1,4 @@
-export const usage = 'agents-relay <job|task|plan|blocker|context|init|record|agent-register|agent-discover|status|reconcile|serve> [options]';
+export const usage = 'agents-relay <job|task|plan|blocker|projection|context|init|record|agent-register|agent-discover|status|reconcile|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -10,6 +10,7 @@ Commands:
   task create|update|show|list|complete|retry|unblock|cancel  Manage durable tasks
   plan                     Invoke the Planner for an existing managed Job
   blocker add|resolve|show  Manage cross-Job blocker dependencies
+  projection conflicts|resolve  Inspect and repair deterministic GitHub projection conflicts
   context resolve          Resolve shared project instructions, skills, agents, and runtimes
   init                     Create a local demo job or initialize a GitHub job
   record                   Backfill a completed task into durable history
@@ -203,6 +204,17 @@ Common: --capabilities a,b, --runtime shell|codex|chatgpt, --provider NAME, --mo
 
 Example:
   npx agents-relay agent-register --file .agents-relay.json --name builder --responsibility "Build code" --role engineer --endpoint shell`,
+    projection: `Inspect and explicitly repair deterministic V2 GitHub projection conflicts.
+
+Usage:
+  npx agents-relay projection conflicts --repo OWNER/REPO --pr NUMBER [--store PATH]
+  npx agents-relay projection resolve --repo OWNER/REPO --pr NUMBER --projection-id ID --action requeue|discard-local
+
+A deterministic same-id/different-definition append conflict is classified once, stops
+consuming retry budget, and retains structured diagnostic evidence. It is never
+auto-overwritten: an operator resolves it after reconciling the divergent definition.
+  requeue        Re-arm the recorded projection after the divergent side is reconciled
+  discard-local  Drop the blocked local mutation so a fresh one can be enqueued`,
     'agent-discover': `Find registered agents using hard filters.
 
 Required: --file PATH or managed GitHub options.
@@ -220,5 +232,7 @@ export function helpText(command, action) {
         return action ? help[`context ${action}`] ?? help.context : help.context;
     if (command === 'blocker')
         return action ? help[`blocker ${action}`] ?? help.blocker : help.blocker;
+    if (command === 'projection')
+        return help.projection;
     return command ? help[command] ?? help.root : help.root;
 }

package/dist/cli-projection.js

@@ -0,0 +1,61 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { SQLiteRelayStore, relayStorePath } from './relay-store.js';
+import { arg, integerArg, pullRequest, repository } from './cli-support.js';
+const DEFAULT_STORE_DIR = join(homedir(), '.agents-relay', 'stores');
+function storePath(args) {
+    const explicit = arg(args, '--store');
+    if (explicit)
+        return explicit;
+    return relayStorePath(arg(args, '--store-dir', DEFAULT_STORE_DIR), repository(args), pullRequest(args));
+}
+export async function runProjectionCommand(action, args) {
+    const store = new SQLiteRelayStore(storePath(args));
+    try {
+        if (action === 'conflicts' || action === 'list') {
+            const conflicts = await store.listProjectionConflicts();
+            console.log(JSON.stringify(conflicts, null, 2));
+            return;
+        }
+        if (action === 'resolve') {
+            const id = integerArg(args, '--projection-id', 0);
+            if (id <= 0)
+                throw new Error('projection resolve requires --projection-id ID');
+            const raw = arg(args, '--action', 'requeue');
+            if (raw !== 'requeue' && raw !== 'discard-local' && raw !== 'discard_local')
+                throw new Error('--action must be requeue or discard-local');
+            const resolution = raw === 'requeue' ? 'requeue' : 'discard_local';
+            const note = arg(args, '--note') || undefined;
+            const resolved = await store.resolveProjectionConflict(id, { action: resolution, ...(note ? { note } : {}) });
+            if (!resolved)
+                throw new Error(`Projection ${id} is not in a resolvable conflict state`);
+            console.log(`Resolved projection ${id} with ${resolution}`);
+            return;
+        }
+        throw new Error(`projection ${action || '<action>'} is not supported; use conflicts or resolve`);
+    }
+    finally {
+        store.close();
+    }
+}
+export function projectionHelp(action) {
+    if (action === 'resolve') {
+        return `Explicitly repair one classified projection conflict.
+
+Required: --projection-id ID --action requeue|discard-local, plus --store PATH or --repo OWNER/REPO --pr NUMBER.
+Actions:
+  requeue        Re-arm the recorded projection after the divergent side is reconciled
+  discard-local  Drop the blocked local mutation so a fresh one can be enqueued
+
+Never silently overwrites either side. The recorded diagnostic remains until resolution.`;
+    }
+    return `Inspect and explicitly repair deterministic V2 GitHub projection conflicts.
+
+Usage:
+  npx agents-relay projection conflicts --repo OWNER/REPO --pr NUMBER [--store PATH]
+  npx agents-relay projection resolve --repo OWNER/REPO --pr NUMBER --projection-id ID --action requeue|discard-local
+
+A deterministic same-id/different-definition append conflict is classified once, stops
+consuming retry budget, and retains structured diagnostic evidence. It is never
+auto-overwritten: an operator resolves it after reconciling the divergent definition.`;
+}

package/dist/cli.js

@@ -23,6 +23,7 @@ import { applyJobActivateAction, applyJobCancelAction } from './job-actions.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
 import { runBlockerCommand } from './cli-blocker.js';
+import { runProjectionCommand } from './cli-projection.js';
 import { helpText, usage } from './cli-help.js';
 import { parseAgentGraph } from './agent-graph.js';
 import { runJobUnblockCommand, runTaskUnblockCommand } from './cli-unblock.js';
@@ -571,6 +572,11 @@ async function main() {
         await runBlockerCommand(action ?? '', blockerArgs);
         return;
     }
+    if (command === 'projection') {
+        const [action, ...projectionArgs] = args;
+        await runProjectionCommand(action ?? '', projectionArgs);
+        return;
+    }
     if (command === 'init') {
         const now = new Date().toISOString();
         const initialSchedule = scheduleFromArgs(args);

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/projected-store.js

@@ -1,5 +1,6 @@
 import { registerBlockerDependency, resolveBlockerDependencies } from './blockers.js';
-import { sameTaskDefinition } from './store-task-definition.js';
+import { DurableDefinitionConflictError, isDurableDefinitionConflict, sameTaskDefinition } from './store-task-definition.js';
+import { decideProjectionFailure } from './workflow/projection-conflict-v2.js';
 function taskKey(task) { return `task:${task.jobId ?? ''}:${task.id}`; }
 function planKey(plan) { return `plan:${plan.jobId}:${plan.id}`; }
 function retryHeader(error, name) {
@@ -27,17 +28,60 @@ export function githubProjectionRetryAt(error, attempt, now = new Date()) {
     const backoffMs = Math.min(300_000, 1_000 * (2 ** Math.min(8, Math.max(0, attempt))));
     return new Date(now.getTime() + backoffMs);
 }
+const DEFINITION_CONFLICT_MESSAGE = /already exists with a different definition$/;
+/**
+ * Core deterministic-conflict classifier.
+ *
+ * A structured {@link DurableDefinitionConflictError} is authoritative; a plain error
+ * whose message matches the canonical GitHub marker conflict text is classified the
+ * same way so remote stores and legacy callers converge on one behavior.
+ */
 export function isTerminalProjectionFailure(item, error) {
+    if (item.operation !== 'append_task' && item.operation !== 'append_plan')
+        return false;
     const message = error instanceof Error ? error.message : String(error);
-    return (item.operation === 'append_task' || item.operation === 'append_plan')
-        && /already exists with a different definition$/.test(message);
+    return isDurableDefinitionConflict(error) || DEFINITION_CONFLICT_MESSAGE.test(message);
+}
+/** Builds durable diagnostic evidence even when a plain error carries no structured fields. */
+function conflictDiagnostic(item, error, detectedAt) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof DurableDefinitionConflictError) {
+        return {
+            kind: error.kind,
+            jobId: error.jobId,
+            subjectId: error.subjectId,
+            operation: item.operation,
+            operationKey: item.operationKey,
+            localDefinition: error.local,
+            remoteDefinition: error.remote,
+            divergingFields: [...error.divergingFields],
+            detectedAt,
+            message,
+        };
+    }
+    const payload = item.payload;
+    const kind = item.operation === 'append_plan' ? 'plan' : 'task';
+    return {
+        kind,
+        jobId: typeof payload?.value?.jobId === 'string' ? payload.value.jobId : '',
+        subjectId: typeof payload?.value?.id === 'string' ? payload.value.id : '',
+        operation: item.operation,
+        operationKey: item.operationKey,
+        localDefinition: payload?.value ?? item.payload ?? null,
+        remoteDefinition: null,
+        divergingFields: [],
+        detectedAt,
+        message,
+    };
 }
 export class GitHubProjectionWriter {
     relay;
     github;
-    constructor(relay, github) {
+    onConflict;
+    constructor(relay, github, onConflict) {
         this.relay = relay;
         this.github = github;
+        this.onConflict = onConflict;
     }
     async flushOnce(limit = 50, now = new Date()) {
         const items = await this.relay.claimDueProjections(limit, now);
@@ -51,8 +95,13 @@ export class GitHubProjectionWriter {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                if (isTerminalProjectionFailure(item, error))
-                    await this.relay.deadLetterProjection(item.id, message);
+                const deterministic = isTerminalProjectionFailure(item, error);
+                const decision = decideProjectionFailure({ deterministicDefinitionConflict: deterministic });
+                if (decision.accepted && decision.target === 'conflict') {
+                    const diagnostic = conflictDiagnostic(item, error, now.toISOString());
+                    await this.relay.recordProjectionConflict(item.id, diagnostic);
+                    await this.notifyConflict(diagnostic, message);
+                }
                 else {
                     await this.relay.retryProjection(item.id, message, githubProjectionRetryAt(error, item.attempts, now));
                     deferred += 1;
@@ -61,6 +110,16 @@ export class GitHubProjectionWriter {
         }
         return { projected, deferred };
     }
+    async notifyConflict(diagnostic, message) {
+        if (!this.onConflict)
+            return;
+        try {
+            await this.onConflict({ type: 'projection.conflict', status: 'conflict', visibility: 'orchestrator', message, data: diagnostic });
+        }
+        catch (error) {
+            process.stderr.write(`warning: projection conflict event unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
     async apply(item) {
         const payload = item.payload;
         switch (payload.operation) {
@@ -106,11 +165,11 @@ export class ProjectedDurableStore {
     relatedStore;
     projection;
     seededFacts;
-    constructor(relay, github, seed = null, relatedStore) {
+    constructor(relay, github, seed = null, relatedStore, onConflict) {
         this.relay = relay;
         this.github = github;
         this.relatedStore = relatedStore;
-        this.projection = new GitHubProjectionWriter(relay, github);
+        this.projection = new GitHubProjectionWriter(relay, github, onConflict);
         this.seededFacts = pullRequestFactsFromSeed(seed);
         if (this.seededFacts)
             void this.relay.savePullRequestFacts(this.seededFacts).catch(() => { });