@adhdev/daemon-core 0.9.82-rc.113 → 0.9.82-rc.115

package/src/mesh/mesh-refine-status.ts

@@ -0,0 +1,145 @@
+import type { MeshLedgerEntry } from './mesh-ledger.js';
+import type { PendingMeshCoordinatorEvent } from './mesh-events.js';
+
+export type MeshAsyncRefineJobStatus = 'accepted' | 'running' | 'completed' | 'failed';
+
+export interface MeshAsyncRefineJobSummary {
+    jobId: string;
+    interactionId?: string;
+    status: MeshAsyncRefineJobStatus;
+    meshId?: string;
+    nodeId?: string;
+    targetNodeId?: string;
+    targetDaemonId?: string;
+    workspace?: string;
+    branch?: string;
+    into?: string;
+    startedAt?: string;
+    completedAt?: string;
+    retryOfJobId?: string;
+    lastEvent?: string;
+    lastLedgerKind?: string;
+    lastUpdatedAt?: string;
+    instruction: string;
+}
+
+function readString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value as Record<string, unknown>
+        : undefined;
+}
+
+function eventStatus(event: string | undefined, fallback?: string): MeshAsyncRefineJobStatus | undefined {
+    if (event === 'refine:accepted') return 'accepted';
+    if (event === 'refine:completed') return 'completed';
+    if (event === 'refine:failed') return 'failed';
+    if (fallback === 'completed' || fallback === 'failed' || fallback === 'accepted') return fallback;
+    return undefined;
+}
+
+function ledgerStatus(kind: string, fallback?: string): MeshAsyncRefineJobStatus {
+    if (kind === 'task_completed') return 'completed';
+    if (kind === 'task_failed') return 'failed';
+    if (fallback === 'accepted') return 'accepted';
+    return 'running';
+}
+
+function instructionForStatus(status: MeshAsyncRefineJobStatus): string {
+    if (status === 'accepted') return 'Refine job is accepted; wait for asyncRefineJobs or pendingCoordinatorEvents to report running/completed/failed.';
+    if (status === 'running') return 'Refine job is running; do not poll the ledger repeatedly. Watch asyncRefineJobs or pendingCoordinatorEvents for the terminal result.';
+    if (status === 'completed') return 'Refine job completed; inspect branch convergence and cleanup evidence before reporting final merge state.';
+    return 'Refine job failed; inspect result/finalBranchConvergenceState in mesh_task_history, fix the blocker, then rerun mesh_refine_node when ready.';
+}
+
+function mergeJob(
+    jobs: Map<string, MeshAsyncRefineJobSummary>,
+    patch: Partial<MeshAsyncRefineJobSummary> & { jobId?: string },
+): void {
+    const jobId = readString(patch.jobId);
+    if (!jobId) return;
+    const previous = jobs.get(jobId);
+    const status = patch.status || previous?.status || 'running';
+    const definedPatch = Object.fromEntries(
+        Object.entries(patch).filter(([, value]) => value !== undefined),
+    ) as Partial<MeshAsyncRefineJobSummary>;
+    jobs.set(jobId, {
+        ...previous,
+        ...definedPatch,
+        jobId,
+        status,
+        instruction: instructionForStatus(status),
+    });
+}
+
+export function buildMeshAsyncRefineJobs(args: {
+    meshId?: string;
+    ledgerEntries?: MeshLedgerEntry[];
+    pendingEvents?: PendingMeshCoordinatorEvent[];
+}): MeshAsyncRefineJobSummary[] {
+    const jobs = new Map<string, MeshAsyncRefineJobSummary>();
+
+    for (const entry of args.ledgerEntries || []) {
+        const payload = readRecord(entry.payload);
+        if (payload?.source !== 'refine_mesh_node_async_job') continue;
+        const refineJob = readRecord(payload.refineJob);
+        const result = readRecord(payload.result);
+        const finalState = readRecord(payload.finalBranchConvergenceState) || readRecord(result?.finalBranchConvergenceState);
+        const jobId = readString(refineJob?.jobId);
+        if (!jobId) continue;
+        const status = ledgerStatus(entry.kind, readString(refineJob?.status));
+        mergeJob(jobs, {
+            jobId,
+            interactionId: readString(refineJob?.interactionId),
+            status,
+            meshId: readString(refineJob?.meshId) || args.meshId,
+            nodeId: readString(refineJob?.nodeId) || entry.nodeId,
+            targetNodeId: readString(refineJob?.nodeId) || entry.nodeId,
+            targetDaemonId: readString(refineJob?.targetDaemonId),
+            workspace: readString(refineJob?.workspace),
+            branch: readString(result?.branch) || readString(finalState?.branch),
+            into: readString(result?.into) || readString(finalState?.baseBranch),
+            startedAt: readString(refineJob?.startedAt),
+            completedAt: readString(refineJob?.completedAt),
+            retryOfJobId: readString(refineJob?.retryOfJobId) || readString(payload.retryOfJobId),
+            lastLedgerKind: entry.kind,
+            lastUpdatedAt: entry.timestamp,
+        });
+    }
+
+    for (const event of args.pendingEvents || []) {
+        const metadata = readRecord(event.metadataEvent);
+        if (metadata?.source !== 'refine_mesh_node_async_job') continue;
+        const result = readRecord(metadata.result);
+        const finalState = readRecord(result?.finalBranchConvergenceState);
+        const jobId = readString(metadata.jobId);
+        if (!jobId) continue;
+        const status = eventStatus(event.event, readString(metadata.status));
+        mergeJob(jobs, {
+            jobId,
+            interactionId: readString(metadata.interactionId),
+            ...(status ? { status } : {}),
+            meshId: readString(metadata.meshId) || event.meshId || args.meshId,
+            nodeId: readString(metadata.nodeId) || event.nodeId,
+            targetNodeId: readString(metadata.nodeId) || event.nodeId,
+            targetDaemonId: readString(metadata.targetDaemonId),
+            workspace: readString(metadata.workspace) || event.workspace,
+            branch: readString(result?.branch) || readString(finalState?.branch),
+            into: readString(result?.into) || readString(finalState?.baseBranch),
+            startedAt: readString(metadata.startedAt),
+            completedAt: readString(metadata.completedAt),
+            retryOfJobId: readString(metadata.retryOfJobId),
+            lastEvent: event.event,
+            lastUpdatedAt: new Date(event.queuedAt).toISOString(),
+        });
+    }
+
+    return Array.from(jobs.values()).sort((a, b) => {
+        const aTime = new Date(a.lastUpdatedAt || a.startedAt || '').getTime();
+        const bTime = new Date(b.lastUpdatedAt || b.startedAt || '').getTime();
+        return (Number.isFinite(bTime) ? bTime : 0) - (Number.isFinite(aTime) ? aTime : 0);
+    });
+}

package/src/mesh/preview-freshness.ts

@@ -0,0 +1,118 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export type PreviewFreshnessStatus = 'fresh' | 'stale' | 'unknown' | 'not_configured';
+
+export interface PreviewFreshness {
+    status: PreviewFreshnessStatus;
+    lastPreviewCommit: string | null;
+    currentMainCommit: string | null;
+    currentMainCommitSource: 'origin/main' | 'HEAD' | 'unknown';
+    recordPath: string;
+    lastDeployedAt?: string;
+    lastTarget?: string;
+    previewVersion?: string;
+    targets: Record<'npm' | 'server' | 'web', {
+        commit: string | null;
+        deployedAt?: string;
+        status: PreviewFreshnessStatus;
+    }>;
+    nextAction: string;
+}
+
+const PREVIEW_DEPLOY_RECORD = '.adhdev/preview-deploy.json';
+
+function runGit(repoRoot: string, args: readonly string[]): string {
+    try {
+        return execFileSync('git', args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        }).trim();
+    } catch {
+        return '';
+    }
+}
+
+function readRecord(repoRoot: string): Record<string, unknown> | null {
+    const path = resolve(repoRoot, PREVIEW_DEPLOY_RECORD);
+    if (!existsSync(path)) return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed as Record<string, unknown>
+            : null;
+    } catch {
+        return null;
+    }
+}
+
+function normalizeCommit(value: unknown): string | null {
+    return typeof value === 'string' && /^[0-9a-f]{7,40}$/i.test(value.trim())
+        ? value.trim()
+        : null;
+}
+
+function readTargetFreshness(record: Record<string, unknown> | null, currentCommit: string | null): PreviewFreshness['targets'] {
+    const targets = record?.targets && typeof record.targets === 'object' && !Array.isArray(record.targets)
+        ? record.targets as Record<string, unknown>
+        : {};
+    const result = {} as PreviewFreshness['targets'];
+    for (const targetName of ['npm', 'server', 'web'] as const) {
+        const targetRecord = targets[targetName] && typeof targets[targetName] === 'object' && !Array.isArray(targets[targetName])
+            ? targets[targetName] as Record<string, unknown>
+            : {};
+        const commit = normalizeCommit(targetRecord.commit);
+        result[targetName] = {
+            commit,
+            deployedAt: typeof targetRecord.deployedAt === 'string' ? targetRecord.deployedAt : undefined,
+            status: commit && currentCommit ? (commit === currentCommit ? 'fresh' : 'stale') : 'unknown',
+        };
+    }
+    return result;
+}
+
+function readCurrentMainCommit(repoRoot: string): Pick<PreviewFreshness, 'currentMainCommit' | 'currentMainCommitSource'> {
+    const originMain = runGit(repoRoot, ['rev-parse', '--verify', 'origin/main^{commit}']);
+    if (originMain) {
+        return { currentMainCommit: originMain, currentMainCommitSource: 'origin/main' };
+    }
+    const head = runGit(repoRoot, ['rev-parse', '--verify', 'HEAD']);
+    if (head) {
+        return { currentMainCommit: head, currentMainCommitSource: 'HEAD' };
+    }
+    return { currentMainCommit: null, currentMainCommitSource: 'unknown' };
+}
+
+export function buildPreviewFreshness(repoRoot: string): PreviewFreshness {
+    const current = readCurrentMainCommit(repoRoot);
+    const record = readRecord(repoRoot);
+    const lastPreviewCommit = normalizeCommit(record?.lastPreviewCommit);
+    const targets = readTargetFreshness(record, current.currentMainCommit);
+    let status: PreviewFreshnessStatus = 'unknown';
+    let nextAction = 'Run npm run deploy:preview from the current main commit, then smoke preview.';
+
+    if (lastPreviewCommit && current.currentMainCommit) {
+        status = lastPreviewCommit === current.currentMainCommit ? 'fresh' : 'stale';
+        nextAction = status === 'fresh'
+            ? 'No preview deploy action needed.'
+            : 'Run npm run deploy:preview from origin/main, then smoke preview.';
+    } else if (!current.currentMainCommit) {
+        nextAction = 'Resolve the current main commit before judging preview freshness.';
+    }
+
+    return {
+        status,
+        lastPreviewCommit,
+        currentMainCommit: current.currentMainCommit,
+        currentMainCommitSource: current.currentMainCommitSource,
+        recordPath: PREVIEW_DEPLOY_RECORD,
+        lastDeployedAt: typeof record?.updatedAt === 'string' ? record.updatedAt : undefined,
+        lastTarget: typeof record?.target === 'string' ? record.target : undefined,
+        previewVersion: typeof record?.previewVersion === 'string' ? record.previewVersion : undefined,
+        targets,
+        nextAction,
+    };
+}

package/src/mesh/refine-config.ts

@@ -13,6 +13,7 @@ export interface RepoMeshRefineValidationCommandConfig {
     category?: MeshRefineValidationCategory;
     cwd?: string;
     timeoutMs?: number;
+    outputLimitBytes?: number;
     env?: Record<string, string>;
 }
 
@@ -44,6 +45,7 @@ export interface MeshRefineValidationCommandPlan {
     source: string;
     cwd?: string;
     timeoutMs?: number;
+    outputLimitBytes?: number;
     env?: Record<string, string>;
 }
 
@@ -110,6 +112,7 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
                             category: { enum: [...MESH_REFINE_VALIDATION_CATEGORIES, 'custom'] },
                             cwd: { type: 'string' },
                             timeoutMs: { type: 'number', minimum: 1000, maximum: 600000 },
+                            outputLimitBytes: { type: 'number', minimum: 1024, maximum: 1048576 },
                             env: { type: 'object', additionalProperties: { type: 'string' } },
                         },
                     },
@@ -127,6 +130,7 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
                             category: { enum: [...MESH_REFINE_VALIDATION_CATEGORIES, 'custom'] },
                             cwd: { type: 'string' },
                             timeoutMs: { type: 'number', minimum: 1000, maximum: 600000 },
+                            outputLimitBytes: { type: 'number', minimum: 1024, maximum: 1048576 },
                             env: { type: 'object', additionalProperties: { type: 'string' } },
                         },
                     },
@@ -136,7 +140,7 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
     },
 } as const;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
+export function isMeshConfigRecord(value: unknown): value is Record<string, unknown> {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
 
@@ -158,8 +162,8 @@ function validateCategory(value: unknown): MeshRefineValidationCategory | 'custo
         : 'custom';
 }
 
-function normalizeCommandConfig(entry: unknown, source: string): { command?: MeshRefineValidationCommandPlan; rejected?: Record<string, unknown> } {
-    if (!isRecord(entry) || typeof entry.command !== 'string') {
+export function normalizeMeshCommandConfig(entry: unknown, source: string): { command?: MeshRefineValidationCommandPlan; rejected?: Record<string, unknown> } {
+    if (!isMeshConfigRecord(entry) || typeof entry.command !== 'string') {
         return { rejected: { source, reason: 'validation command must be an object with a command string' } };
     }
 
@@ -189,7 +193,10 @@ function normalizeCommandConfig(entry: unknown, source: string): { command?: Mes
     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'))) {
+    if (entry.outputLimitBytes !== undefined && (typeof entry.outputLimitBytes !== 'number' || !Number.isFinite(entry.outputLimitBytes) || entry.outputLimitBytes < 1024 || entry.outputLimitBytes > 1048576)) {
+        return { rejected: { source, command: commandText, reason: 'outputLimitBytes must be between 1024 and 1048576' } };
+    }
+    if (entry.env !== undefined && (!isMeshConfigRecord(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' } };
     }
 
@@ -202,11 +209,14 @@ function normalizeCommandConfig(entry: unknown, source: string): { command?: Mes
             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> } : {}),
+            ...(typeof entry.outputLimitBytes === 'number' ? { outputLimitBytes: entry.outputLimitBytes } : {}),
+            ...(isMeshConfigRecord(entry.env) ? { env: entry.env as Record<string, string> } : {}),
         },
     };
 }
 
+const isRecord = isMeshConfigRecord;
+
 export function validateMeshRefineConfig(config: unknown, source = 'inline'): { valid: boolean; errors: string[]; bootstrapCommands: MeshRefineValidationCommandPlan[]; commands: MeshRefineValidationCommandPlan[]; rejectedCommands: Array<Record<string, unknown>> } {
     const errors: string[] = [];
     const bootstrapCommands: MeshRefineValidationCommandPlan[] = [];
@@ -226,14 +236,14 @@ export function validateMeshRefineConfig(config: unknown, source = 'inline'): {
     if (rawBootstrapCommands !== undefined && !Array.isArray(rawBootstrapCommands)) errors.push('validation.bootstrapCommands must be an array');
     if (Array.isArray(rawBootstrapCommands)) {
         rawBootstrapCommands.forEach((entry, index) => {
-            const normalized = normalizeCommandConfig(entry, `${source}:validation.bootstrapCommands[${index}]`);
+            const normalized = normalizeMeshCommandConfig(entry, `${source}:validation.bootstrapCommands[${index}]`);
             if (normalized.command) bootstrapCommands.push(normalized.command);
             if (normalized.rejected) rejectedCommands.push(normalized.rejected);
         });
     }
     if (Array.isArray(rawCommands)) {
         rawCommands.forEach((entry, index) => {
-            const normalized = normalizeCommandConfig(entry, `${source}:validation.commands[${index}]`);
+            const normalized = normalizeMeshCommandConfig(entry, `${source}:validation.commands[${index}]`);
             if (normalized.command) commands.push(normalized.command);
             if (normalized.rejected) rejectedCommands.push(normalized.rejected);
         });

package/src/mesh/worktree-bootstrap-config.ts

@@ -0,0 +1,234 @@
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve as pathResolve } from 'path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as yaml from 'js-yaml';
+import {
+    isMeshConfigRecord,
+    normalizeMeshCommandConfig,
+    type MeshRefineValidationCommandPlan,
+    type RepoMeshRefineValidationCommandConfig,
+} from './refine-config.js';
+
+export type WorktreeBootstrapStatus = 'ready' | 'running' | 'failed' | 'not_configured' | 'disabled' | 'stale';
+
+export interface RepoMeshWorktreeBootstrapConfig {
+    version: 1;
+    enabled?: boolean;
+    runOnClone?: boolean;
+    required?: boolean;
+    commands?: RepoMeshRefineValidationCommandConfig[];
+    staleInputs?: string[];
+}
+
+export interface WorktreeBootstrapState {
+    status: WorktreeBootstrapStatus;
+    required: boolean;
+    configSource?: string;
+    configSourceType?: 'repo_file' | 'mesh_policy' | 'unavailable' | 'invalid';
+    startedAt?: string;
+    completedAt?: string;
+    lastCommand?: string;
+    exitCode?: number | null;
+    error?: string;
+    commandsRun?: Array<Record<string, unknown>>;
+    staleInputs?: string[];
+}
+
+export interface WorktreeBootstrapConfigLoadResult {
+    config?: RepoMeshWorktreeBootstrapConfig;
+    source: string;
+    sourceType: 'repo_file' | 'mesh_policy' | 'unavailable' | 'invalid';
+    path?: string;
+    error?: string;
+}
+
+export const MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS = [
+    '.adhdev/worktree_bootstrap.json',
+    '.adhdev/worktree_bootstrap.yaml',
+    '.adhdev/worktree_bootstrap.yml',
+    '.adhdev/worktree-bootstrap.json',
+    '.adhdev/worktree-bootstrap.yaml',
+    '.adhdev/worktree-bootstrap.yml',
+];
+
+export const MESH_WORKTREE_BOOTSTRAP_CONFIG_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'ADHDev Repo Mesh Worktree Bootstrap Config',
+    type: 'object',
+    additionalProperties: false,
+    required: ['version'],
+    properties: {
+        version: { const: 1 },
+        enabled: { type: 'boolean', default: true },
+        runOnClone: { type: 'boolean', default: true },
+        required: { type: 'boolean', default: true },
+        staleInputs: { type: 'array', maxItems: 16, items: { type: 'string', minLength: 1 } },
+        commands: {
+            type: 'array',
+            minItems: 1,
+            maxItems: 4,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['command'],
+                properties: {
+                    command: { type: 'string', minLength: 1 },
+                    args: { type: 'array', items: { type: 'string' } },
+                    category: { enum: ['typecheck', 'test', 'lint', 'build', 'custom'] },
+                    cwd: { type: 'string' },
+                    timeoutMs: { type: 'number', minimum: 1000, maximum: 600000 },
+                    outputLimitBytes: { type: 'number', minimum: 1024, maximum: 1048576 },
+                    env: { type: 'object', additionalProperties: { type: 'string' } },
+                },
+            },
+        },
+    },
+} as const;
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_OUTPUT_LIMIT_BYTES = 128 * 1024;
+const OUTPUT_SUMMARY_CHARS = 2_000;
+
+function parseConfigText(path: string, text: string): unknown {
+    if (/\.json$/i.test(path)) return JSON.parse(text);
+    return yaml.load(text);
+}
+
+function truncateOutput(value: unknown): string {
+    const text = typeof value === 'string' ? value : value == null ? '' : String(value);
+    if (text.length <= OUTPUT_SUMMARY_CHARS) return text;
+    return `${text.slice(0, OUTPUT_SUMMARY_CHARS)}\n[truncated ${text.length - OUTPUT_SUMMARY_CHARS} chars]`;
+}
+
+export function validateMeshWorktreeBootstrapConfig(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 (!isMeshConfigRecord(config)) return { valid: false, errors: ['config must be an object'], commands, rejectedCommands };
+    if (config.version !== 1) errors.push('version must be 1');
+    if (config.enabled !== undefined && typeof config.enabled !== 'boolean') errors.push('enabled must be a boolean when provided');
+    if (config.runOnClone !== undefined && typeof config.runOnClone !== 'boolean') errors.push('runOnClone must be a boolean when provided');
+    if (config.required !== undefined && typeof config.required !== 'boolean') errors.push('required must be a boolean when provided');
+    if (config.staleInputs !== undefined && (!Array.isArray(config.staleInputs) || !config.staleInputs.every(input => typeof input === 'string' && input.trim()))) {
+        errors.push('staleInputs must be an array of non-empty strings when provided');
+    }
+    if (config.commands !== undefined && !Array.isArray(config.commands)) errors.push('commands must be an array');
+    if (Array.isArray(config.commands)) {
+        config.commands.forEach((entry, index) => {
+            const normalized = normalizeMeshCommandConfig(entry, `${source}:commands[${index}]`);
+            if (normalized.command) commands.push(normalized.command);
+            if (normalized.rejected) rejectedCommands.push(normalized.rejected);
+        });
+    }
+    if (config.enabled !== false && config.runOnClone !== false && commands.length === 0) errors.push('commands must contain at least one command when bootstrap is enabled');
+    if (rejectedCommands.length) errors.push('one or more bootstrap commands are invalid');
+    return { valid: errors.length === 0, errors, commands, rejectedCommands };
+}
+
+export function loadMeshWorktreeBootstrapConfig(mesh: any, workspace: string): WorktreeBootstrapConfigLoadResult {
+    const inline = mesh?.worktreeBootstrapConfig || mesh?.policy?.worktreeBootstrapConfig || mesh?.policy?.worktreeBootstrap;
+    if (inline !== undefined) {
+        const validation = validateMeshWorktreeBootstrapConfig(inline, 'mesh.policy.worktreeBootstrapConfig');
+        if (!validation.valid) return { source: 'mesh.policy.worktreeBootstrapConfig', sourceType: 'invalid', error: String(validation.rejectedCommands[0]?.reason || validation.errors.join('; ')) };
+        return { config: inline as RepoMeshWorktreeBootstrapConfig, source: 'mesh.policy.worktreeBootstrapConfig', sourceType: 'mesh_policy' };
+    }
+    for (const relative of MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS) {
+        const configPath = join(workspace, relative);
+        if (!existsSync(configPath)) continue;
+        try {
+            const parsed = parseConfigText(configPath, readFileSync(configPath, 'utf-8'));
+            const validation = validateMeshWorktreeBootstrapConfig(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 RepoMeshWorktreeBootstrapConfig, 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 worktree bootstrap config found. Checked: ${MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS.join(', ')}` };
+}
+
+export async function runMeshWorktreeBootstrap(mesh: any, workspace: string): Promise<WorktreeBootstrapState> {
+    const loaded = loadMeshWorktreeBootstrapConfig(mesh, workspace);
+    if (!loaded.config) {
+        return { status: 'not_configured', required: false, configSource: loaded.source, configSourceType: loaded.sourceType, error: loaded.error };
+    }
+    const required = loaded.config.required !== false;
+    if (loaded.config.enabled === false || loaded.config.runOnClone === false) {
+        return { status: 'disabled', required, configSource: loaded.path || loaded.source, configSourceType: loaded.sourceType };
+    }
+    const validation = validateMeshWorktreeBootstrapConfig(loaded.config, loaded.source);
+    if (!validation.valid) {
+        return { status: 'failed', required, configSource: loaded.path || loaded.source, configSourceType: 'invalid', error: String(validation.rejectedCommands[0]?.reason || validation.errors.join('; ')), commandsRun: [] };
+    }
+
+    const execFileAsync = promisify(execFile);
+    const state: WorktreeBootstrapState = {
+        status: 'running',
+        required,
+        configSource: loaded.path || loaded.source,
+        configSourceType: loaded.sourceType,
+        startedAt: new Date().toISOString(),
+        commandsRun: [],
+        staleInputs: loaded.config.staleInputs,
+    };
+    for (const command of validation.commands) {
+        const cwd = command.cwd ? pathResolve(workspace, command.cwd) : workspace;
+        const startedAt = Date.now();
+        state.lastCommand = command.displayCommand;
+        try {
+            const result = await execFileAsync(command.command, command.args, {
+                cwd,
+                encoding: 'utf8',
+                timeout: command.timeoutMs || DEFAULT_TIMEOUT_MS,
+                maxBuffer: command.outputLimitBytes || DEFAULT_OUTPUT_LIMIT_BYTES,
+                env: { ...process.env, CI: process.env.CI || '1', ...(command.env || {}) },
+                windowsHide: true,
+            });
+            state.commandsRun?.push({
+                command: command.command,
+                args: command.args,
+                displayCommand: command.displayCommand,
+                category: command.category,
+                source: command.source,
+                cwd,
+                passed: true,
+                durationMs: Date.now() - startedAt,
+                exitCode: 0,
+                stdout: truncateOutput(result.stdout),
+                stderr: truncateOutput(result.stderr),
+            });
+        } catch (error: any) {
+            const exitCode = typeof error?.code === 'number' ? error.code : null;
+            state.status = 'failed';
+            state.exitCode = exitCode;
+            state.error = error?.message || String(error);
+            state.completedAt = new Date().toISOString();
+            state.commandsRun?.push({
+                command: command.command,
+                args: command.args,
+                displayCommand: command.displayCommand,
+                category: command.category,
+                source: command.source,
+                cwd,
+                passed: false,
+                durationMs: Date.now() - startedAt,
+                exitCode,
+                signal: typeof error?.signal === 'string' ? error.signal : null,
+                timedOut: error?.killed === true || /timed out/i.test(String(error?.message || '')),
+                stdout: truncateOutput(error?.stdout),
+                stderr: truncateOutput(error?.stderr || error?.message),
+            });
+            return state;
+        }
+    }
+    state.status = 'ready';
+    state.exitCode = 0;
+    state.completedAt = new Date().toISOString();
+    return state;
+}

package/src/repo-mesh-types.ts

@@ -290,6 +290,20 @@ export interface LocalMeshNodeEntry {
     worktreeBranch?: string;
     /** Node ID this worktree was cloned from */
     clonedFromNodeId?: string;
+    /** Repo-local preparation result for ADHDev-created worktree nodes. */
+    worktreeBootstrap?: {
+        status: 'ready' | 'running' | 'failed' | 'not_configured' | 'disabled' | 'stale';
+        required?: boolean;
+        configSource?: string;
+        configSourceType?: string;
+        startedAt?: string;
+        completedAt?: string;
+        lastCommand?: string;
+        exitCode?: number | null;
+        error?: string;
+        commandsRun?: Array<Record<string, unknown>>;
+        staleInputs?: string[];
+    };
     /** Optional associated/external repos configured as node metadata. */
     relatedRepos?: RepoMeshRelatedRepo[];
     role?: RepoMeshDaemonRole;
@@ -361,6 +375,9 @@ export interface RepoMeshNodeStatus {
     activeSessionDetails?: RepoMeshSessionStatus[];
     providerPriority?: string[];
     launchReady?: boolean;
+    worktreeBootstrap?: LocalMeshNodeEntry['worktreeBootstrap'];
+    launchBlockedReason?: string;
+    launchBlockedMessage?: string;
     lastSeenAt?: string;
     updatedAt?: string;
     connection?: RepoMeshPeerConnectionStatus;