@adhdev/daemon-core 0.9.82-rc.9 → 0.9.82-rc.90

package/src/launch.ts

@@ -16,7 +16,16 @@
  * adhdev launch --workspace /path — Open specific workspace
  */
 
-import { execSync, spawn, spawnSync } from 'child_process';
+import { exec, spawn, spawnSync } from 'child_process';
+
+async function execQuiet(command: string, options: any = {}): Promise<string> {
+    return new Promise((resolve) => {
+        exec(command, options, (error, stdout) => {
+            if (error) return resolve('');
+            resolve(stdout.toString());
+        });
+    });
+}
 import * as net from 'net';
 import * as os from 'os';
 import * as path from 'path';
@@ -76,11 +85,11 @@ function getIdePathCandidates(ideId: string): string[] {
     return getProviderLoader().getIdePathCandidates(ideId);
 }
 
-function getMacAppProcessPids(ideId: string): number[] {
+async function getMacAppProcessPids(ideId: string): Promise<number[]> {
     const appPaths = getIdePathCandidates(ideId);
     if (appPaths.length === 0) return [];
     try {
-        const output = execSync('ps axww -o pid=,args=', {
+        const output = await execQuiet('ps axww -o pid=,args=', {
             encoding: 'utf-8',
             timeout: 3000,
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -91,8 +100,8 @@ function getMacAppProcessPids(ideId: string): number[] {
     }
 }
 
-function killMacAppPathProcesses(ideId: string, signal: NodeJS.Signals): boolean {
-    const pids = getMacAppProcessPids(ideId);
+async function killMacAppPathProcesses(ideId: string, signal: NodeJS.Signals): Promise<boolean> {
+    const pids = (await getMacAppProcessPids(ideId));
     let signalled = false;
     for (const pid of pids) {
         try {
@@ -163,49 +172,49 @@ export async function killIdeProcess(ideId: string): Promise<boolean> {
         if (plat === 'darwin' && appName) {
  // macOS: graceful quit via osascript
             try {
-                execSync(`osascript -e 'tell application "${escapeForAppleScript(appName)}" to quit' 2>/dev/null`, {
+                await execQuiet(`osascript -e 'tell application "${escapeForAppleScript(appName)}" to quit' 2>/dev/null`, {
                     timeout: 5000,
                 });
             } catch {
-                try { execSync(`pkill -x "${appName}" 2>/dev/null`, { timeout: 5000 }); } catch { }
+                try { await execQuiet(`pkill -x "${appName}" 2>/dev/null`, { timeout: 5000 }); } catch { }
             }
-            killMacAppPathProcesses(ideId, 'SIGTERM');
+            await killMacAppPathProcesses(ideId, 'SIGTERM');
         } else if (plat === 'win32' && winProcesses) {
  // Windows: taskkill for each process name
             for (const proc of winProcesses) {
                 try {
-                    execSync(`taskkill /IM "${proc}" /F 2>nul`, { timeout: 5000 });
+                    await execQuiet(`taskkill /IM "${proc}" /F 2>nul`, { timeout: 5000 });
                 } catch { }
             }
  // Process name may differ, so also try via WMIC
             try {
                 const exeName = winProcesses[0].replace('.exe', '');
-                execSync(`powershell -Command "Get-Process -Name '${exeName}' -ErrorAction SilentlyContinue | Stop-Process -Force"`, {
+                await execQuiet(`powershell -Command "Get-Process -Name '${exeName}' -ErrorAction SilentlyContinue | Stop-Process -Force"`, {
                     timeout: 10000,
                 });
             } catch { }
         } else {
-            try { execSync(`pkill -f "${ideId}" 2>/dev/null`); } catch { }
+            try { await execQuiet(`pkill -f "${ideId}" 2>/dev/null`); } catch { }
         }
 
  // Wait for process kill (max 15 seconds)
         for (let i = 0; i < 30; i++) {
             await new Promise(r => setTimeout(r, 500));
-            if (!isIdeRunning(ideId)) return true;
+            if (!(await isIdeRunning(ideId))) return true;
         }
 
  // Force terminate retry
         if (plat === 'darwin' && appName) {
-            try { execSync(`pkill -9 -x "${appName}" 2>/dev/null`, { timeout: 5000 }); } catch { }
-            killMacAppPathProcesses(ideId, 'SIGKILL');
+            try { await execQuiet(`pkill -9 -x "${appName}" 2>/dev/null`, { timeout: 5000 }); } catch { }
+            await killMacAppPathProcesses(ideId, 'SIGKILL');
         } else if (plat === 'win32' && winProcesses) {
             for (const proc of winProcesses) {
-                try { execSync(`taskkill /IM "${proc}" /F 2>nul`); } catch { }
+                try { await execQuiet(`taskkill /IM "${proc}" /F 2>nul`); } catch { }
             }
         }
 
         await new Promise(r => setTimeout(r, 2000));
-        return !isIdeRunning(ideId);
+        return !(await isIdeRunning(ideId));
 
     } catch {
         return false;
@@ -213,15 +222,15 @@ export async function killIdeProcess(ideId: string): Promise<boolean> {
 }
 
 /** Check if IDE process is running */
-export function isIdeRunning(ideId: string): boolean {
+export async function isIdeRunning(ideId: string): Promise<boolean> {
     const plat = os.platform();
 
     try {
         if (plat === 'darwin') {
             const appName = getMacAppIdentifiers()[ideId];
-            if (!appName) return getMacAppProcessPids(ideId).length > 0;
+            if (!appName) return (await getMacAppProcessPids(ideId)).length > 0;
             try {
-                const result = execSync(`pgrep -x "${appName}" 2>/dev/null`, {
+                const result = await execQuiet(`pgrep -x "${appName}" 2>/dev/null`, {
                     encoding: 'utf-8',
                     timeout: 3000,
                 });
@@ -229,7 +238,7 @@ export function isIdeRunning(ideId: string): boolean {
             } catch { }
 
             try {
-                const result = execSync(
+                const result = await execQuiet(
                     `osascript -e 'tell application "System Events" to count (every process whose name is "${escapeForAppleScript(appName)}")'`,
                     {
                         encoding: 'utf-8',
@@ -240,21 +249,21 @@ export function isIdeRunning(ideId: string): boolean {
                 if (Number.parseInt(result.trim() || '0', 10) > 0) return true;
             } catch { }
 
-            return getMacAppProcessPids(ideId).length > 0;
+            return (await getMacAppProcessPids(ideId)).length > 0;
         } else if (plat === 'win32') {
             const winProcesses = getWinProcessNames()[ideId];
             if (!winProcesses) return false;
  // Check each process name
             for (const proc of winProcesses) {
                 try {
-                    const result = execSync(`tasklist /FI "IMAGENAME eq ${proc}" /NH 2>nul`, { encoding: 'utf-8' });
+                    const result = await execQuiet(`tasklist /FI "IMAGENAME eq ${proc}" /NH 2>nul`, { encoding: 'utf-8' });
                     if (result.includes(proc)) return true;
                 } catch { }
             }
  // Also check via PowerShell (when tasklist cannot find)
             try {
                 const exeName = winProcesses[0].replace('.exe', '');
-                const result = execSync(
+                const result = await execQuiet(
                     `powershell -Command "(Get-Process -Name '${exeName}' -ErrorAction SilentlyContinue).Count"`,
                     { encoding: 'utf-8', timeout: 5000 }
                 );
@@ -262,7 +271,7 @@ export function isIdeRunning(ideId: string): boolean {
             } catch { }
             return false;
         } else {
-            const result = execSync(`pgrep -f "${ideId}" 2>/dev/null`, { encoding: 'utf-8' });
+            const result = await execQuiet(`pgrep -f "${ideId}" 2>/dev/null`, { encoding: 'utf-8' });
             return result.trim().length > 0;
         }
     } catch {
@@ -271,14 +280,14 @@ export function isIdeRunning(ideId: string): boolean {
 }
 
 /** Detect currently open workspace path */
-function detectCurrentWorkspace(ideId: string): string | undefined {
+async function detectCurrentWorkspace(ideId: string): Promise<string | undefined> {
     const plat = os.platform();
 
     if (plat === 'darwin') {
         try {
             const appName = getMacAppIdentifiers()[ideId];
             if (!appName) return undefined;
-            const result = execSync(
+            const result = await execQuiet(
                 `lsof -c "${appName}" 2>/dev/null | grep cwd | head -1 | awk '{print $NF}'`,
                 { encoding: 'utf-8', timeout: 3000 }
             );
@@ -392,8 +401,8 @@ export async function launchWithCdp(options: LaunchOptions = {}): Promise<Launch
     }
 
  // 4. Check if IDE is currently running
-    const alreadyRunning = isIdeRunning(targetIde.id);
-    const workspace = options.workspace || (alreadyRunning ? detectCurrentWorkspace(targetIde.id) : undefined);
+    const alreadyRunning = await isIdeRunning(targetIde.id);
+    const workspace = options.workspace || (alreadyRunning ? await detectCurrentWorkspace(targetIde.id) : undefined);
 
  // 5. If IDE is running, terminate it
     if (alreadyRunning) {

package/src/logging/async-batch-writer.ts

@@ -0,0 +1,55 @@
+import * as fs from 'fs';
+
+export class AsyncBatchWriter {
+    // Maps filePath -> string buffer
+    private static buffers: Map<string, string[]> = new Map();
+    private static writePromises: Map<string, Promise<void>> = new Map();
+    private static flushTimer: NodeJS.Timeout | null = null;
+
+    /**
+     * Queues data to be written to a file asynchronously in a batch.
+     */
+    public static write(filePath: string, data: string) {
+        let buf = this.buffers.get(filePath);
+        if (!buf) {
+            buf = [];
+            this.buffers.set(filePath, buf);
+        }
+        buf.push(data);
+
+        if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => {
+                this.flushTimer = null;
+                this.flushAll();
+            }, 50);
+        }
+    }
+
+    private static async flushAll() {
+        const entries = Array.from(this.buffers.entries());
+        this.buffers.clear();
+
+        for (const [filePath, buffer] of entries) {
+            const dataToWrite = buffer.join('');
+            
+            const doWrite = async () => {
+                try {
+                    const prevPromise = this.writePromises.get(filePath);
+                    if (prevPromise) await prevPromise;
+                    await fs.promises.appendFile(filePath, dataToWrite, { encoding: 'utf-8', mode: 0o600 });
+                } catch {
+                    // Logging must never create secondary failures or late console noise.
+                }
+            };
+
+            const writePromise = doWrite();
+            this.writePromises.set(filePath, writePromise);
+            
+            writePromise.finally(() => {
+                if (this.writePromises.get(filePath) === writePromise) {
+                    this.writePromises.delete(filePath);
+                }
+            });
+        }
+    }
+}

package/src/logging/logger.ts

@@ -20,6 +20,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { AsyncBatchWriter } from './async-batch-writer.js';
 
 // ─── Log Level ──────────────────────────────
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
@@ -123,7 +124,7 @@ function writeToFile(line: string): void {
             checkDateRotation();
             rotateSizeIfNeeded();
         }
-        fs.appendFileSync(currentLogFile, line + '\n');
+        AsyncBatchWriter.write(currentLogFile, line + '\n');
     } catch { }
 }
 

package/src/mesh/beads-db.ts

@@ -0,0 +1,176 @@
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { createRequire } from 'module';
+import { getLedgerDir } from './mesh-ledger.js';
+import type { MeshTaskStatus, MeshWorkQueueEntry } from './mesh-work-queue.js';
+import type BetterSqlite3 from 'better-sqlite3';
+import type { Database as DatabaseHandle } from 'better-sqlite3';
+
+let DatabaseCtor: typeof BetterSqlite3 | undefined;
+
+function loadDatabaseCtor(): typeof BetterSqlite3 {
+    if (DatabaseCtor) return DatabaseCtor;
+    const runtimeRequire = typeof require === 'function'
+        ? require
+        : createRequire(import.meta.url);
+    DatabaseCtor = runtimeRequire('better-sqlite3') as typeof BetterSqlite3;
+    return DatabaseCtor;
+}
+
+function safeMeshId(meshId: string): string {
+    return meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+
+function legacyQueuePath(meshId: string): string {
+    return join(getLedgerDir(), `${safeMeshId(meshId)}.queue.json`);
+}
+
+export class BeadsDB {
+    private static instance: BeadsDB | undefined;
+    private readonly db: DatabaseHandle;
+    private readonly migratedMeshIds = new Set<string>();
+
+    private constructor(dbPath: string) {
+        const dir = dirname(dbPath);
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+        this.db = new (loadDatabaseCtor())(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('synchronous = NORMAL');
+        this.db.pragma('foreign_keys = ON');
+        this.db.pragma('busy_timeout = 5000');
+        this.migrate();
+    }
+
+    static getInstance(): BeadsDB {
+        if (!this.instance) {
+            this.instance = new BeadsDB(join(getLedgerDir(), 'beads.db'));
+        }
+        return this.instance;
+    }
+
+    static resetForTests(): void {
+        this.instance?.close();
+        this.instance = undefined;
+    }
+
+    close(): void {
+        this.db.close();
+    }
+
+    transaction<T>(fn: () => T): T {
+        return this.db.transaction(fn).immediate();
+    }
+
+    private migrate(): void {
+        this.db.exec(`
+            CREATE TABLE IF NOT EXISTS mesh_queue (
+                id TEXT PRIMARY KEY,
+                mesh_id TEXT NOT NULL,
+                status TEXT NOT NULL,
+                target_node_id TEXT,
+                target_session_id TEXT,
+                assigned_node_id TEXT,
+                assigned_session_id TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                payload TEXT NOT NULL
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_mesh_queue_mesh_status_created
+                ON mesh_queue(mesh_id, status, created_at);
+            CREATE INDEX IF NOT EXISTS idx_mesh_queue_assignment
+                ON mesh_queue(mesh_id, assigned_node_id, assigned_session_id, status);
+        `);
+    }
+
+    private ensureLegacyQueueMigrated(meshId: string): void {
+        if (this.migratedMeshIds.has(meshId)) return;
+        this.migratedMeshIds.add(meshId);
+
+        const count = this.db
+            .prepare('SELECT COUNT(*) AS count FROM mesh_queue WHERE mesh_id = ?')
+            .get(meshId) as { count: number };
+        if (count.count > 0) return;
+
+        const path = legacyQueuePath(meshId);
+        if (!existsSync(path)) return;
+
+        try {
+            const entries = JSON.parse(readFileSync(path, 'utf-8')) as MeshWorkQueueEntry[];
+            if (!Array.isArray(entries)) return;
+            const insert = this.db.prepare(`
+                INSERT OR REPLACE INTO mesh_queue (
+                    id, mesh_id, status, target_node_id, target_session_id,
+                    assigned_node_id, assigned_session_id, created_at, updated_at, payload
+                ) VALUES (
+                    @id, @meshId, @status, @targetNodeId, @targetSessionId,
+                    @assignedNodeId, @assignedSessionId, @createdAt, @updatedAt, @payload
+                )
+            `);
+            for (const entry of entries) {
+                insert.run(this.toRow(entry));
+            }
+        } catch {
+            return;
+        }
+    }
+
+    getQueueEntries(meshId: string, statuses?: MeshTaskStatus[]): MeshWorkQueueEntry[] {
+        this.ensureLegacyQueueMigrated(meshId);
+        if (statuses?.length) {
+            const placeholders = statuses.map(() => '?').join(', ');
+            const rows = this.db
+                .prepare(`SELECT payload FROM mesh_queue WHERE mesh_id = ? AND status IN (${placeholders}) ORDER BY created_at ASC`)
+                .all(meshId, ...statuses) as Array<{ payload: string }>;
+            return rows.map(row => JSON.parse(row.payload) as MeshWorkQueueEntry);
+        }
+        const rows = this.db
+            .prepare('SELECT payload FROM mesh_queue WHERE mesh_id = ? ORDER BY created_at ASC')
+            .all(meshId) as Array<{ payload: string }>;
+        return rows.map(row => JSON.parse(row.payload) as MeshWorkQueueEntry);
+    }
+
+    getQueueRevision(meshId: string): string {
+        this.ensureLegacyQueueMigrated(meshId);
+        const rows = this.db
+            .prepare('SELECT id, status, updated_at FROM mesh_queue WHERE mesh_id = ? ORDER BY id ASC')
+            .all(meshId) as Array<{ id: string; status: string; updated_at: string }>;
+        return rows.map(row => `${row.id}:${row.status}:${row.updated_at}`).join('|');
+    }
+
+    replaceQueue(meshId: string, queue: MeshWorkQueueEntry[]): void {
+        const deleteStmt = this.db.prepare('DELETE FROM mesh_queue WHERE mesh_id = ?');
+        const insert = this.db.prepare(`
+            INSERT INTO mesh_queue (
+                id, mesh_id, status, target_node_id, target_session_id,
+                assigned_node_id, assigned_session_id, created_at, updated_at, payload
+            ) VALUES (
+                @id, @meshId, @status, @targetNodeId, @targetSessionId,
+                @assignedNodeId, @assignedSessionId, @createdAt, @updatedAt, @payload
+            )
+        `);
+        deleteStmt.run(meshId);
+        for (const entry of queue) insert.run(this.toRow(entry));
+    }
+
+    deleteQueue(meshId: string): void {
+        this.db.prepare('DELETE FROM mesh_queue WHERE mesh_id = ?').run(meshId);
+        this.migratedMeshIds.delete(meshId);
+    }
+
+    private toRow(entry: MeshWorkQueueEntry): Record<string, unknown> {
+        return {
+            id: entry.id,
+            meshId: entry.meshId,
+            status: entry.status,
+            targetNodeId: entry.targetNodeId ?? null,
+            targetSessionId: entry.targetSessionId ?? null,
+            assignedNodeId: entry.assignedNodeId ?? null,
+            assignedSessionId: entry.assignedSessionId ?? null,
+            createdAt: entry.createdAt,
+            updatedAt: entry.updatedAt,
+            payload: JSON.stringify(entry),
+        };
+    }
+}

package/src/mesh/coordinator-prompt.ts

@@ -76,7 +76,12 @@ Repository: \`${mesh.repoIdentity}\`${mesh.defaultBranch ? `\nDefault branch: \`
 // ─── Section Builders ───────────────────────────
 
 function buildNodeStatusSection(nodes: RepoMeshNodeStatus[]): string {
-    const lines = ['## Current Node Status', ''];
+    const lines = [
+        '## Current Node Status',
+        '',
+        'Node labels are display context, not aliases. Use exact `nodeId` values in mesh tool calls; do not invent shorthand names such as M1/M2 unless they are explicitly configured labels.',
+        '',
+    ];
     for (const n of nodes) {
         const healthIcon = n.health === 'online' ? '🟢' :
             n.health === 'dirty' ? '🟡' :
@@ -85,21 +90,33 @@ function buildNodeStatusSection(nodes: RepoMeshNodeStatus[]): string {
             ? `sessions: ${n.activeSessions.join(', ')}`
             : 'no active sessions';
         const branch = n.git?.branch ? `branch: \`${n.git.branch}\`` : '';
-        lines.push(`- ${healthIcon} **${n.machineLabel}** (${n.nodeId})`);
-        lines.push(`  workspace: \`${n.workspace}\` | ${branch} | ${sessions}`);
+        const context = [
+            n.daemonId ? `daemon: \`${n.daemonId}\`` : '',
+            n.providers?.length ? `providers: ${n.providers.join(', ')}` : '',
+        ].filter(Boolean).join(' | ');
+        lines.push(`- ${healthIcon} **${n.machineLabel}** (nodeId: \`${n.nodeId}\`)`);
+        lines.push(`  workspace: \`${n.workspace}\`${context ? ` | ${context}` : ''} | ${branch} | ${sessions}`);
         if (n.error) lines.push(`  ⚠️ ${n.error}`);
     }
     return lines.join('\n');
 }
 
 function buildNodeConfigSection(mesh: LocalMeshEntry): string {
-    const lines = ['## Configured Nodes', ''];
+    const lines = [
+        '## Configured Nodes',
+        '',
+        'Node labels are display context, not aliases. Use exact `nodeId` values in mesh tool calls; do not invent shorthand names such as M1/M2 unless they are explicitly configured labels.',
+        '',
+    ];
     for (const n of mesh.nodes) {
         const labels: string[] = [];
         if (n.isLocalWorktree) labels.push('worktree');
         if (n.policy?.readOnly) labels.push('read-only');
         const suffix = labels.length ? ` [${labels.join(', ')}]` : '';
-        lines.push(`- **${n.workspace}** (${n.id})${suffix}`);
+        const explicitMachineLabel = typeof (n as any).machineLabel === 'string' ? (n as any).machineLabel : '';
+        const explicitLabel = explicitMachineLabel ? ` label: **${explicitMachineLabel}** |` : '';
+        const providerPriority = n.policy?.providerPriority?.length ? ` | providers: ${n.policy.providerPriority.join(', ')}` : '';
+        lines.push(`- ${explicitLabel} nodeId: \`${n.id}\` | workspace: \`${n.workspace}\`${n.daemonId ? ` | daemon: \`${n.daemonId}\`` : ''}${providerPriority}${suffix}`);
     }
     lines.push('', '_Use `mesh_status` to probe live health before delegating work._');
     return lines.join('\n');
@@ -110,6 +127,9 @@ function buildPolicySection(policy: RepoMeshPolicy): string {
     if (policy.requirePreTaskCheckpoint) rules.push('- Create a git checkpoint **before** starting each task');
     if (policy.requirePostTaskCheckpoint) rules.push('- Create a git checkpoint **after** each task completes');
     if (policy.requireApprovalForPush) rules.push('- **Ask for user approval** before pushing to remote');
+    if (policy.allowAutoPublishSubmoduleMainCommits) {
+        rules.push('- Refinery may auto-publish unreachable submodule gitlink commits to submodule origin/main with non-force pushes after validation and patch-equivalence pass');
+    }
     if (policy.requireApprovalForDestructiveGit) rules.push('- **Ask for user approval** before destructive git operations (force push, reset, etc.)');
 
     const dirtyBehavior = {
@@ -140,6 +160,7 @@ const TOOLS_SECTION = `## Available Tools
 | \`mesh_read_debug\` | Collect a daemon-side chat/parser debug bundle for a session |
 | \`mesh_task_history\` | Read the task ledger — dispatches, completions, failures. Use to understand what has been done before deciding next steps |
 | \`mesh_git_status\` | Check git status on a specific node |
+| \`mesh_fast_forward_node\` | Safely dry-run or explicitly execute an obvious clean fast-forward without launching an agent session |
 | \`mesh_checkpoint\` | Create a git checkpoint on a node |
 | \`mesh_approve\` | Approve/reject a pending agent action |
 | \`mesh_clone_node\` | Create a worktree node for isolated parallel branch work |
@@ -164,7 +185,7 @@ const WORKFLOW_SECTION = `## Orchestration Workflow
 4. **Monitor** — Prefer event-driven completion/status notifications. Do **not** poll \`mesh_read_chat\` repeatedly. Use \`mesh_view_queue\` to see the status of all pending, assigned, completed, and failed tasks. Do not call \`mesh_read_chat\` again within a few seconds for the same generating session. Use at most one compact \`mesh_read_chat\` check after a completion/approval signal. Handle approvals via \`mesh_approve\`.
 5. **Verify** — When a task reports completion or git work is visible, call \`mesh_git_status\` to verify changes were made.
 6. **Checkpoint** — Call \`mesh_checkpoint\` to save the work.
-7. **Converge branches** — Before marking any task complete, classify every touched node/branch into exactly one final state: \`merged_to_main\`, \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\`. Use \`mesh_status\` branchConvergenceSummary and \`mesh_refine_node\` for clean worktree branches when safe. A task that remains on a non-main branch is not fully complete unless the final report names the follow-up state and next step.
+7. **Converge branches** — Before marking any task complete, classify every touched node/branch into exactly one final state: \`merged_to_main\`, \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\`. Use \`mesh_status\` branchConvergenceSummary. For obvious clean branch catch-up (ahead 0, behind > 0, upstream fresh, no dirty/stash/submodule issues), use \`mesh_fast_forward_node\` dry-run first and execute only when explicitly safe/approved; this avoids consuming an agent session. Use \`mesh_refine_node\` for clean worktree branches when safe. Before/refine merging root commits that contain submodule gitlink changes, require each submodule commit to be reachable from the configured submodule remote main branch, not merely present on a feature ref or local checkout. If \`mesh_refine_node\` returns \`submodule_reachability_failed\` or publish-required evidence, keep the public convergence bucket as \`blocked_review\`; unless \`allowAutoPublishSubmoduleMainCommits\` is explicitly enabled and Refinery reports successful non-force publish plus post-publish verification, ask the user for explicit approval to push/publish the unreachable submodule commit(s) to submodule main, then rerun \`mesh_refine_node\`. Do not merge the root branch until the submodule commit(s) are reachable from submodule origin/main. A task that remains on a non-main branch is not fully complete unless the final report names the follow-up state and next step.
 8. **Clean up** — Remove worktree nodes via \`mesh_remove_node\` after their work is merged or no longer needed.
 9. **Report** — Summarize what was done, what changed, any issues, and the branch convergence state.
 
@@ -201,6 +222,8 @@ function buildRulesSection(coordinatorCliType?: string): string {
 - **Respect node capabilities.** Don't send build tasks to read-only nodes. Don't push from nodes that aren't allowed to.
 - **Never fabricate tool results.** Always call the actual tool; never pretend you did.
 - **Clean up worktree nodes.** After a worktree task completes and its changes are merged or checkpointed, call \`mesh_remove_node\` to free resources.
-- **Do not strand completed branches.** A checkpointed or clean feature/worktree branch is not done by itself. Merge/refine it to the mesh default branch, or explicitly report one of \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\` with the next action.
+- **Do not strand completed branches.** A checkpointed or clean feature/worktree branch is not done by itself. Merge/refine it to the mesh default branch, fast-forward obvious clean behind-only branches with \`mesh_fast_forward_node\`, or explicitly report one of \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\` with the next action.
+- **Keep Refinery validation project-configurable.** \`mesh_refine_node\` must execute validation from repo mesh/refine config (for example \`.adhdev/refine.{json,yaml,yml}\`, \`.adhdev/repo-mesh-refine.*\`, or \`repo-mesh.refine.*\`). Heuristics are suggestions/scaffolding only, not the execution path.
+- **Treat submodule main reachability as publish-needed.** A \`submodule_reachability_failed\` refine result means the root gitlink points at a submodule commit that is not reachable from the configured submodule remote main branch. Do not treat feature-branch reachability as complete, retry validation blindly, or start code review first. Classify it as \`blocked_review\`, request user approval to push/publish the submodule commit to submodule main, then rerun \`mesh_refine_node\`, unless the mesh or repo refine config explicitly enabled \`allowAutoPublishSubmoduleMainCommits\` and Refinery reports exact path/commit/remote/branch evidence with post-publish verification.
 - **Name worktree branches meaningfully.** Use descriptive names like \`feat/auth-refactor\` or \`fix/build-123\`.${coordinatorNote}`;
 }