@adhdev/daemon-core 0.9.82-rc.5 → 0.9.82-rc.51

package/src/mesh/mesh-work-queue.ts

@@ -1,7 +1,9 @@
-import { existsSync, writeFileSync, readFileSync } from 'fs';
+import { existsSync, writeFileSync, readFileSync, openSync, closeSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
 import { getLedgerDir } from './mesh-ledger.js';
+import { requireMeshHostQueueOwner } from './mesh-host-ownership.js';
+import type { RepoMeshDaemonRole } from '../repo-mesh-types.js';
 
 export type MeshTaskStatus = 'pending' | 'assigned' | 'completed' | 'failed' | 'cancelled';
 export type MeshActiveTaskStatus = Extract<MeshTaskStatus, 'pending' | 'assigned'>;
@@ -45,11 +47,40 @@ export interface MeshWorkQueueEntry {
     updatedAt: string;
 }
 
+export interface MeshQueueMutationOptions {
+    ownerRole?: RepoMeshDaemonRole;
+}
+
 function getQueuePath(meshId: string): string {
     const safe = meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
     return join(getLedgerDir(), `${safe}.queue.json`);
 }
 
+function getLockPath(meshId: string): string {
+    const safe = meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(getLedgerDir(), `${safe}.queue.lock`);
+}
+
+/**
+ * Simple advisory file lock using O_EXCL (atomic create) for queue mutations.
+ * Retries up to 10 times at 30 ms intervals; proceeds without lock on timeout
+ * to prevent deadlock (best-effort — far better than no locking at all).
+ */
+function withQueueLock<T>(meshId: string, fn: () => T): T {
+    const lockPath = getLockPath(meshId);
+    let fd = -1;
+    for (let i = 0; i < 10; i++) {
+        try { fd = openSync(lockPath, 'wx'); break; } catch {
+            const deadline = Date.now() + 30;
+            while (Date.now() < deadline) { /* spin */ }
+        }
+    }
+    try { return fn(); } finally {
+        if (fd !== -1) try { closeSync(fd); } catch { /* noop */ }
+        try { unlinkSync(lockPath); } catch { /* already removed */ }
+    }
+}
+
 function readQueue(meshId: string): MeshWorkQueueEntry[] {
     const path = getQueuePath(meshId);
     if (!existsSync(path)) return [];
@@ -72,22 +103,25 @@ function writeQueue(meshId: string, queue: MeshWorkQueueEntry[]): void {
 export function enqueueTask(
     meshId: string,
     message: string,
-    opts?: { targetNodeId?: string; targetSessionId?: string }
+    opts?: { targetNodeId?: string; targetSessionId?: string } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry {
-    const queue = readQueue(meshId);
-    const entry: MeshWorkQueueEntry = {
-        id: randomUUID(),
-        meshId,
-        message,
-        status: 'pending',
-        targetNodeId: opts?.targetNodeId,
-        targetSessionId: opts?.targetSessionId,
-        createdAt: new Date().toISOString(),
-        updatedAt: new Date().toISOString(),
-    };
-    queue.push(entry);
-    writeQueue(meshId, queue);
-    return entry;
+    requireMeshHostQueueOwner(opts);
+    return withQueueLock(meshId, () => {
+        const queue = readQueue(meshId);
+        const entry: MeshWorkQueueEntry = {
+            id: randomUUID(),
+            meshId,
+            message,
+            status: 'pending',
+            targetNodeId: opts?.targetNodeId,
+            targetSessionId: opts?.targetSessionId,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+        queue.push(entry);
+        writeQueue(meshId, queue);
+        return entry;
+    });
 }
 
 /**
@@ -106,39 +140,29 @@ export function getQueue(meshId: string, opts?: { status?: MeshTaskStatus[] }):
  * Find the next pending task that this node is allowed to claim, and mark it as assigned.
  */
 export function claimNextTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-
-    // A worker must finish or fail its current queued assignment before it can
-    // claim another one. maxParallelTasks limits total mesh concurrency; it is
-    // not permission for one node/session to accumulate multiple assigned items.
-    const hasActiveAssignment = queue.some(q => q.status === 'assigned' && (
-        q.assignedSessionId === sessionId || q.assignedNodeId === nodeId
-    ));
-    if (hasActiveAssignment) return null;
-    
-    // Find highest priority task:
-    // 1. Pending tasks explicitly targeted at this runtime session
-    // 2. Pending tasks explicitly targeted at this node (but not another session)
-    // 3. Pending tasks with no target node/session
-    let targetIdx = queue.findIndex(q => q.status === 'pending' && q.targetSessionId === sessionId);
-    if (targetIdx === -1) {
-        targetIdx = queue.findIndex(q => q.status === 'pending' && q.targetNodeId === nodeId && !q.targetSessionId);
-    }
-    if (targetIdx === -1) {
-        targetIdx = queue.findIndex(q => q.status === 'pending' && !q.targetNodeId && !q.targetSessionId);
-    }
-
-    if (targetIdx === -1) return null;
-
-    const entry = queue[targetIdx];
-    entry.status = 'assigned';
-    entry.assignedNodeId = nodeId;
-    entry.assignedSessionId = sessionId;
-    entry.dispatchTimestamp = new Date().toISOString();
-    entry.updatedAt = new Date().toISOString();
-
-    writeQueue(meshId, queue);
-    return entry;
+    return withQueueLock(meshId, () => {
+        const queue = readQueue(meshId);
+        const hasActiveAssignment = queue.some(q => q.status === 'assigned' && (
+            q.assignedSessionId === sessionId || q.assignedNodeId === nodeId
+        ));
+        if (hasActiveAssignment) return null;
+        let targetIdx = queue.findIndex(q => q.status === 'pending' && q.targetSessionId === sessionId);
+        if (targetIdx === -1) {
+            targetIdx = queue.findIndex(q => q.status === 'pending' && q.targetNodeId === nodeId && !q.targetSessionId);
+        }
+        if (targetIdx === -1) {
+            targetIdx = queue.findIndex(q => q.status === 'pending' && !q.targetNodeId && !q.targetSessionId);
+        }
+        if (targetIdx === -1) return null;
+        const entry = queue[targetIdx];
+        entry.status = 'assigned';
+        entry.assignedNodeId = nodeId;
+        entry.assignedSessionId = sessionId;
+        entry.dispatchTimestamp = new Date().toISOString();
+        entry.updatedAt = new Date().toISOString();
+        writeQueue(meshId, queue);
+        return entry;
+    });
 }
 
 /**
@@ -149,15 +173,18 @@ export function updateTaskStatus(
     meshId: string,
     taskId: string,
     status: MeshTaskStatus,
+    opts?: MeshQueueMutationOptions,
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    const idx = queue.findIndex(q => q.id === taskId);
-    if (idx === -1) return null;
-
-    queue[idx].status = status;
-    queue[idx].updatedAt = new Date().toISOString();
-    writeQueue(meshId, queue);
-    return queue[idx];
+    requireMeshHostQueueOwner(opts);
+    return withQueueLock(meshId, () => {
+        const queue = readQueue(meshId);
+        const idx = queue.findIndex(q => q.id === taskId);
+        if (idx === -1) return null;
+        queue[idx].status = status;
+        queue[idx].updatedAt = new Date().toISOString();
+        writeQueue(meshId, queue);
+        return queue[idx];
+    });
 }
 
 export function recordTaskAutoLaunch(
@@ -165,17 +192,16 @@ export function recordTaskAutoLaunch(
     taskId: string,
     autoLaunch: Omit<NonNullable<MeshWorkQueueEntry['autoLaunch']>, 'updatedAt'>,
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    const idx = queue.findIndex(q => q.id === taskId);
-    if (idx === -1) return null;
-    const now = new Date().toISOString();
-    queue[idx].autoLaunch = {
-        ...autoLaunch,
-        updatedAt: now,
-    };
-    queue[idx].updatedAt = now;
-    writeQueue(meshId, queue);
-    return queue[idx];
+    return withQueueLock(meshId, () => {
+        const queue = readQueue(meshId);
+        const idx = queue.findIndex(q => q.id === taskId);
+        if (idx === -1) return null;
+        const now = new Date().toISOString();
+        queue[idx].autoLaunch = { ...autoLaunch, updatedAt: now };
+        queue[idx].updatedAt = now;
+        writeQueue(meshId, queue);
+        return queue[idx];
+    });
 }
 
 /**
@@ -184,19 +210,21 @@ export function recordTaskAutoLaunch(
 export function cancelTask(
     meshId: string,
     taskId: string,
-    opts?: { reason?: string },
+    opts?: { reason?: string } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    const idx = queue.findIndex(q => q.id === taskId);
-    if (idx === -1) return null;
-
-    const now = new Date().toISOString();
-    queue[idx].status = 'cancelled';
-    queue[idx].updatedAt = now;
-    queue[idx].cancelledAt = now;
-    if (opts?.reason) queue[idx].cancelReason = opts.reason;
-    writeQueue(meshId, queue);
-    return queue[idx];
+    requireMeshHostQueueOwner(opts);
+    return withQueueLock(meshId, () => {
+        const queue = readQueue(meshId);
+        const idx = queue.findIndex(q => q.id === taskId);
+        if (idx === -1) return null;
+        const now = new Date().toISOString();
+        queue[idx].status = 'cancelled';
+        queue[idx].updatedAt = now;
+        queue[idx].cancelledAt = now;
+        if (opts?.reason) queue[idx].cancelReason = opts.reason;
+        writeQueue(meshId, queue);
+        return queue[idx];
+    });
 }
 
 /**
@@ -212,29 +240,31 @@ export function requeueTask(
         targetSessionId?: string;
         clearTargetNode?: boolean;
         clearTargetSession?: boolean;
-    },
+    } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    const idx = queue.findIndex(q => q.id === taskId);
-    if (idx === -1) return null;
-
-    const entry = queue[idx];
-    const now = new Date().toISOString();
-    entry.status = 'pending';
-    delete entry.assignedNodeId;
-    delete entry.assignedSessionId;
-    delete entry.cancelledAt;
-    delete entry.cancelReason;
-    if (opts?.clearTargetNode) delete entry.targetNodeId;
-    if (typeof opts?.targetNodeId === 'string') entry.targetNodeId = opts.targetNodeId;
-    if (opts?.clearTargetSession !== false) delete entry.targetSessionId;
-    if (typeof opts?.targetSessionId === 'string') entry.targetSessionId = opts.targetSessionId;
-    entry.updatedAt = now;
-    entry.requeuedAt = now;
-    entry.requeueCount = (entry.requeueCount || 0) + 1;
-    if (opts?.reason) entry.requeueReason = opts.reason;
-    writeQueue(meshId, queue);
-    return entry;
+    requireMeshHostQueueOwner(opts);
+    return withQueueLock(meshId, () => {
+        const queue = readQueue(meshId);
+        const idx = queue.findIndex(q => q.id === taskId);
+        if (idx === -1) return null;
+        const entry = queue[idx];
+        const now = new Date().toISOString();
+        entry.status = 'pending';
+        delete entry.assignedNodeId;
+        delete entry.assignedSessionId;
+        delete entry.cancelledAt;
+        delete entry.cancelReason;
+        if (opts?.clearTargetNode) delete entry.targetNodeId;
+        if (typeof opts?.targetNodeId === 'string') entry.targetNodeId = opts.targetNodeId;
+        if (opts?.clearTargetSession !== false) delete entry.targetSessionId;
+        if (typeof opts?.targetSessionId === 'string') entry.targetSessionId = opts.targetSessionId;
+        entry.updatedAt = now;
+        entry.requeuedAt = now;
+        entry.requeueCount = (entry.requeueCount || 0) + 1;
+        if (opts?.reason) entry.requeueReason = opts.reason;
+        writeQueue(meshId, queue);
+        return entry;
+    });
 }
 
 /**
@@ -244,29 +274,26 @@ export function updateSessionTaskStatus(
     meshId: string,
     sessionId: string,
     status: MeshTaskStatus,
+    opts?: { occurredAt?: string },
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    // Collect all assigned tasks for this session, then pick the one with the
-    // most recent dispatchTimestamp (or updatedAt fallback for legacy entries).
-    // This prevents completing the wrong task when multiple tasks were assigned
-    // to the same session in rapid succession.
-    let bestIdx = -1;
-    let bestTime = 0;
-    for (let i = queue.length - 1; i >= 0; i--) {
-        if (queue[i].assignedSessionId === sessionId && queue[i].status === 'assigned') {
+    return withQueueLock(meshId, () => {
+        const queue = readQueue(meshId);
+        const occurredAtTime = opts?.occurredAt ? new Date(opts.occurredAt).getTime() : Number.NaN;
+        const hasOccurredAt = Number.isFinite(occurredAtTime);
+        let bestIdx = -1;
+        let bestTime = 0;
+        for (let i = queue.length - 1; i >= 0; i--) {
+            if (queue[i].assignedSessionId !== sessionId || queue[i].status !== 'assigned') continue;
             const time = new Date(queue[i].dispatchTimestamp || queue[i].updatedAt).getTime();
-            if (time > bestTime) {
-                bestTime = time;
-                bestIdx = i;
-            }
+            if (hasOccurredAt && Number.isFinite(time) && time > occurredAtTime) continue;
+            if (time > bestTime) { bestTime = time; bestIdx = i; }
         }
-    }
-    if (bestIdx === -1) return null;
-
-    queue[bestIdx].status = status;
-    queue[bestIdx].updatedAt = new Date().toISOString();
-    writeQueue(meshId, queue);
-    return queue[bestIdx];
+        if (bestIdx === -1) return null;
+        queue[bestIdx].status = status;
+        queue[bestIdx].updatedAt = new Date().toISOString();
+        writeQueue(meshId, queue);
+        return queue[bestIdx];
+    });
 }
 
 export interface MeshWorkQueueStats {

package/src/mesh/refine-config.ts

@@ -0,0 +1,306 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import * as yaml from 'js-yaml';
+
+export const MESH_REFINE_VALIDATION_CATEGORIES = ['typecheck', 'test', 'lint', 'build'] as const;
+export type MeshRefineValidationCategory = typeof MESH_REFINE_VALIDATION_CATEGORIES[number];
+
+export interface RepoMeshRefineValidationCommandConfig {
+    /** Executable name or a whitespace-tokenized command string. Never executed through a shell. */
+    command: string;
+    /** Optional explicit argv. Prefer this over shell-like command strings. */
+    args?: string[];
+    category?: MeshRefineValidationCategory;
+    cwd?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+}
+
+export interface RepoMeshRefineConfig {
+    version: 1;
+    validation?: {
+        required?: boolean;
+        commands?: RepoMeshRefineValidationCommandConfig[];
+    };
+}
+
+export interface MeshRefineValidationCommandPlan {
+    command: string;
+    args: string[];
+    displayCommand: string;
+    category: MeshRefineValidationCategory | 'custom';
+    source: string;
+    cwd?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+}
+
+export interface MeshRefineConfigLoadResult {
+    config?: RepoMeshRefineConfig;
+    source: string;
+    sourceType: 'mesh_policy' | 'repo_file' | 'unavailable' | 'invalid';
+    path?: string;
+    error?: string;
+}
+
+export interface MeshRefineValidationPlan {
+    source: string;
+    sourceType: MeshRefineConfigLoadResult['sourceType'];
+    commands: MeshRefineValidationCommandPlan[];
+    rejectedCommands: Array<Record<string, unknown>>;
+    suggestions: RepoMeshRefineValidationCommandConfig[];
+    suggestedConfig?: RepoMeshRefineConfig;
+    unavailableReason?: string;
+}
+
+export const MESH_REFINE_CONFIG_LOCATIONS = [
+    '.adhdev/refine.json',
+    '.adhdev/refine.yaml',
+    '.adhdev/refine.yml',
+    '.adhdev/repo-mesh-refine.json',
+    '.adhdev/repo-mesh-refine.yaml',
+    '.adhdev/repo-mesh-refine.yml',
+    'repo-mesh.refine.json',
+    'repo-mesh.refine.yaml',
+    'repo-mesh.refine.yml',
+];
+
+export const MESH_REFINE_CONFIG_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'ADHDev Repo Mesh Refinery Config',
+    type: 'object',
+    additionalProperties: false,
+    required: ['version'],
+    properties: {
+        version: { const: 1 },
+        validation: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                required: { type: 'boolean', default: true },
+                commands: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: 8,
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['command'],
+                        properties: {
+                            command: { type: 'string', minLength: 1 },
+                            args: { type: 'array', items: { type: 'string' } },
+                            category: { enum: [...MESH_REFINE_VALIDATION_CATEGORIES, 'custom'] },
+                            cwd: { type: 'string' },
+                            timeoutMs: { type: 'number', minimum: 1000, maximum: 600000 },
+                            env: { type: 'object', additionalProperties: { type: 'string' } },
+                        },
+                    },
+                },
+            },
+        },
+    },
+} as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function tokenizeCommandString(command: string): string[] | null {
+    const trimmed = command.trim();
+    if (!trimmed) return null;
+    // Explicit config may name any executable, but the Refinery never invokes a shell.
+    // Reject shell syntax, quotes and substitutions so config cannot smuggle a compound command.
+    if (/[;&|<>`$\\\n\r'\"]/.test(trimmed)) return null;
+    const tokens = trimmed.split(/\s+/).filter(Boolean);
+    if (!tokens.length) return null;
+    if (tokens.some(token => !/^[A-Za-z0-9_@./:=+-]+$/.test(token))) return null;
+    return tokens;
+}
+
+function validateCategory(value: unknown): MeshRefineValidationCategory | 'custom' {
+    return typeof value === 'string' && ([...MESH_REFINE_VALIDATION_CATEGORIES, 'custom'] as string[]).includes(value)
+        ? value as MeshRefineValidationCategory | 'custom'
+        : 'custom';
+}
+
+function normalizeCommandConfig(entry: unknown, source: string): { command?: MeshRefineValidationCommandPlan; rejected?: Record<string, unknown> } {
+    if (!isRecord(entry) || typeof entry.command !== 'string') {
+        return { rejected: { source, reason: 'validation command must be an object with a command string' } };
+    }
+
+    const commandText = entry.command.trim();
+    const explicitArgs = Array.isArray(entry.args) ? entry.args : undefined;
+    if (explicitArgs && !explicitArgs.every(arg => typeof arg === 'string')) {
+        return { rejected: { source, command: commandText, reason: 'args must be an array of strings' } };
+    }
+
+    let command = commandText;
+    let args = explicitArgs ? [...explicitArgs] : [];
+    if (!explicitArgs) {
+        const tokens = tokenizeCommandString(commandText);
+        if (!tokens) return { rejected: { source, command: commandText, reason: 'unsafe command string is not allowlisted' } };
+        command = tokens[0];
+        args = tokens.slice(1);
+    } else if (!tokenizeCommandString(command)) {
+        return { rejected: { source, command: commandText, reason: 'unsafe executable name is not allowlisted' } };
+    }
+
+    if (args.some(arg => /[\n\r\0]/.test(arg))) {
+        return { rejected: { source, command: commandText, reason: 'args cannot contain control characters' } };
+    }
+    if (entry.cwd !== undefined && typeof entry.cwd !== 'string') {
+        return { rejected: { source, command: commandText, reason: 'cwd must be a string when provided' } };
+    }
+    if (entry.timeoutMs !== undefined && (typeof entry.timeoutMs !== 'number' || !Number.isFinite(entry.timeoutMs) || entry.timeoutMs < 1000 || entry.timeoutMs > 600000)) {
+        return { rejected: { source, command: commandText, reason: 'timeoutMs must be between 1000 and 600000' } };
+    }
+    if (entry.env !== undefined && (!isRecord(entry.env) || !Object.values(entry.env).every(value => typeof value === 'string'))) {
+        return { rejected: { source, command: commandText, reason: 'env must be an object of string values' } };
+    }
+
+    return {
+        command: {
+            command,
+            args,
+            displayCommand: [command, ...args].join(' '),
+            category: validateCategory(entry.category),
+            source,
+            ...(typeof entry.cwd === 'string' && entry.cwd.trim() ? { cwd: entry.cwd.trim() } : {}),
+            ...(typeof entry.timeoutMs === 'number' ? { timeoutMs: entry.timeoutMs } : {}),
+            ...(isRecord(entry.env) ? { env: entry.env as Record<string, string> } : {}),
+        },
+    };
+}
+
+export function validateMeshRefineConfig(config: unknown, source = 'inline'): { valid: boolean; errors: string[]; commands: MeshRefineValidationCommandPlan[]; rejectedCommands: Array<Record<string, unknown>> } {
+    const errors: string[] = [];
+    const commands: MeshRefineValidationCommandPlan[] = [];
+    const rejectedCommands: Array<Record<string, unknown>> = [];
+
+    if (!isRecord(config)) return { valid: false, errors: ['config must be an object'], commands, rejectedCommands };
+    if (config.version !== 1) errors.push('version must be 1');
+    const validation = config.validation;
+    if (validation !== undefined && !isRecord(validation)) errors.push('validation must be an object');
+    const rawCommands = isRecord(validation) ? validation.commands : undefined;
+    if (rawCommands !== undefined && !Array.isArray(rawCommands)) errors.push('validation.commands must be an array');
+    if (Array.isArray(rawCommands)) {
+        rawCommands.forEach((entry, index) => {
+            const normalized = normalizeCommandConfig(entry, `${source}:validation.commands[${index}]`);
+            if (normalized.command) commands.push(normalized.command);
+            if (normalized.rejected) rejectedCommands.push(normalized.rejected);
+        });
+    }
+    if (rejectedCommands.length) errors.push('one or more validation commands are invalid');
+    return { valid: errors.length === 0, errors, commands, rejectedCommands };
+}
+
+function parseConfigText(path: string, text: string): unknown {
+    if (/\.json$/i.test(path)) return JSON.parse(text);
+    return yaml.load(text);
+}
+
+export function loadMeshRefineConfig(mesh: any, workspace: string): MeshRefineConfigLoadResult {
+    const policy = mesh?.policy && typeof mesh.policy === 'object' && !Array.isArray(mesh.policy) ? mesh.policy : {};
+    const inline = mesh?.refineConfig || (policy as any).refineConfig || (policy as any).refine;
+    if (inline !== undefined) {
+        const validation = validateMeshRefineConfig(inline, 'mesh.policy.refineConfig');
+        if (!validation.valid) return { source: 'mesh.policy.refineConfig', sourceType: 'invalid', error: String(validation.rejectedCommands[0]?.reason || validation.errors.join('; ')) };
+        return { config: inline as RepoMeshRefineConfig, source: 'mesh.policy.refineConfig', sourceType: 'mesh_policy' };
+    }
+
+    for (const relative of MESH_REFINE_CONFIG_LOCATIONS) {
+        const configPath = join(workspace, relative);
+        if (!existsSync(configPath)) continue;
+        try {
+            const parsed = parseConfigText(configPath, readFileSync(configPath, 'utf-8'));
+            const validation = validateMeshRefineConfig(parsed, relative);
+            if (!validation.valid) return { source: relative, sourceType: 'invalid', path: configPath, error: String(validation.rejectedCommands[0]?.reason || validation.errors.join('; ')) };
+            return { config: parsed as RepoMeshRefineConfig, source: relative, sourceType: 'repo_file', path: configPath };
+        } catch (error: any) {
+            return { source: relative, sourceType: 'invalid', path: configPath, error: error?.message || String(error) };
+        }
+    }
+
+    return {
+        source: 'unavailable',
+        sourceType: 'unavailable',
+        error: `No repo mesh/refine config found. Checked: ${MESH_REFINE_CONFIG_LOCATIONS.join(', ')}`,
+    };
+}
+
+function readPackageScripts(workspace: string): Record<string, string> {
+    try {
+        const parsed = JSON.parse(readFileSync(join(workspace, 'package.json'), 'utf-8'));
+        return isRecord(parsed?.scripts) ? parsed.scripts as Record<string, string> : {};
+    } catch {
+        return {};
+    }
+}
+
+function collectProjectContextSuggestions(mesh: any): RepoMeshRefineValidationCommandConfig[] {
+    const commands = mesh?.projectContext?.commands;
+    if (!isRecord(commands)) return [];
+    const suggestions: RepoMeshRefineValidationCommandConfig[] = [];
+    for (const category of MESH_REFINE_VALIDATION_CATEGORIES) {
+        const entries = Array.isArray(commands[category]) ? commands[category] : [];
+        for (const entry of entries) {
+            if (isRecord(entry) && typeof entry.command === 'string') suggestions.push({ command: entry.command, category });
+        }
+    }
+    return suggestions;
+}
+
+function collectPackageScriptSuggestions(workspace: string): RepoMeshRefineValidationCommandConfig[] {
+    const scripts = readPackageScripts(workspace);
+    const suggestions: RepoMeshRefineValidationCommandConfig[] = [];
+    for (const category of MESH_REFINE_VALIDATION_CATEGORIES) {
+        for (const scriptName of Object.keys(scripts)) {
+            if (scriptName === category || scriptName.startsWith(`${category}:`)) {
+                suggestions.push({ command: 'npm', args: ['run', scriptName], category });
+            }
+        }
+    }
+    return suggestions;
+}
+
+export function suggestMeshRefineConfig(mesh: any, workspace: string): { suggestions: RepoMeshRefineValidationCommandConfig[]; suggestedConfig?: RepoMeshRefineConfig } {
+    const seen = new Set<string>();
+    const suggestions: RepoMeshRefineValidationCommandConfig[] = [];
+    for (const entry of [...collectProjectContextSuggestions(mesh), ...collectPackageScriptSuggestions(workspace)]) {
+        const key = `${entry.command} ${(entry.args || []).join(' ')}`.trim();
+        if (seen.has(key)) continue;
+        seen.add(key);
+        suggestions.push(entry);
+    }
+    return {
+        suggestions,
+        suggestedConfig: suggestions.length ? { version: 1, validation: { required: true, commands: suggestions.slice(0, 4) } } : undefined,
+    };
+}
+
+export function resolveMeshRefineValidationPlan(mesh: any, workspace: string): MeshRefineValidationPlan {
+    const loaded = loadMeshRefineConfig(mesh, workspace);
+    const suggestion = suggestMeshRefineConfig(mesh, workspace);
+    if (!loaded.config) {
+        return {
+            source: loaded.source,
+            sourceType: loaded.sourceType,
+            commands: [],
+            rejectedCommands: loaded.error ? [{ source: loaded.source, reason: loaded.error }] : [],
+            suggestions: suggestion.suggestions,
+            suggestedConfig: suggestion.suggestedConfig,
+            unavailableReason: loaded.error || 'validation_unavailable: repo mesh/refine config missing',
+        };
+    }
+
+    const validation = validateMeshRefineConfig(loaded.config, loaded.source);
+    return {
+        source: loaded.path || loaded.source,
+        sourceType: loaded.sourceType,
+        commands: validation.commands,
+        rejectedCommands: validation.rejectedCommands,
+        suggestions: suggestion.suggestions,
+        suggestedConfig: suggestion.suggestedConfig,
+        unavailableReason: validation.commands.length ? undefined : 'validation_unavailable: repo mesh/refine config has no validation.commands',
+    };
+}

package/src/providers/chat-message-normalization.ts

@@ -1,9 +1,11 @@
 import type { ChatMessage } from '../types.js';
 import { flattenContent } from './contracts.js';
 
+export const DEFAULT_FINAL_SUMMARY_MAX_CHARS = 4_000;
+
 export function extractFinalSummaryFromMessages(
   messages: ChatMessage[] | null | undefined,
-  maxChars: number = 500,
+  maxChars: number = DEFAULT_FINAL_SUMMARY_MAX_CHARS,
 ): string {
   if (!Array.isArray(messages) || messages.length === 0) return '';