@adhdev/daemon-core 0.9.82-rc.310 → 0.9.82-rc.311

package/src/providers/spec/cli-adapter.ts

@@ -21,7 +21,7 @@
 import { FsmDriver, type DashboardEvent, type ISpecDriver } from './fsm-driver.js';
 import { executeNativeHistory } from './native-history-executor.js';
 import * as fs from 'node:fs';
-import type { NativeHistoryConfig, Control } from './types.js';
+import type { NativeHistoryConfig, Control, ControlAction } from './types.js';
 import type { CliAdapter, CliAdapterStatus } from '../../cli-adapter-types.js';
 import type { ChatMessage } from '../../types.js';
 import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
@@ -47,6 +47,10 @@ function stripAnsi(text: string): string {
         .replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
 }
 
+function delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
 export class SpecCliAdapter implements CliAdapter {
     readonly cliType: string;
     readonly cliName: string;
@@ -311,9 +315,15 @@ export class SpecCliAdapter implements CliAdapter {
      * drives the dispatch:
      *
      *   send_keys     → click_control                   (e.g. stop)
-     *   open_picker   → click_control then resolve when extract_choices
-     *                   surface; choice index comes from args.choiceIndex
-     *                   or args.choice (string label match), defaulting to 0
+     *   open_picker   → two roles, driven by the screen, not a hardcoded list:
+     *                   - LIST  (no choice arg): open the picker, wait for it
+     *                     to render, parse the on-screen options via
+     *                     `extract_choices`, and return them as
+     *                     `controlResult.options` (+ `currentValue`). This is
+     *                     how the dashboard's Model/Mode controls learn what is
+     *                     actually selectable in this CLI right now.
+     *                   - SELECT (args.choiceIndex / args.choiceLabel): drive
+     *                     the picker to that option using `submit_key`.
      *   attach_image  → attach_image dispatch; expects args.blob (data url
      *                   or base64) and args.mime
      *
@@ -341,16 +351,148 @@ export class SpecCliAdapter implements CliAdapter {
             this.driver.dispatch({ kind: 'attach_image', blob, mime });
             return Promise.resolve({ ok: true, effects: [{ type: 'attached_image', controlId: ctl.id }] });
         }
-        // send_keys + open_picker both route through click_control. For
-        // open_picker the dashboard sees the picker modal arrive via a
-        // state_changed event, then submits the choice using
-        // resolveModal/click_modal_button. invokeScript's synchronous
-        // return is just an acknowledgement that the trigger fired.
+        if (action.type === 'open_picker') {
+            const choiceIndex = typeof flat.choiceIndex === 'number' ? flat.choiceIndex
+                : typeof flat.choiceIndex === 'string' && flat.choiceIndex.trim() ? Number(flat.choiceIndex)
+                : undefined;
+            const choiceLabel = typeof flat.choiceLabel === 'string' ? flat.choiceLabel
+                : typeof flat.choice === 'string' ? flat.choice
+                : undefined;
+            if ((typeof choiceIndex === 'number' && Number.isFinite(choiceIndex)) || (choiceLabel && choiceLabel.trim())) {
+                return this.selectPickerChoice(ctl, action, choiceIndex, choiceLabel);
+            }
+            return this.openPickerAndListChoices(ctl, action);
+        }
+        // send_keys routes through click_control.
         this.driver.dispatch({ kind: 'click_control', control_id: ctl.id, payload: flat });
-        const effects: { type: string; controlId: string }[] = [];
-        if (action.type === 'open_picker') effects.push({ type: 'opened_picker', controlId: ctl.id });
-        else if (action.type === 'send_keys') effects.push({ type: 'sent_keys', controlId: ctl.id });
-        return Promise.resolve({ ok: true, effects });
+        return Promise.resolve({ ok: true, effects: [{ type: 'sent_keys', controlId: ctl.id }] });
+    }
+
+    /**
+     * Open an `open_picker` control and return the options the CLI is showing,
+     * parsed live from the screen via `extract_choices`. Nothing is selected —
+     * the picker is left open so a follow-up SELECT invoke can commit a choice.
+     */
+    private async openPickerAndListChoices(
+        ctl: Control,
+        action: Extract<ControlAction, { type: 'open_picker' }>,
+    ): Promise<unknown> {
+        this.driver.dispatch({ kind: 'click_control', control_id: ctl.id });
+        const ready = await this.waitForPickerRendered(action);
+        const options = this.extractPickerChoices(action);
+        const currentValue = options.find(o => o.current)?.label;
+        return {
+            ok: true,
+            effects: [{ type: 'opened_picker', controlId: ctl.id }],
+            controlResult: {
+                options: options.map(o => ({ value: o.label, label: o.label, current: o.current })),
+                ...(currentValue ? { currentValue } : {}),
+                source: 'screen-parse',
+                ...(ready ? {} : { warning: 'picker_render_timeout' }),
+            },
+        };
+    }
+
+    /**
+     * Drive an already-listable picker to a specific option. The option can be
+     * named (choiceLabel — matched against the parsed on-screen labels) or
+     * positional (choiceIndex — the on-screen number). The actual keystrokes
+     * come from the spec's `submit_key` with `{index}` substituted, so the spec
+     * — not this code — decides how a selection is keyed for each CLI.
+     */
+    private async selectPickerChoice(
+        ctl: Control,
+        action: Extract<ControlAction, { type: 'open_picker' }>,
+        choiceIndex: number | undefined,
+        choiceLabel: string | undefined,
+    ): Promise<unknown> {
+        // Open + wait so the choice list is on screen before we resolve the
+        // label → index mapping (a fresh invoke may arrive with the picker
+        // closed; re-opening an open picker is a no-op on these CLIs).
+        this.driver.dispatch({ kind: 'click_control', control_id: ctl.id });
+        await this.waitForPickerRendered(action);
+        const options = this.extractPickerChoices(action);
+
+        let index = choiceIndex;
+        if ((index == null || !Number.isFinite(index)) && choiceLabel) {
+            const needle = choiceLabel.trim().toLowerCase();
+            const match = options.find(o => o.label.toLowerCase().includes(needle));
+            if (!match) {
+                return { ok: false, error: `choice not found on screen: ${choiceLabel}`, controlResult: { options: options.map(o => ({ value: o.label, label: o.label })) } };
+            }
+            index = match.index;
+        }
+        if (index == null || !Number.isFinite(index)) {
+            return { ok: false, error: 'choiceIndex or choiceLabel required to select' };
+        }
+
+        const keys = (action.submit_key || '{index}\r').replace(/\{index\}/g, String(index));
+        this.driver.dispatch({ kind: 'pty_write', data: keys });
+        const selected = options.find(o => o.index === index);
+        return {
+            ok: true,
+            effects: [{ type: 'selected_choice', controlId: ctl.id }],
+            controlResult: {
+                ok: true,
+                ...(selected ? { currentValue: selected.label } : {}),
+                selectedIndex: index,
+            },
+        };
+    }
+
+    /** Poll the live screen until the picker's `wait_for` condition matches,
+     *  up to a short budget. Returns true if it rendered, false on timeout. */
+    private async waitForPickerRendered(action: Extract<ControlAction, { type: 'open_picker' }>): Promise<boolean> {
+        const wf = action.wait_for;
+        if (!wf?.regex) { await delay(250); return true; }
+        const re = new RegExp(wf.regex, wf.flags ?? 'i');
+        const deadline = Date.now() + 2500;
+        while (Date.now() < deadline) {
+            await delay(120);
+            const hay = this.readScreenSectionText(wf.section);
+            if (re.test(hay)) return true;
+        }
+        return false;
+    }
+
+    /** Parse the picker's `extract_choices` pattern against the live screen.
+     *  Each match yields { index, label, current }. `current` is true for the
+     *  line the CLI marks with its cursor glyph (❯ ›). Purely screen-driven —
+     *  no model/mode names are baked in. */
+    private extractPickerChoices(action: Extract<ControlAction, { type: 'open_picker' }>): Array<{ index: number; label: string; current: boolean }> {
+        const ec = action.extract_choices;
+        if (!ec?.pattern) return [];
+        const text = this.readScreenSectionText(ec.section);
+        const out: Array<{ index: number; label: string; current: boolean }> = [];
+        const seen = new Set<number>();
+        for (const rawLine of text.split('\n')) {
+            const line = rawLine.replace(/\r$/, '');
+            const m = new RegExp(ec.pattern, ec.flags ?? '').exec(line);
+            if (!m) continue;
+            const idx = Number(m[1]);
+            if (!Number.isFinite(idx) || seen.has(idx)) continue;
+            const label = (m[2] ?? '').replace(/\s+/g, ' ').trim();
+            if (!label) continue;
+            const current = /^\s*[❯›>]/.test(line) || /[✔✓●]\s*$/.test(label);
+            seen.add(idx);
+            out.push({ index: idx, label, current });
+        }
+        return out;
+    }
+
+    /** Live text of a named screen section (or the whole screen when no
+     *  section is named), resolved from the driver's current sections. */
+    private readScreenSectionText(sectionId?: string): string {
+        try {
+            const sections = this.driver.getSections();
+            if (sectionId && sections) {
+                const hit = sections.find(s => s.id === sectionId);
+                if (hit) return hit.text;
+            }
+            return this.driver.getScreen();
+        } catch {
+            return '';
+        }
     }
     getDebugSnapshot(): unknown {
         let screen = '';

package/src/providers/spec/fsm-driver.ts

@@ -752,7 +752,20 @@ export class FsmDriver implements ISpecDriver {
         switch (a.type) {
             case 'send_keys': this.adapter.send_keys(a.keys); return;
             case 'open_picker':
-                this.adapter.send_keys(a.trigger_keys);
+                // Some TUIs (e.g. codex) don't register a slash command if its
+                // text and the submitting Enter arrive in the same write — the
+                // composer needs a beat to recognise the command before the CR.
+                // Split a trailing CR/LF off the trigger and send it after a
+                // short delay, mirroring send_message's delay_ms_before_submit.
+                {
+                    const m = /^([\s\S]*?)([\r\n]+)$/.exec(a.trigger_keys);
+                    if (m && m[1]) {
+                        this.adapter.send_keys(m[1]);
+                        setTimeout(() => this.adapter.send_keys(m[2]), 200);
+                    } else {
+                        this.adapter.send_keys(a.trigger_keys);
+                    }
+                }
                 this.pickerInProgress = { control_id: ctl.id, spec: ctl };
                 return;
             case 'attach_image': {

package/src/providers/spec/native-history-executor.ts

@@ -26,6 +26,7 @@ import type {
     NativeHistoryJsonlSource,
     NativeHistoryMessageMap,
     NativeHistorySqliteSource,
+    NativeHistoryToolMap,
 } from './types.js';
 
 export interface NativeHistoryInput {
@@ -163,8 +164,7 @@ function executeJsonl(src: NativeHistoryJsonlSource, input: NativeHistoryInput):
     for (let i = 0; i < lines.length; i += 1) {
         const rec = lines[i];
         if (filter && !filter(rec)) continue;
-        const msg = projectMessage(rec, src.message_map, i, lines.length, mtime);
-        if (msg) {
+        for (const msg of projectMessages(rec, src.message_map, i, lines.length, mtime)) {
             if (transcriptWorkspace) msg.workspace = transcriptWorkspace;
             messages.push(msg);
         }
@@ -256,8 +256,9 @@ function executeSqlite(src: NativeHistorySqliteSource, input: NativeHistoryInput
         const mtime = safeMtimeMs(resolved);
         const messages: NativeHistoryMessage[] = [];
         for (let i = 0; i < messageRows.length; i += 1) {
-            const msg = projectMessage(messageRows[i], src.message_map, i, messageRows.length, mtime);
-            if (msg) messages.push(msg);
+            for (const msg of projectMessages(messageRows[i], src.message_map, i, messageRows.length, mtime)) {
+                messages.push(msg);
+            }
         }
         if (messages.length === 0) return null;
 
@@ -749,11 +750,75 @@ function jsonPathGet(record: any, expr: string): unknown {
     return cur;
 }
 
-function projectMessage(record: any, map: NativeHistoryMessageMap, index: number, total: number, sourceMtimeMs: number): NativeHistoryMessage | null {
+/**
+ * Project one on-disk record into zero or more transcript messages.
+ *
+ * A record yields at most one text bubble (the prose turn) plus — when the
+ * spec declares `message_map.tools` — one `kind:'tool'` bubble per tool-call
+ * or tool-result content block. Without `tools`, behaviour is identical to
+ * the old single-message projection: text-only, tool blocks dropped.
+ */
+function projectMessages(record: any, map: NativeHistoryMessageMap, index: number, total: number, sourceMtimeMs: number): NativeHistoryMessage[] {
     const roleRaw = jsonPathGet(record, map.role);
-    const contentRaw = jsonPathGet(record, map.content);
     const role = normalizeRole(roleRaw);
-    let content = stringifyContent(contentRaw);
+
+    // Records are passed in chronological order (oldest → newest), so the
+    // last record's receivedAt should be ~sourceMtimeMs (when the file was
+    // last touched) and earlier records should walk backwards. Earlier
+    // version had this inverted, which made the dashboard render bubbles
+    // in reverse order and produce the "chat jumping" effect.
+    let receivedAt = sourceMtimeMs - ((total - 1 - index) * 1000);
+    if (map.timestamp_ms) {
+        const tsRaw = jsonPathGet(record, map.timestamp_ms);
+        const parsed = parseTimestamp(tsRaw);
+        if (parsed != null) receivedAt = parsed;
+    }
+    const kindRaw = map.kind ? jsonPathGet(record, map.kind) : undefined;
+    const kind = typeof kindRaw === 'string' && kindRaw ? kindRaw : 'standard';
+
+    const out: NativeHistoryMessage[] = [];
+
+    // Two transcript shapes carry tool activity:
+    //   - record-level: the whole record IS a tool call/result (codex stores
+    //     each function_call / function_call_output as its own jsonl record).
+    //   - block-nested: tool blocks live inside the message's content array
+    //     (claude stores tool_use / tool_result as content blocks).
+    // When the spec opts into `tools`, try the record itself first; if it's a
+    // tool record we emit only that bubble (it has no prose). Otherwise emit
+    // the text bubble plus a tool bubble per matching content block.
+    if (map.tools) {
+        const recordTool = projectToolBlock(record, role, map.tools);
+        if (recordTool) {
+            out.push({ ...recordTool, receivedAt });
+            return out;
+        }
+    }
+
+    const contentRaw = jsonPathGet(record, map.content);
+    const content = cleanContent(stringifyContent(contentRaw), map);
+    if (content) out.push({ role, content, receivedAt, kind });
+
+    // Block-nested tool bubbles are ordered just after the text bubble of the
+    // same record by nudging receivedAt forward a millisecond per bubble, so a
+    // turn's prose still renders before its tool activity without colliding
+    // with the next record's timestamp.
+    if (map.tools && Array.isArray(contentRaw)) {
+        let nudge = 1;
+        for (const block of contentRaw) {
+            const tool = projectToolBlock(block, role, map.tools);
+            if (tool) {
+                out.push({ ...tool, receivedAt: receivedAt + nudge });
+                nudge += 1;
+            }
+        }
+    }
+
+    return out;
+}
+
+/** Apply content_strip / content_unwrap tag surgery and trim. */
+function cleanContent(input: string, map: NativeHistoryMessageMap): string {
+    let content = input;
     if (content && map.content_strip) {
         for (const tag of map.content_strip) {
             const safeTag = tag.replace(/[.+^${}()|[\]\\]/g, '\\$&');
@@ -769,23 +834,50 @@ function projectMessage(record: any, map: NativeHistoryMessageMap, index: number
             content = content.replace(open, '').replace(close, '');
         }
     }
-    if (content) content = content.trim();
-    if (!content) return null;
+    return content ? content.trim() : '';
+}
 
-    // Records are passed in chronological order (oldest → newest), so the
-    // last record's receivedAt should be ~sourceMtimeMs (when the file was
-    // last touched) and earlier records should walk backwards. Earlier
-    // version had this inverted, which made the dashboard render bubbles
-    // in reverse order and produce the "chat jumping" effect.
-    let receivedAt = sourceMtimeMs - ((total - 1 - index) * 1000);
-    if (map.timestamp_ms) {
-        const tsRaw = jsonPathGet(record, map.timestamp_ms);
-        const parsed = parseTimestamp(tsRaw);
-        if (parsed != null) receivedAt = parsed;
+const DEFAULT_TOOL_CALL_TYPES = ['tool_use', 'function_call', 'custom_tool_call'];
+const DEFAULT_TOOL_RESULT_TYPES = ['tool_result', 'function_call_output', 'custom_tool_call_output'];
+
+/**
+ * Turn a single content block into a `kind:'tool'` message, or null if the
+ * block is not a tool call/result. Field locations come from the spec's
+ * `tools` map with Anthropic-block defaults.
+ *
+ * Both tool calls and tool results render on the assistant side: a tool call
+ * is the agent's action, and a tool result is part of the agent's work, not a
+ * user turn (claude/codex persist results under the user / no role, which would
+ * otherwise misattribute them). Calls render as `↗ {name}: {one-line args}`,
+ * results as `↘ {one-line result}`. The `role` param is accepted for symmetry
+ * but tool bubbles are always assistant.
+ */
+function projectToolBlock(block: any, role: 'user' | 'assistant' | 'system', tmap: NativeHistoryToolMap): NativeHistoryMessage | null {
+    void role;
+    if (block == null || typeof block !== 'object') return null;
+    const typeVal = String(jsonPathGet(block, tmap.block_type || '$.type') ?? '');
+    if (!typeVal) return null;
+    const callTypes = tmap.call_types ?? DEFAULT_TOOL_CALL_TYPES;
+    const resultTypes = tmap.result_types ?? DEFAULT_TOOL_RESULT_TYPES;
+
+    if (callTypes.includes(typeVal)) {
+        const name = String(jsonPathGet(block, tmap.call_name || '$.name') ?? 'tool').trim() || 'tool';
+        const args = oneLine(stringifyContent(jsonPathGet(block, tmap.call_args || '$.input')), 240);
+        const content = args ? `↗ ${name}: ${args}` : `↗ ${name}`;
+        return { role: 'assistant', content, receivedAt: 0, kind: 'tool' };
     }
-    const kindRaw = map.kind ? jsonPathGet(record, map.kind) : undefined;
-    const kind = typeof kindRaw === 'string' && kindRaw ? kindRaw : 'standard';
-    return { role, content, receivedAt, kind };
+    if (resultTypes.includes(typeVal)) {
+        const result = oneLine(stringifyContent(jsonPathGet(block, tmap.result_content || '$.content')), 600);
+        if (!result) return null;
+        return { role: 'assistant', content: `↘ ${result}`, receivedAt: 0, kind: 'tool' };
+    }
+    return null;
+}
+
+/** Collapse whitespace to single spaces and cap length for a tool summary. */
+function oneLine(s: string, max: number): string {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? flat.slice(0, max - 1) + '…' : flat;
 }
 
 /**

package/src/providers/spec/types.ts

@@ -98,6 +98,43 @@ export interface NativeHistoryMessageMap {
     content_unwrap?: string[];
     timestamp_ms?: string;
     kind?: string;
+    /**
+     * Declarative tool-bubble extraction. Without it the executor only emits
+     * the text-bearing parts of each record, so a turn that is purely a tool
+     * call or tool result (no prose) is dropped — the restored transcript
+     * loses every tool interaction. When present, the executor walks each
+     * record's content blocks and emits an extra `kind:'tool'` message for
+     * any block whose `$.type` matches a tool shape.
+     *
+     * Defaults target the Anthropic-style content-block shape that claude-cli
+     * and codex-cli persist (blocks of `{ type: 'tool_use' | 'tool_result',
+     * name, input, content }`); a provider with a different on-disk shape
+     * overrides the field paths. Set `tools: {}` to opt in with the defaults.
+     */
+    tools?: NativeHistoryToolMap;
+}
+
+/**
+ * How to surface tool-call / tool-result blocks as `kind:'tool'` bubbles.
+ * Every field is optional — the defaults read the Anthropic block shape.
+ * Paths are jsonpath-lite evaluated against a single content block (the
+ * element of `$.message.content[]`), not the whole record.
+ */
+export interface NativeHistoryToolMap {
+    /** Path to a block's discriminator. Default `$.type`. */
+    block_type?: string;
+    /** Block-type values that mean "a tool was invoked". Default
+     *  `['tool_use', 'function_call', 'custom_tool_call']`. */
+    call_types?: string[];
+    /** Block-type values that mean "a tool returned". Default
+     *  `['tool_result', 'function_call_output', 'custom_tool_call_output']`. */
+    result_types?: string[];
+    /** Path to the tool name on a call block. Default `$.name`. */
+    call_name?: string;
+    /** Path to the tool arguments on a call block. Default `$.input`. */
+    call_args?: string;
+    /** Path to the result payload on a result block. Default `$.content`. */
+    result_content?: string;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/repo-mesh-types.ts

@@ -91,6 +91,93 @@ export type RepoMeshNodeHealth =
 export type RepoMeshSessionCleanupMode = 'preserve' | 'stop' | 'delete_stopped' | 'stop_and_delete';
 export type RepoMeshSpawnedSessionVisibility = 'visible' | 'hidden';
 
+/**
+ * Mesh-wide tie-break strategy for distributing untargeted queue work across
+ * eligible nodes. This ONLY governs the final tie-break stage of the scheduler
+ * pipeline (TAG hard-filter → MAX-ALLOC capacity gate → PRIORITY soft score →
+ * TIE-BREAK); eligibility/capacity/priority are evaluated identically for every
+ * strategy.
+ *
+ * - 'first_eligible' (DEFAULT): preserve today's behavior exactly. Nodes are
+ *   visited in config/array order and the first that can launch wins. No
+ *   load-spreading. This is the strict no-change default — a mesh that never
+ *   sets schedulingStrategy behaves identically to before this feature.
+ * - 'least_loaded': prefer the eligible node with the fewest active assignments,
+ *   so untargeted work spreads instead of piling onto whichever node asks first.
+ * - 'round_robin': among nodes tied at the least load, rotate the winner using a
+ *   per-mesh cursor so distribution stays fair across passes.
+ * - 'priority_only': rank purely by schedulingPriority (then config order),
+ *   ignoring load — always send to the highest-priority eligible node.
+ *
+ * Distribution is explicit opt-in: a strategy other than 'first_eligible' must be
+ * configured for any load-spreading to occur.
+ */
+export type RepoMeshSchedulingStrategy =
+    | 'first_eligible'
+    | 'least_loaded'
+    | 'round_robin'
+    | 'priority_only';
+
+export const MESH_SCHEDULING_STRATEGIES: RepoMeshSchedulingStrategy[] = [
+    'first_eligible',
+    'least_loaded',
+    'round_robin',
+    'priority_only',
+];
+
+export const DEFAULT_MESH_SCHEDULING_STRATEGY: RepoMeshSchedulingStrategy = 'first_eligible';
+
+/**
+ * Normalize an unknown scheduling-strategy value to a valid strategy, defaulting
+ * to 'first_eligible' (strict no-change) for anything missing/blank/unrecognized.
+ */
+export function normalizeMeshSchedulingStrategy(value: unknown): RepoMeshSchedulingStrategy {
+    if (typeof value !== 'string') return DEFAULT_MESH_SCHEDULING_STRATEGY;
+    const trimmed = value.trim() as RepoMeshSchedulingStrategy;
+    return (MESH_SCHEDULING_STRATEGIES as string[]).includes(trimmed)
+        ? trimmed
+        : DEFAULT_MESH_SCHEDULING_STRATEGY;
+}
+
+/**
+ * Resolve a node's soft scheduling priority — a single scalar used as the PRIORITY
+ * stage rank key (higher = preferred). It is NOT an eligibility gate (the MAX-ALLOC
+ * capacity gate alone decides whether a node can take work). Missing/blank/NaN
+ * resolves to 0 so unconfigured nodes all share the same neutral priority.
+ */
+export function resolveNodeSchedulingPriority(
+    nodePolicy: Pick<RepoMeshNodePolicy, 'schedulingPriority'> | null | undefined,
+): number {
+    const raw = Number(nodePolicy?.schedulingPriority);
+    return Number.isFinite(raw) ? raw : 0;
+}
+
+/**
+ * Synthetic capability tag advertised by every mesh node describing how it can land
+ * its work onto the base branch:
+ *   - converge=refine: a local worktree node (on any machine — refine_mesh_node
+ *     forwards to the owning daemon) can run the Refinery merge → push → cleanup.
+ *   - converge=fast_forward: a non-worktree node (the machine itself) can only
+ *     fast-forward/push an already-converged branch.
+ * Emitted by buildMeshNodeCapabilityTags and matched through the ordinary
+ * required-tags filter.
+ */
+export const MESH_CONVERGE_REFINE_TAG = 'converge=refine';
+export const MESH_CONVERGE_FAST_FORWARD_TAG = 'converge=fast_forward';
+
+/**
+ * Resolve whether the load-balancing scheduler should auto-inject a
+ * `converge=refine` required tag onto code_change tasks so they hard-filter onto
+ * refine-capable (worktree) nodes only. Strict opt-in: defaults to false, so a mesh
+ * that does not set it behaves exactly as before (code_change routes to any eligible
+ * node, including a non-worktree machine node when no worktree exists).
+ */
+export function resolveAutoConvergeCodeChange(
+    policy: Pick<RepoMeshPolicy, 'autoConvergeCodeChange'> | null | undefined,
+): boolean {
+    return policy?.autoConvergeCodeChange === true;
+}
+
 export interface RepoMeshAutoFastForwardPolicy {
     /** Defaults to true. Set false to disable daemon-initiated idle fast-forwards. */
     enabled: boolean;
@@ -115,6 +202,24 @@ export interface RepoMeshPolicy {
     dirtyWorkspaceBehavior: 'block' | 'warn' | 'checkpoint_then_continue';
     maxParallelTasks: number;
     allowedProviders?: string[];
+    /**
+     * Mesh-wide tie-break strategy for distributing untargeted queue work across
+     * eligible nodes. Defaults to 'first_eligible' (today's exact behavior — no
+     * load-spreading). Set to 'least_loaded' / 'round_robin' / 'priority_only' to
+     * opt into distribution. Only governs the final tie-break stage; eligibility,
+     * capacity, and priority are evaluated identically regardless of strategy.
+     */
+    schedulingStrategy?: RepoMeshSchedulingStrategy;
+    /**
+     * Convergence routing opt-in: when true, the scheduler auto-injects a
+     * `converge=refine` required tag onto every code_change task at enqueue time, so
+     * code_change work hard-filters onto refine-capable worktree nodes (on any
+     * machine — refine_mesh_node forwards to the owning daemon) and never lands on a
+     * non-worktree machine node. Explicit target_node_id routing and any
+     * caller-supplied required_tags are preserved (the tag is merged, not replaced).
+     * Defaults to false: code_change routing is unchanged unless opted in.
+     */
+    autoConvergeCodeChange?: boolean;
     /**
      * Whether sessions spawned by mesh/coordinator policy should auto-open as visible
      * dashboard tabs or start hidden. Defaults to 'visible' to preserve existing
@@ -163,12 +268,17 @@ export interface RepoMeshRelatedRepo {
  *
  * `role` is a free-form resource-pool label (recommended values:
  * 'investigation' | 'coding' | 'orchestration') describing what this
- * (node, provider) combination is *for*. It is a label/hint only — it is
- * surfaced to the coordinator and dashboards but the daemon does NOT route
- * tasks by role (task routing stays driven by taskMode + requiredTags +
- * targetNode/targetSession). role is intentionally orthogonal to taskMode:
- * taskMode classifies the *work* (code_change vs live_debug_readonly), role
- * classifies the *resource pool*.
+ * (node, provider) combination is *for*. As of the load-balancing scheduler it
+ * is ALSO routable: each declared role is advertised as a synthetic `role=<x>`
+ * capability tag (see buildMeshNodeCapabilityTags), so a task enqueued with
+ * requiredTags: ["role=validation"] is hard-filtered to nodes/providers that
+ * declare that role — through the same nodeSatisfiesRequiredTags path as any
+ * other tag. There is intentionally no separate "advertisedRoles" field: the
+ * label and the routing tag are one mechanism. A task that does not require a
+ * `role=` tag ignores roles entirely (opt-in, fully backward compatible).
+ *
+ * role is intentionally orthogonal to taskMode: taskMode classifies the *work*
+ * (code_change vs live_debug_readonly), role classifies the *resource pool*.
  *
  * `maxParallel` is the only enforced field: the queue will not assign a task
  * to this (node, provider) once it already has `maxParallel` active
@@ -190,15 +300,24 @@ export interface RepoMeshNodePolicy {
     readOnly?: boolean;
     canPush?: boolean;
     maxConcurrentSessions?: number;
+    /**
+     * Soft scheduling priority used as the PRIORITY rank key (higher = preferred)
+     * when the mesh schedulingStrategy spreads work across nodes. Defaults to 0.
+     * This is NOT an eligibility gate — a node with a high priority that is at its
+     * capacity (MAX-ALLOC gate) is still skipped; priority only orders nodes that
+     * can actually take work. Ignored entirely under 'first_eligible'.
+     */
+    schedulingPriority?: number;
     /** Ordered provider preference used when mesh_launch_session omits an explicit type. */
     providerPriority?: string[];
     /**
      * Per-(node, provider) role + parallelism declarations. Each entry binds a
      * providerType on THIS node to an optional free-form role label and an
-     * optional maxParallel cap. Only maxParallel is enforced (as an additional,
+     * optional maxParallel cap. maxParallel is enforced (as an additional,
      * stricter-wins constraint on top of the global maxParallelTasks/taskMode
-     * caps); role is a label/hint surfaced to the coordinator. Missing/empty:
-     * the node behaves exactly as before (global caps only).
+     * caps); role is advertised as a routable `role=<x>` capability tag so tasks
+     * can hard-filter by required role. Missing/empty: the node behaves exactly
+     * as before (global caps only, no role tags).
      */
     providerRoles?: RepoMeshProviderRole[];
     /**