@adhdev/daemon-core 0.9.82-rc.209 → 0.9.82-rc.210

package/src/mesh/mesh-task-stats.ts

@@ -0,0 +1,154 @@
+/**
+ * M7: Operational stats (time/attempts) derived from existing truth.
+ *
+ * No cost/token accounting — ADHDev observes PTY/CDP and cannot see API
+ * tokens (explicit non-goal). Everything here is derived at query time from
+ * the SQLite ledger and queue rows; there is no separate aggregate table.
+ * Tasks with missing ledger evidence report incompleteEvidence instead of
+ * estimated numbers.
+ */
+
+import { readLedgerEntries } from './mesh-ledger.js';
+import type { MeshLedgerEntry } from './mesh-ledger.js';
+import { getQueue } from './mesh-work-queue.js';
+
+export interface MeshTaskStats {
+    taskId: string;
+    status: string;
+    dispatchedAt: string | null;
+    terminalAt: string | null;
+    terminalKind: 'task_completed' | 'task_failed' | null;
+    /** dispatched → terminal wall clock; null when evidence is incomplete. */
+    durationMs: number | null;
+    /** Number of task_dispatched ledger entries observed for this task. */
+    dispatchCount: number;
+    /** Queue requeueCount (0 when the row is gone or never requeued). */
+    requeueCount: number;
+    /** True when dispatch or terminal ledger evidence is missing — numbers are withheld, never estimated. */
+    incompleteEvidence?: true;
+}
+
+export interface MeshMissionStats {
+    missionId: string;
+    taskCount: number;
+    completed: number;
+    failed: number;
+    /** Sum of per-task durations with complete evidence. */
+    totalDurationMs: number;
+    /** First dispatch → last terminal across the mission's tasks; null without complete endpoints. */
+    wallClockMs: number | null;
+    /** Total requeue attempts across the mission's tasks. */
+    retries: number;
+    /** Task ids whose ledger evidence was incomplete (excluded from sums). */
+    incompleteTaskIds: string[];
+}
+
+function readPayloadTaskId(entry: MeshLedgerEntry): string {
+    const value = entry.payload?.taskId;
+    return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function parseTime(value: string | null | undefined): number | null {
+    if (!value) return null;
+    const parsed = new Date(value).getTime();
+    return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * Compute per-task stats from ledger entries. Scans a bounded tail window —
+ * stats are an operational view of recent work, not a full historical report.
+ */
+export function computeMeshTaskStats(meshId: string, opts?: { taskIds?: string[]; missionId?: string; tail?: number }): MeshTaskStats[] {
+    const queue = getQueue(meshId);
+    const queueById = new Map(queue.map(task => [task.id, task]));
+
+    let targetIds: string[];
+    if (opts?.taskIds?.length) {
+        targetIds = [...new Set(opts.taskIds)];
+    } else if (opts?.missionId) {
+        targetIds = queue.filter(task => task.missionId === opts.missionId).map(task => task.id);
+    } else {
+        targetIds = queue.map(task => task.id);
+    }
+    if (targetIds.length === 0) return [];
+    const targetSet = new Set(targetIds);
+
+    const entries = readLedgerEntries(meshId, { tail: opts?.tail ?? 1000 });
+    const dispatches = new Map<string, { first: string; count: number }>();
+    const terminals = new Map<string, { at: string; kind: 'task_completed' | 'task_failed' }>();
+    for (const entry of entries) {
+        const taskId = readPayloadTaskId(entry);
+        if (!taskId || !targetSet.has(taskId)) continue;
+        if (entry.kind === 'task_dispatched') {
+            const existing = dispatches.get(taskId);
+            if (existing) existing.count += 1;
+            else dispatches.set(taskId, { first: entry.timestamp, count: 1 });
+        } else if (entry.kind === 'task_completed' || entry.kind === 'task_failed') {
+            // Last terminal wins (requeued tasks can have multiple terminals).
+            terminals.set(taskId, { at: entry.timestamp, kind: entry.kind });
+        }
+    }
+
+    return targetIds.map(taskId => {
+        const queueEntry = queueById.get(taskId);
+        const status = queueEntry?.status ?? 'unknown';
+        const dispatch = dispatches.get(taskId);
+        const terminal = terminals.get(taskId);
+        const isTerminalStatus = status === 'completed' || status === 'failed' || status === 'cancelled';
+        const dispatchTime = parseTime(dispatch?.first ?? queueEntry?.dispatchTimestamp);
+        const terminalTime = parseTime(terminal?.at);
+        const stats: MeshTaskStats = {
+            taskId,
+            status,
+            dispatchedAt: dispatch?.first ?? queueEntry?.dispatchTimestamp ?? null,
+            terminalAt: terminal?.at ?? null,
+            terminalKind: terminal?.kind ?? null,
+            durationMs: null,
+            dispatchCount: dispatch?.count ?? 0,
+            requeueCount: queueEntry?.requeueCount ?? 0,
+        };
+        if (dispatchTime !== null && terminalTime !== null && terminalTime >= dispatchTime) {
+            stats.durationMs = terminalTime - dispatchTime;
+        } else if (isTerminalStatus) {
+            // Terminal task without complete dispatch+terminal ledger evidence:
+            // withhold numbers rather than estimate (M7 rule).
+            stats.incompleteEvidence = true;
+        }
+        return stats;
+    });
+}
+
+/** Mission rollup — derived from per-task stats, no stored aggregates. */
+export function computeMeshMissionStats(meshId: string, missionId: string): MeshMissionStats {
+    const tasks = computeMeshTaskStats(meshId, { missionId });
+    const stats: MeshMissionStats = {
+        missionId,
+        taskCount: tasks.length,
+        completed: 0,
+        failed: 0,
+        totalDurationMs: 0,
+        wallClockMs: null,
+        retries: 0,
+        incompleteTaskIds: [],
+    };
+    let firstDispatch: number | null = null;
+    let lastTerminal: number | null = null;
+    for (const task of tasks) {
+        if (task.status === 'completed') stats.completed += 1;
+        else if (task.status === 'failed') stats.failed += 1;
+        stats.retries += task.requeueCount;
+        if (task.incompleteEvidence) {
+            stats.incompleteTaskIds.push(task.taskId);
+            continue;
+        }
+        if (task.durationMs !== null) stats.totalDurationMs += task.durationMs;
+        const dispatchTime = parseTime(task.dispatchedAt);
+        const terminalTime = parseTime(task.terminalAt);
+        if (dispatchTime !== null && (firstDispatch === null || dispatchTime < firstDispatch)) firstDispatch = dispatchTime;
+        if (terminalTime !== null && (lastTerminal === null || terminalTime > lastTerminal)) lastTerminal = terminalTime;
+    }
+    if (firstDispatch !== null && lastTerminal !== null && lastTerminal >= firstDispatch) {
+        stats.wallClockMs = lastTerminal - firstDispatch;
+    }
+    return stats;
+}

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

@@ -2,6 +2,7 @@ import { randomUUID } from 'crypto';
 import { requireMeshHostQueueOwner } from './mesh-host-ownership.js';
 import type { RepoMeshDaemonRole } from '../repo-mesh-types.js';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
+import { getMesh } from '../config/mesh-config.js';
 
 export type MeshTaskStatus = 'pending' | 'assigned' | 'completed' | 'failed' | 'cancelled';
 export type MeshActiveTaskStatus = Extract<MeshTaskStatus, 'pending' | 'assigned'>;
@@ -71,6 +72,20 @@ export interface MeshWorkQueueEntry {
     targetSessionId?: string;
     /** If specified, a node must expose all tags before it can claim the task. */
     requiredTags?: string[];
+    /**
+     * M1: ids of tasks that must reach 'completed' before this task is claimable.
+     * Forward references (ids not yet enqueued) are allowed for batch flows and
+     * simply keep the task waiting until the referenced task exists and completes.
+     */
+    dependsOn?: string[];
+    /** M1/M3: mission this task belongs to (joins mesh_missions). */
+    missionId?: string;
+    /**
+     * M1: why this task is held back (e.g. "dependency_failed:<taskId>").
+     * Only set by the system on dependency failure under the 'block' policy;
+     * waiting-on-dependency state is computed at view time, not stored.
+     */
+    blockedReason?: string;
     /** The node that actually claimed and is executing the task */
     assignedNodeId?: string;
     /** The session currently executing the task */
@@ -82,6 +97,8 @@ export interface MeshWorkQueueEntry {
     requeueReason?: string;
     requeuedAt?: string;
     requeueCount?: number;
+    /** Max automatic requeue attempts. When requeueCount reaches this, task is auto-failed. */
+    maxRetries?: number;
     /** Last automatic queue session spin-up attempt, for mesh_view_queue/debug visibility. */
     autoLaunch?: {
         status: 'skipped' | 'started' | 'failed' | 'completed';
@@ -123,17 +140,24 @@ function firstProviderPriority(policy: unknown): string | undefined {
 }
 
 export function buildMeshNodeCapabilityTags(
-    node: { capabilities?: unknown; policy?: unknown } | undefined,
+    node: { capabilities?: unknown; policy?: unknown; isLocalWorktree?: unknown; worktreeBranch?: unknown } | undefined,
     providerType?: string,
 ): string[] {
     const provider = typeof providerType === 'string' && providerType.trim()
         ? providerType.trim()
         : firstProviderPriority(node?.policy);
+    const worktreeBranch = typeof node?.worktreeBranch === 'string' && node.worktreeBranch.trim()
+        ? node.worktreeBranch.trim()
+        : null;
     return normalizeMeshCapabilityTags([
         ...(Array.isArray(node?.capabilities) ? node.capabilities : []),
         `os=${process.platform}`,
         `arch=${process.arch}`,
         ...(provider ? [`provider=${provider}`] : []),
+        // Worktree nodes automatically expose a "worktree=<branch>" tag so that
+        // mesh_enqueue_task with required_tags: ["worktree=<branch>"] routes
+        // only to the matching worktree node.
+        ...(node?.isLocalWorktree === true && worktreeBranch ? [`worktree=${worktreeBranch}`] : []),
     ]);
 }
 
@@ -156,33 +180,96 @@ function writeQueue(meshId: string, queue: MeshWorkQueueEntry[]): void {
     MeshRuntimeStore.getInstance().replaceQueue(meshId, queue);
 }
 
+function normalizeDependsOn(value: unknown): string[] {
+    if (!Array.isArray(value)) return [];
+    const seen = new Set<string>();
+    return value
+        .map(id => typeof id === 'string' ? id.trim() : '')
+        .filter(Boolean)
+        .filter(id => {
+            if (seen.has(id)) return false;
+            seen.add(id);
+            return true;
+        });
+}
+
+/**
+ * M1: detect dependency cycles before enqueue. Walks the dependency graph of
+ * existing queue entries plus the new task's edges. Fail-closed: a cycle
+ * rejects the enqueue entirely. Synchronous and bounded by queue size.
+ */
+export function assertNoDependencyCycle(meshId: string, newTaskId: string, dependsOn: string[]): void {
+    if (dependsOn.length === 0) return;
+    if (dependsOn.includes(newTaskId)) {
+        throw new Error(`dependency_cycle_detected: task '${newTaskId}' cannot depend on itself`);
+    }
+    const adjacency = new Map<string, string[]>();
+    for (const entry of readQueue(meshId)) {
+        adjacency.set(entry.id, normalizeDependsOn(entry.dependsOn));
+    }
+    adjacency.set(newTaskId, dependsOn);
+    // DFS from the new task: if we can reach newTaskId again, the edges form a cycle.
+    const stack = [...dependsOn];
+    const visited = new Set<string>();
+    while (stack.length > 0) {
+        const current = stack.pop()!;
+        if (current === newTaskId) {
+            throw new Error(`dependency_cycle_detected: task '${newTaskId}' is part of a dependency cycle via '${dependsOn.join(', ')}'`);
+        }
+        if (visited.has(current)) continue;
+        visited.add(current);
+        stack.push(...(adjacency.get(current) ?? []));
+    }
+}
+
 /**
  * Add a new task to the mesh queue.
  */
 export function enqueueTask(
     meshId: string,
     message: string,
-    opts?: { targetNodeId?: string; targetSessionId?: string; taskMode?: MeshTaskMode | string; requiredTags?: string[] } & MeshQueueMutationOptions,
+    opts?: {
+        targetNodeId?: string;
+        targetSessionId?: string;
+        taskMode?: MeshTaskMode | string;
+        requiredTags?: string[];
+        /** M1: tasks that must complete before this one is claimable. */
+        dependsOn?: string[];
+        /** M1/M3: mission this task belongs to. */
+        missionId?: string;
+        /** Explicit task id for batch/template flows (M5). Random UUID when omitted. */
+        id?: string;
+    } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry {
     requireMeshHostQueueOwner(opts);
     const modeValidation = validateMeshTaskModeRequest(opts?.taskMode, message);
     if (!modeValidation.valid) {
         throw new Error(`live_debug_readonly_guardrail_violation: forbidden operations (${modeValidation.violations.join(', ')})`);
     }
-    const entry: MeshWorkQueueEntry = {
-        id: randomUUID(),
-        meshId,
-        message,
-        status: 'pending',
-        taskMode: modeValidation.taskMode,
-        targetNodeId: opts?.targetNodeId,
-        targetSessionId: opts?.targetSessionId,
-        requiredTags: normalizeMeshCapabilityTags(opts?.requiredTags),
-        createdAt: new Date().toISOString(),
-        updatedAt: new Date().toISOString(),
-    };
-    MeshRuntimeStore.getInstance().insertQueueEntry(entry);
-    return entry;
+    const id = typeof opts?.id === 'string' && opts.id.trim() ? opts.id.trim() : randomUUID();
+    const dependsOn = normalizeDependsOn(opts?.dependsOn);
+    return withQueueLock(meshId, () => {
+        if (MeshRuntimeStore.getInstance().findQueueEntryById(meshId, id)) {
+            throw new Error(`duplicate_task_id: task '${id}' already exists in mesh '${meshId}'`);
+        }
+        assertNoDependencyCycle(meshId, id, dependsOn);
+        const entry: MeshWorkQueueEntry = {
+            id,
+            meshId,
+            message,
+            status: 'pending',
+            taskMode: modeValidation.taskMode,
+            targetNodeId: opts?.targetNodeId,
+            targetSessionId: opts?.targetSessionId,
+            requiredTags: normalizeMeshCapabilityTags(opts?.requiredTags),
+            ...(dependsOn.length > 0 ? { dependsOn } : {}),
+            ...(typeof opts?.missionId === 'string' && opts.missionId.trim() ? { missionId: opts.missionId.trim() } : {}),
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+        MeshRuntimeStore.getInstance().insertQueueEntry(entry);
+        return entry;
+    });
 }
 
 /**
@@ -203,6 +290,57 @@ export function claimNextTask(meshId: string, nodeId: string, sessionId: string,
     return MeshRuntimeStore.getInstance().claimNextQueueTask(meshId, nodeId, sessionId, capabilityTags);
 }
 
+// ─── M1: Dependency Failure Propagation ─────────
+
+export type DependencyFailurePolicy = 'block' | 'cancel';
+
+function resolveDependencyFailurePolicy(meshId: string): DependencyFailurePolicy {
+    try {
+        const policy = (getMesh(meshId)?.policy ?? {}) as Record<string, unknown>;
+        return policy.onDependencyFailure === 'cancel' ? 'cancel' : 'block';
+    } catch {
+        return 'block';
+    }
+}
+
+/**
+ * Apply the mesh's onDependencyFailure policy to pending dependents of a task
+ * that just reached a failed/cancelled terminal state.
+ *
+ * - 'block' (default): dependents stay pending with blockedReason
+ *   "dependency_failed:<taskId>" so an operator can requeue/cancel them.
+ * - 'cancel': dependents are cancelled (cascading to their own dependents).
+ *
+ * Must be called inside the queue lock of the triggering transition.
+ */
+function propagateDependencyFailure(meshId: string, failedTaskId: string): void {
+    const policy = resolveDependencyFailurePolicy(meshId);
+    const store = MeshRuntimeStore.getInstance();
+    const frontier = [failedTaskId];
+    const seen = new Set<string>(frontier);
+    while (frontier.length > 0) {
+        const currentId = frontier.pop()!;
+        const dependents = store.getQueueEntries(meshId, ['pending'])
+            .filter(entry => Array.isArray(entry.dependsOn) && entry.dependsOn.includes(currentId));
+        for (const dependent of dependents) {
+            if (seen.has(dependent.id)) continue;
+            seen.add(dependent.id);
+            if (policy === 'cancel') {
+                dependent.status = 'cancelled';
+                dependent.cancelledAt = new Date().toISOString();
+                dependent.cancelReason = `dependency_failed:${currentId}`;
+                store.updateQueueEntry(dependent);
+                frontier.push(dependent.id); // cascade to transitive dependents
+            } else {
+                dependent.blockedReason = `dependency_failed:${currentId}`;
+                store.updateQueueEntry(dependent);
+            }
+        }
+    }
+}
+
+const DEPENDENCY_FAILURE_TERMINALS = new Set<MeshTaskStatus>(['failed', 'cancelled']);
+
 /**
  * Update the status of a specific task.
  * Used when a session completes, fails, or stalls.
@@ -219,6 +357,7 @@ export function updateTaskStatus(
         if (!entry) return null;
         entry.status = status;
         MeshRuntimeStore.getInstance().updateQueueEntry(entry);
+        if (DEPENDENCY_FAILURE_TERMINALS.has(status)) propagateDependencyFailure(meshId, taskId);
         return entry;
     });
 }
@@ -255,6 +394,7 @@ export function cancelTask(
         entry.cancelledAt = now;
         if (opts?.reason) entry.cancelReason = opts.reason;
         MeshRuntimeStore.getInstance().updateQueueEntry(entry);
+        propagateDependencyFailure(meshId, taskId);
         return entry;
     });
 }
@@ -263,6 +403,11 @@ export function cancelTask(
  * Return a queue task to pending for retry. By default, dead session targeting
  * and assigned ownership are cleared so stale assignments do not strand again.
  */
+export type RequeueResult =
+    | { status: 'requeued'; entry: MeshWorkQueueEntry }
+    | { status: 'failed_max_retries'; entry: MeshWorkQueueEntry; maxRetries: number; requeueCount: number }
+    | { status: 'not_found' };
+
 export function requeueTask(
     meshId: string,
     taskId: string,
@@ -272,13 +417,34 @@ export function requeueTask(
         targetSessionId?: string;
         clearTargetNode?: boolean;
         clearTargetSession?: boolean;
+        /**
+         * Override the retry cap for this call. Use only for explicit operator actions.
+         * If true, the task is requeued even when requeueCount >= maxRetries.
+         */
+        force?: boolean;
+        /** Per-task retry cap override. Falls back to mesh policy maxTaskRetries (default 1). */
+        maxRetries?: number;
     } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry | null {
     requireMeshHostQueueOwner(opts);
     return withQueueLock(meshId, () => {
         const entry = MeshRuntimeStore.getInstance().findQueueEntryById(meshId, taskId);
         if (!entry) return null;
+        const currentCount = entry.requeueCount || 0;
+        const maxRetries = opts?.maxRetries ?? entry.maxRetries ?? 1;
+        if (!opts?.force && currentCount >= maxRetries) {
+            // Auto-fail: cap exceeded without explicit force override.
+            entry.status = 'failed';
+            entry.cancelReason = `max_retries_exceeded: requeued ${currentCount} time(s), limit is ${maxRetries}`;
+            entry.updatedAt = new Date().toISOString();
+            MeshRuntimeStore.getInstance().updateQueueEntry(entry);
+            propagateDependencyFailure(meshId, taskId);
+            return entry;
+        }
         entry.status = 'pending';
+        // Operator requeue clears a dependency-failure block — the operator is
+        // explicitly overriding the held-back state.
+        delete entry.blockedReason;
         delete entry.assignedNodeId;
         delete entry.assignedSessionId;
         delete entry.cancelledAt;
@@ -288,7 +454,7 @@ export function requeueTask(
         if (opts?.clearTargetSession !== false) delete entry.targetSessionId;
         if (typeof opts?.targetSessionId === 'string') entry.targetSessionId = opts.targetSessionId;
         entry.requeuedAt = new Date().toISOString();
-        entry.requeueCount = (entry.requeueCount || 0) + 1;
+        entry.requeueCount = currentCount + 1;
         if (opts?.reason) entry.requeueReason = opts.reason;
         MeshRuntimeStore.getInstance().updateQueueEntry(entry);
         return entry;
@@ -310,10 +476,37 @@ export function updateSessionTaskStatus(
         if (!entry) return null;
         entry.status = status;
         MeshRuntimeStore.getInstance().updateQueueEntry(entry);
+        if (DEPENDENCY_FAILURE_TERMINALS.has(status)) propagateDependencyFailure(meshId, entry.id);
         return entry;
     });
 }
 
+/**
+ * M1-3: true when at least one pending task is waiting on the given task.
+ * Used by the completion event path to decide whether to wake the queue.
+ */
+export function hasPendingDependents(meshId: string, taskId: string): boolean {
+    return MeshRuntimeStore.getInstance().getQueueEntries(meshId, ['pending'])
+        .some(entry => Array.isArray(entry.dependsOn) && entry.dependsOn.includes(taskId));
+}
+
+/**
+ * M1-4: view-time dependency state for a task — unmet dependency ids and
+ * whether the task is currently claimable from a dependency standpoint.
+ * Not stored (truth stays in task statuses).
+ */
+export function describeTaskDependencyState(
+    entry: Pick<MeshWorkQueueEntry, 'dependsOn' | 'blockedReason'>,
+    statusById: Map<string, MeshTaskStatus | string>,
+): { waitingOn: string[]; dependenciesSatisfied: boolean } {
+    const deps = Array.isArray(entry.dependsOn) ? entry.dependsOn : [];
+    const waitingOn = deps.filter(depId => statusById.get(depId) !== 'completed');
+    return {
+        waitingOn,
+        dependenciesSatisfied: waitingOn.length === 0 && !entry.blockedReason,
+    };
+}
+
 export interface MeshWorkQueueStats {
     total: number;
     active: number;
@@ -436,3 +629,26 @@ export function markStaleDirectDispatches(meshId: string, olderThanMs = 60 * 60_
         MeshRuntimeStore.getInstance().markStaleDirectDispatches(meshId, olderThanMs);
     } catch { /* best-effort */ }
 }
+
+export type MeshToolCallRateResult = { rateLimitExceeded: boolean; callsInWindow: number; advisory: string | null };
+
+/**
+ * Record a coordinator tool call and return a rate-limit advisory when the
+ * call rate for that tool exceeds the allowed threshold.
+ *
+ * Defaults: 10-second sliding window, max 5 calls before advisory is raised.
+ * Returns { rateLimitExceeded: false } on any store error so callers are not blocked.
+ */
+export function recordMeshToolCall(opts: {
+    meshId: string;
+    tool: string;
+    sessionId?: string | null;
+    windowMs?: number;
+    maxCalls?: number;
+}): MeshToolCallRateResult {
+    try {
+        return MeshRuntimeStore.getInstance().recordMeshToolCall(opts);
+    } catch {
+        return { rateLimitExceeded: false, callsInWindow: 0, advisory: null };
+    }
+}

package/src/mesh/refine-config.ts

@@ -29,8 +29,18 @@ export interface RepoMeshRefineConfig {
     validation?: {
         required?: boolean;
         /**
-         * Optional dependency/bootstrap commands that Refinery runs before
-         * validation commands. Refinery never infers installs on its own.
+         * M2-2 (v2): how Refinery sources its bootstrap stage.
+         *   'inherit' (default) — consume the worktree_bootstrap config/state:
+         *     skip when the node's bootstrap is 'ready' (staleInputs unchanged),
+         *     run the worktree_bootstrap definition when stale/never-ran.
+         *   'skip' — no bootstrap stage at all (validation commands run as-is).
+         */
+        bootstrap?: 'inherit' | 'skip';
+        /**
+         * DEPRECATED (M2-2): define bootstrap once in
+         * .adhdev/worktree_bootstrap.json instead. Still honored when no
+         * worktree_bootstrap config exists, with a deprecation warning; when
+         * both exist the worktree_bootstrap config wins.
          */
         bootstrapCommands?: RepoMeshRefineValidationCommandConfig[];
         commands?: RepoMeshRefineValidationCommandConfig[];
@@ -60,9 +70,13 @@ export interface MeshRefineConfigLoadResult {
 export interface MeshRefineValidationPlan {
     source: string;
     sourceType: MeshRefineConfigLoadResult['sourceType'];
+    /** M2-2: how the bootstrap stage is sourced ('inherit' consumes worktree_bootstrap; 'skip' disables it). */
+    bootstrapMode: 'inherit' | 'skip';
     bootstrapCommands: MeshRefineValidationCommandPlan[];
     commands: MeshRefineValidationCommandPlan[];
     rejectedCommands: Array<Record<string, unknown>>;
+    /** M2-2: deprecation notices (e.g. validation.bootstrapCommands present). */
+    deprecationWarnings: string[];
     suggestions: RepoMeshRefineValidationCommandConfig[];
     suggestedConfig?: RepoMeshRefineConfig;
     unavailableReason?: string;
@@ -98,6 +112,11 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
             additionalProperties: false,
             properties: {
                 required: { type: 'boolean', default: true },
+                bootstrap: {
+                    enum: ['inherit', 'skip'],
+                    default: 'inherit',
+                    description: "M2-2 (v2): 'inherit' consumes the worktree_bootstrap config/state (skip when ready, rerun when stale); 'skip' disables the bootstrap stage entirely.",
+                },
                 commands: {
                     type: 'array',
                     minItems: 1,
@@ -120,6 +139,7 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
                 bootstrapCommands: {
                     type: 'array',
                     maxItems: 4,
+                    description: 'DEPRECATED: define bootstrap once in .adhdev/worktree_bootstrap.json. Honored only when no worktree_bootstrap config exists (with a deprecation warning); worktree_bootstrap wins when both exist.',
                     items: {
                         type: 'object',
                         additionalProperties: false,
@@ -217,23 +237,36 @@ export function normalizeMeshCommandConfig(entry: unknown, source: string): { co
 
 const isRecord = isMeshConfigRecord;
 
-export function validateMeshRefineConfig(config: unknown, source = 'inline'): { valid: boolean; errors: string[]; bootstrapCommands: MeshRefineValidationCommandPlan[]; commands: MeshRefineValidationCommandPlan[]; rejectedCommands: Array<Record<string, unknown>> } {
+export function validateMeshRefineConfig(config: unknown, source = 'inline'): { valid: boolean; errors: string[]; bootstrapCommands: MeshRefineValidationCommandPlan[]; commands: MeshRefineValidationCommandPlan[]; rejectedCommands: Array<Record<string, unknown>>; bootstrapMode: 'inherit' | 'skip'; deprecationWarnings: string[] } {
     const errors: string[] = [];
     const bootstrapCommands: MeshRefineValidationCommandPlan[] = [];
     const commands: MeshRefineValidationCommandPlan[] = [];
     const rejectedCommands: Array<Record<string, unknown>> = [];
+    const deprecationWarnings: string[] = [];
+    let bootstrapMode: 'inherit' | 'skip' = 'inherit';
 
-    if (!isRecord(config)) return { valid: false, errors: ['config must be an object'], bootstrapCommands, commands, rejectedCommands };
+    if (!isRecord(config)) return { valid: false, errors: ['config must be an object'], bootstrapCommands, commands, rejectedCommands, bootstrapMode, deprecationWarnings };
     if (config.version !== 1) errors.push('version must be 1');
     if (config.allowAutoPublishSubmoduleMainCommits !== undefined && typeof config.allowAutoPublishSubmoduleMainCommits !== 'boolean') {
         errors.push('allowAutoPublishSubmoduleMainCommits must be a boolean when provided');
     }
     const validation = config.validation;
     if (validation !== undefined && !isRecord(validation)) errors.push('validation must be an object');
+    const rawBootstrapMode = isRecord(validation) ? validation.bootstrap : undefined;
+    if (rawBootstrapMode !== undefined) {
+        if (rawBootstrapMode === 'inherit' || rawBootstrapMode === 'skip') {
+            bootstrapMode = rawBootstrapMode;
+        } else {
+            errors.push("validation.bootstrap must be 'inherit' or 'skip' when provided");
+        }
+    }
     const rawCommands = isRecord(validation) ? validation.commands : undefined;
     const rawBootstrapCommands = isRecord(validation) ? validation.bootstrapCommands : undefined;
     if (rawCommands !== undefined && !Array.isArray(rawCommands)) errors.push('validation.commands must be an array');
     if (rawBootstrapCommands !== undefined && !Array.isArray(rawBootstrapCommands)) errors.push('validation.bootstrapCommands must be an array');
+    if (Array.isArray(rawBootstrapCommands) && rawBootstrapCommands.length > 0) {
+        deprecationWarnings.push('validation.bootstrapCommands is deprecated: define bootstrap once in .adhdev/worktree_bootstrap.json. It still runs when no worktree_bootstrap config exists; when both exist the worktree_bootstrap config wins.');
+    }
     if (Array.isArray(rawBootstrapCommands)) {
         rawBootstrapCommands.forEach((entry, index) => {
             const normalized = normalizeMeshCommandConfig(entry, `${source}:validation.bootstrapCommands[${index}]`);
@@ -249,7 +282,7 @@ export function validateMeshRefineConfig(config: unknown, source = 'inline'): {
         });
     }
     if (rejectedCommands.length) errors.push('one or more validation commands are invalid');
-    return { valid: errors.length === 0, errors, bootstrapCommands, commands, rejectedCommands };
+    return { valid: errors.length === 0, errors, bootstrapCommands, commands, rejectedCommands, bootstrapMode, deprecationWarnings };
 }
 
 function parseConfigText(path: string, text: string): unknown {
@@ -343,9 +376,11 @@ export function resolveMeshRefineValidationPlan(mesh: any, workspace: string): M
         return {
             source: loaded.source,
             sourceType: loaded.sourceType,
+            bootstrapMode: 'inherit',
             bootstrapCommands: [],
             commands: [],
             rejectedCommands: loaded.error ? [{ source: loaded.source, reason: loaded.error }] : [],
+            deprecationWarnings: [],
             suggestions: suggestion.suggestions,
             suggestedConfig: suggestion.suggestedConfig,
             unavailableReason: loaded.error || 'validation_unavailable: repo mesh/refine config missing',
@@ -356,9 +391,11 @@ export function resolveMeshRefineValidationPlan(mesh: any, workspace: string): M
     return {
         source: loaded.path || loaded.source,
         sourceType: loaded.sourceType,
+        bootstrapMode: validation.bootstrapMode,
         bootstrapCommands: validation.bootstrapCommands,
         commands: validation.commands,
         rejectedCommands: validation.rejectedCommands,
+        deprecationWarnings: validation.deprecationWarnings,
         suggestions: suggestion.suggestions,
         suggestedConfig: suggestion.suggestedConfig,
         unavailableReason: validation.commands.length ? undefined : 'validation_unavailable: repo mesh/refine config has no validation.commands',